[libcamera-devel] [RFC 6/7] libcamera: properties: Define 'lens' properties

Fri Dec 27 17:40:22 CET 2019

Hi Jacopo,

On 19.12.2019 14:45, Jacopo Mondi wrote:
> Hello Andrey,
>     thanks for the feedback
> 
> On Wed, Dec 18, 2019 at 10:41:53PM +0300, Andrey Konovalov wrote:
>> Hi Jacopo,
>>
>> Nice to see how fast the areas which libcamera covers grow. Fantastic work!
>>
> 
> Great, as said on IRC the definition of controls and properties is one
> of the area where valuable feedback is mostly needed! Thanks for
> looking into this
> 
>> Just I am somewhat confused with the terminology used.
>> Could you please elaborate a bit on that?
>>
>> As considerable part of libcamera developers might not be familiar enough with optics and photography,
>> guess it would make a lot of sense to create, or to refer to some existing document which would provide
>> enough introductory type information on all that stuff?
>>
> 
> I wish I had found any comprehensive documentation. Unfortunately
> information are spread on the web, with Wikipedia being a good source
> for the basic concepts. I mostly refer to the Android
> metadata documentation, but it of course assume the reader is somehow
> already educated on the topics.
> 
> Also please remember this properties are meant to be filled up by
> device vendors and integrators and only very advanced application
> might need to know something about the optical characteristics of a
> camera to tune accordingly.

OK

>> On 18.12.2019 17:50, Jacopo Mondi wrote:
>>> Define properties that describe the optical characteristics of the image
>>> sensor.
>>
>> Afraid the 'lens' properties aren't the optical characteristics of the image sensor.
>> The same image sensor can be paired with a bunch of different lenses..
>> (the family of ov5647-based cameras for RPi by waveshare, DSLRs, etc etc)
>>
> 
> Right, I used 'image sensor' where most probably 'camera module' is somehow
> more appropriate, as it refers to the sensor itself and it packaging,
> including the lens.

'camera module' looks OK for me.

>>> Signed-off-by: Jacopo Mondi <jacopo at jmondi.org>
>>> ---
>>>    src/libcamera/property_ids.yaml | 34 +++++++++++++++++++++++++++++++++
>>>    1 file changed, 34 insertions(+)
>>>
>>> diff --git a/src/libcamera/property_ids.yaml b/src/libcamera/property_ids.yaml
>>> index 9e2333cb7206..fdadfb8b1da4 100644
>>> --- a/src/libcamera/property_ids.yaml
>>> +++ b/src/libcamera/property_ids.yaml
>>> @@ -208,4 +208,38 @@ controls:
>>>            The range of supported ISO sensitivities, as documented by the
>>>            ISO 12232:2006 standard
>>> +  - LensApertures:
>>> +      type: float
>>> +      compound: true
>>> +      description: |
>>> +        The available lens apertures, expressed as f numbers (the ratio between
>>> +        the lens focal distance and the diameter of the pupil aperture).
>>> +
>>> +        If the sensor
>>
>> - s/sensor/lens ?
>>
> 
> camera module ?

Yes, this would be fine.

>>> has a fixed aperture, the property transports a single
>>> +        value.
>>> +
>>> +  - LensFocalDistance:
>>> +      type: float
>>> +      compound: true
>>> +      description: |
>>> +        The available focal length distances, expressed in millimeters.
>>
>> Sorry, this sounds confusing.
>> The "focal length" is the characteristic of the lens: https://en.wikipedia.org/wiki/Focal_length
>> If this is what you meant, then the property name should be "LensFocalLength", and the description should use
>> "available focal lengths" (no "distances" here).
>>
>> "Focus distance" is the distance at which the lens is currently focused at.
> 
> You're right! I just checked and Android uses "length" and not
> distance to refer to the same concept. I'll change this, thanks.
> 
>>
>>> +
>>> +        If the sensor is featured with a movable lens mechanism this property
>>> +        reports the focal lengths associated with each discrete step.
>>
>> - this is a zoom lens, right?
>>
> 
> Movable lenses are indeed used to implement mechanical zoom, but also
> to change the focus distance I guess..

Yes, both zooming and focusing are implemented by moving an element (== simple lens) or a group of elements.

Just as the above sentence says "reports the *focal lengths*" then it is about zooming, not focusing.
LensFocalLength property is exactly for that purpose.

>>> For
>>> +        sensor with fixed-focus lenses
>>
>> "fixed-focus" means that the focus, the distance at which the lens is focused, can't be changed
>> (vs "auto-focus" or "manual focus").
>> So "fixed-focus" shouldn't be mentioned here.
>>
>>> , a single focal length should be instead
>>> +        reported.
>> - this is exactly the term used at https://imaging.nikon.com/lineup/lens/f-mount/
>>    Other common names are "fixed focal length lens" or "prime lens".
>>    (and the "fixed-focus" is completely different story)
>>
> 
> Ok, so s/fixed-focus/single focal length ?

Right.

> What I wanted to convey here is "movable lens" vs "non movable lens" :)

"movable lens" is too vague term imho...
As I said, moving an element (or elements) of a lens could be used to zoom it,
or to focus it (but not the same element(s) for the both tasks).

>>> +
>>> +  - LensHyperfocalDistance:
>>> +      type: float
>>> +      compound: true
>>> +      description: |
>>> +        The hyperfocal distance of the sensor.
>>
>> s/sensor/lens ?
>>
>>> The property is particularly
>>> +        meaningful for fixed-focus devices.
>>> +
>>> +  - LensMinimumFocalDistance:
>>
>> The correct term which matches the description is "minimum focus distance".
>> See e.g.
>> https://imaging.nikon.com/lineup/lens/f-mount/zoom/normalzoom/af-p_dx_18-55mmf_35-56g/spec.htm
>>
>>> +      type: float
>>> +      description: |
>>> +        The shortest distance in millimeters from the lens surface in which an
>>> +        object could be brought into sharp focus.
>>
>> It might be not very precise (the "from the lens surface" part), but otherwise good description.
> 
> Kudos to Android developers here from where I took the last part of
> the description.
> 
> On the "from the lens surface": the Nikon website uses the term "focal
> plan". Might it be more appropriate ?

Not to confuse people, I would probably drop completely the part which explains where the focus distance is
measured from :)

Otherwise "from focal plane" is correct. Just the people who know what "focal plane" is, know where the focus
distance is measured from anyway.

So something like "The shortest distance in millimeters at which an object could be brought into sharp focus"
should work fine for the both groups of people.

Thanks,
Andrey

>>
>>> +
>>>    ...
>>>
>>
>> Will continue in the reply to the next patch.
>>
> 
> Thanks again!
> 
>>
>> Thanks,
>> Andrey
>> _______________________________________________
>> libcamera-devel mailing list
>> libcamera-devel at lists.libcamera.org
>> https://lists.libcamera.org/listinfo/libcamera-devel