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

[Jacopo Mondi]

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.

> 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.

> > 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 ?

> > 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..

> > 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 ?

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

> > +
> > +  - 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 ?

>
> > +
> >   ...
> >
>
> 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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://lists.libcamera.org/pipermail/libcamera-devel/attachments/20191219/483c0cec/attachment.sig>