[1/2] Documentation: add glossary page

25614 diff mbox series

The page currently contains acronyms and abbreviations commonly used
troughout libcamera and related projects, but can be expanded to also
explain technical terms.

Signed-off-by: Walter Werner Schneider <contact@schnwalter.eu>
---
 Documentation/glossary.rst | 158 +++++++++++++++++++++++++++++++++++++++++++++
 Documentation/index.rst    |   1 +
 Documentation/meson.build  |   1 +
 3 files changed, 160 insertions(+)

Hi Walter,

On Fri, Dec 19, 2025 at 09:06:30PM +0200, Walter Werner Schneider wrote:
> The page currently contains acronyms and abbreviations commonly used
> troughout libcamera and related projects, but can be expanded to also
> explain technical terms.

Thanks, as said on irc I'm in two minds about this.

On one side, I clearly understand it might be helpful to newcomers to
navigate the code base and documentation. On the other hand, most
concepts here are not libcamera specific, and just providing an
explanation for the acronym might not be sufficient to clarify the
concepts in full.

On some terms, specifically the ones that refers to standards, just
spelling the names out might even be confusing. See below

>
> Signed-off-by: Walter Werner Schneider <contact@schnwalter.eu>
> ---
>  Documentation/glossary.rst | 158 +++++++++++++++++++++++++++++++++++++++++++++
>  Documentation/index.rst    |   1 +
>  Documentation/meson.build  |   1 +
>  3 files changed, 160 insertions(+)
>
> diff --git a/Documentation/glossary.rst b/Documentation/glossary.rst
> new file mode 100644
> index 0000000000000000000000000000000000000000..d8679a1148d2b520c301891745e78f5033b1235d
> --- /dev/null
> +++ b/Documentation/glossary.rst
> @@ -0,0 +1,158 @@
> +.. SPDX-License-Identifier: CC-BY-SA-4.0
> +
> +Glossary
> +========
> +
> +This document contains a glossary of technical terms, acronyms and
> +abbreviations commonly used throughout the libcamera documentation and
> +codebase.
> +
> +.. Please keep the glossary entries in alphabetical order.
> +
> +.. glossary::
> +   :sorted:
> +
> +   3A
> +      Refers to the :term:`AE`, :term:`AF` and :term:`AWB`.
> +
> +   AE
> +      Auto Exposure
> +
> +   AEC
> +      Auto Exposure Control
> +
> +   AEGC
> +      Refers to :term:`AEC` and :term:`AGC`
> +
> +   AF
> +      Auto Focus
> +
> +   AFC
> +      Auto Focus Control
> +
> +   AGC
> +      Auto Gain Control
> +
> +   ALSC
> +      Auto Lens Shading Correction

I think the 'A' here stands for "Adaptive", at least in the RPi
implementation ?

> +
> +   AWB
> +      Auto White Balance
> +
> +   BLC
> +      Black Level Correction
> +
> +   BLS
> +      Black Level Subtraction

See, one might wonder what the difference is between the two, while
they're actually two different names for the same algorithm

> +
> +   CAC
> +      Chromatic Aberration Correction
> +
> +   CC
> +      Color Correction
> +
> +   CCI
> +      Camera Control Interface

This is a MIPI standard, and if we want to define it, we should give a
reference to the standard. CCI is actually part of the CCS
specification if I'm not mistaken ?

> +
> +   CCM
> +      Color Correction Matrix
> +
> +   CCS
> +      Camera Command Set

That's a MIPI standard. Should we say so ?

> +
> +   CDAF
> +      Contrast Detection Auto Focus
> +
> +   CDN
> +      Color Denoise
> +
> +   CIF
> +      Camera Interface

Is CIF a Rockchip specific name ?

> +
> +   CPROC
> +      Color Processing
> +
> +   CSC
> +      Color Space Conversion
> +
> +   CSI
> +      Camera Serial Interface

Eh. CSI is probably the most overloaded acronym of all. Some vendors
(amlogic ?) have a parallel interface named CSI..

> +
> +   CSI-2
> +      Camera Serial Interface 2

A mipi standard indeed

> +
> +   DMA
> +      Direct Memory Access

Is this really related to cameras ?

> +
> +   DPC
> +      Defective Pixel Correction
> +
> +   DPCC
> +      Defective Pixel Cluster Correction
> +
> +   DPF
> +      Denoise Pre-Filter
> +
> +   FB
> +      Frame Buffer

One might wonder what "Frame buffer" means precisely. I think we should
either explain it in more length or drop it

> +
> +   FourCC
> +      Four Character Code, abstract identifier that uniquely defines
> +      a :term:`FB` pixel format.

What's a pixel format then ? :)

> +
> +   GEQ
> +      Green Equalisation
> +
> +   GSL
> +      Gamma Sensor Linearization
> +
> +   GOC
> +      Gamma Out Curve
> +
> +   HAL
> +      Hardware Abstraction Layer

This is an androidism, but it is used by other OSes and frameworks as
well.. Not sure it has anything to do with imaging though

> +
> +   HDR
> +      High Dynamic Range
> +
> +   IPA
> +      Image Processing Algorithm

That's indeed a libcamera-specific term

> +
> +   IPC
> +      Inter-process communication

Not really related to imaging

> +
> +   IPU3
> +      Intel 3rd generation Image Processing Unit
> +

Why IPU3 and not all the other ISPs names ? I mean, I understand it
might be useful to quickly know what it means, but ... not sure it's
the right place here

> +   ISP
> +      Image Signal Processor
> +
> +   NLL
> +      Noise Level Lookup
> +
> +   LSC
> +      Lens Shading Correction
> +
> +   PDAF
> +      Phase Detection Auto Focus
> +
> +   SDN
> +      Spatial Denoise
> +
> +   TDN
> +      Temporal Denoise
> +
> +   UVC
> +      USB Video Class
> +
> +   V4L2
> +      Video for Linux 2
> +
> +   VIMC
> +      Virtual Media Controller

That's just the name of a driver in Linux...

> +
> +   WBG
> +      White Balance Gain

First time I see this one :)

> +
> +   WDR
> +      Wide Dynamic Range

I'm not sure.. Again, I understand why it might be useful, but it
feels there are a lot terms there which either refers to standards,
informal acronyms, driver names.. it's a bit mixed.. maybe it's just
what a glossary should look like.

In general, I'm a bit skeptical on the idea of trying to create
definitions for things 'bigger' than libcamera. It's not the job of
a software library to provide a knowledge base for imaging concepts
and technologies, as the risk of providing incomplete/misleading
information is higher than the benefit. Here we have just terms, so
the risk of mis-guiding people is low, but still it feels
underspecified for some entries (standards in particular).

What do the others think ?


> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 8109b4295c92d722a2a215b97fd50af2f9babb9c..2eb0b894f1139d43389b2b450be003b054f6e335 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -21,6 +21,7 @@
>
>     Contribute <contributing>
>     Getting Started <getting-started>
> +   Glossary <glossary>
>     Camera Sensor Model <camera-sensor-model>
>     IPA Writer's guide <guides/ipa>
>     libcamera Architecture <libcamera_architecture>
> diff --git a/Documentation/meson.build b/Documentation/meson.build
> index 51899c19c1667c8ac07c6e7776e1faaa14915e20..158825e398c48f41fbfebe4b4ac7afecb1a5b2a2 100644
> --- a/Documentation/meson.build
> +++ b/Documentation/meson.build
> @@ -161,6 +161,7 @@ if sphinx.found()
>          'guides/ipa.rst',
>          'guides/pipeline-handler.rst',
>          'guides/tracing.rst',
> +        'glossary.rst',
>          'index.rst',
>          'internal-api/index.rst',
>          'introduction.rst',
>
> --
> 2.51.1
>

Hi Walter,

Thank you for working on this.

Quoting Jacopo Mondi (2025-12-23 11:02:09)
> Hi Walter,
> 
> On Fri, Dec 19, 2025 at 09:06:30PM +0200, Walter Werner Schneider wrote:
> > The page currently contains acronyms and abbreviations commonly used
> > troughout libcamera and related projects, but can be expanded to also
> > explain technical terms.
> 
> Thanks, as said on irc I'm in two minds about this.

I think this is a positive and helpful contribution.

> On one side, I clearly understand it might be helpful to newcomers to
> navigate the code base and documentation. On the other hand, most
> concepts here are not libcamera specific, and just providing an
> explanation for the acronym might not be sufficient to clarify the
> concepts in full.

It might not be fully describing the concepts, but it's at least more
clearly expanding the definition to /our/ usage. As you stated below -
sometimes TLAs (The literal abbreviations) can be MUA
(Multi-use-acronyms) and at the very least a DUI (defined ultimate
intent) can prevent them from being misconstrued.


> On some terms, specifically the ones that refers to standards, just
> spelling the names out might even be confusing. See below

I'm not sure I understand this how can spelling out the names be more
confusing than just leaving an ambiguity ?

> 
> >
> > Signed-off-by: Walter Werner Schneider <contact@schnwalter.eu>
> > ---
> >  Documentation/glossary.rst | 158 +++++++++++++++++++++++++++++++++++++++++++++
> >  Documentation/index.rst    |   1 +
> >  Documentation/meson.build  |   1 +
> >  3 files changed, 160 insertions(+)
> >
> > diff --git a/Documentation/glossary.rst b/Documentation/glossary.rst
> > new file mode 100644
> > index 0000000000000000000000000000000000000000..d8679a1148d2b520c301891745e78f5033b1235d
> > --- /dev/null
> > +++ b/Documentation/glossary.rst
> > @@ -0,0 +1,158 @@
> > +.. SPDX-License-Identifier: CC-BY-SA-4.0
> > +
> > +Glossary
> > +========
> > +
> > +This document contains a glossary of technical terms, acronyms and
> > +abbreviations commonly used throughout the libcamera documentation and
> > +codebase.
> > +
> > +.. Please keep the glossary entries in alphabetical order.
> > +
> > +.. glossary::
> > +   :sorted:
> > +
> > +   3A
> > +      Refers to the :term:`AE`, :term:`AF` and :term:`AWB`.
> > +
> > +   AE
> > +      Auto Exposure
> > +
> > +   AEC
> > +      Auto Exposure Control
> > +
> > +   AEGC
> > +      Refers to :term:`AEC` and :term:`AGC`
> > +
> > +   AF
> > +      Auto Focus
> > +
> > +   AFC
> > +      Auto Focus Control
> > +
> > +   AGC
> > +      Auto Gain Control
> > +
> > +   ALSC
> > +      Auto Lens Shading Correction
> 
> I think the 'A' here stands for "Adaptive", at least in the RPi
> implementation ?

Yes, I think I recall that too.

> 
> > +
> > +   AWB
> > +      Auto White Balance
> > +
> > +   BLC
> > +      Black Level Correction
> > +
> > +   BLS
> > +      Black Level Subtraction
> 
> See, one might wonder what the difference is between the two, while
> they're actually two different names for the same algorithm


That can easily be solved with ", equivalent to :term:`BLC`" or such ?

I think it's helpful to document that we expect these terms to mean the
same thing ultimately.

> 
> > +
> > +   CAC
> > +      Chromatic Aberration Correction
> > +
> > +   CC
> > +      Color Correction

Ohh that's an interesting one. I don't recall seeing that used.

git grep " CC" | grep -Ev "CC0|CCM|CCS|CC_|CC-"
src/ipa/libipa/colours.cpp: * locus in order to calculate the CCT in terms of chromaticity coordinates.
src/ipa/libipa/colours.cpp:	/* Calculate CCT */
utils/raspberrypi/ctt/ctt.py:        if image is greyscale then CCm makes no sense


I think I'd drop this one. I don't think CC should be used on it's own,
and the only match I see above is CCm ? which is just CCM really.


> > +
> > +   CCI
> > +      Camera Control Interface
> 
> This is a MIPI standard, and if we want to define it, we should give a
> reference to the standard. CCI is actually part of the CCS
> specification if I'm not mistaken ?


I don't actually see this in the libcamera tree. So I'm not sure if we
should define it (yet?) but if we do then yes we should clearly point
that when we say CCI we mean the MIPI-CCI specification.

> 
> > +
> > +   CCM
> > +      Color Correction Matrix
> > +
> > +   CCS
> > +      Camera Command Set
> 
> That's a MIPI standard. Should we say so ?

include/linux/drm_fourcc.h uses CCS for "Color Control Surfaces". Which
is unrelated to our usages, but in the project. I wonder if we should
clear that up here somehow.

But indeed we should reference that we mean the MIPI CCS. This is where
I think adding a bit more text than just the expansion can help.


> 
> > +
> > +   CDAF
> > +      Contrast Detection Auto Focus
> > +
> > +   CDN
> > +      Color Denoise
> > +
> > +   CIF
> > +      Camera Interface
> 
> Is CIF a Rockchip specific name ?

I think so:

RKISP1_CIF_ISP_DPCC_MODE_STAGE1_ENABLE

So it ends up frequently used in the code base for src/ipa/rkisp1/.
Perhaps we should state that.


> 
> > +
> > +   CPROC
> > +      Color Processing
> > +
> > +   CSC
> > +      Color Space Conversion
> > +
> > +   CSI
> > +      Camera Serial Interface
> 
> Eh. CSI is probably the most overloaded acronym of all. Some vendors
> (amlogic ?) have a parallel interface named CSI..

I think CSI should point to CSI-2 which is what it actually refers to
for our use cases. Or a bit like a wikipedia:
  - https://en.wikipedia.org/wiki/CSI

Perhaps it should say:

 "CSI may refer to :term:`CSI-2` or :term:`CSI(Amlogic)`"

Or something like that ?
 

> > +
> > +   CSI-2
> > +      Camera Serial Interface 2
> 
> A mipi standard indeed


> 
> > +
> > +   DMA
> > +      Direct Memory Access
> 
> Is this really related to cameras ?

'git grep -i DMA' certainly implies it is related to libcamera.

> > +
> > +   DPC
> > +      Defective Pixel Correction
> > +
> > +   DPCC
> > +      Defective Pixel Cluster Correction
> > +
> > +   DPF
> > +      Denoise Pre-Filter
> > +
> > +   FB
> > +      Frame Buffer
> 
> One might wonder what "Frame buffer" means precisely. I think we should
> either explain it in more length or drop it
> 
> > +
> > +   FourCC
> > +      Four Character Code, abstract identifier that uniquely defines
> > +      a :term:`FB` pixel format.
> 
> What's a pixel format then ? :)
> 
> > +
> > +   GEQ
> > +      Green Equalisation
> > +
> > +   GSL
> > +      Gamma Sensor Linearization
> > +
> > +   GOC
> > +      Gamma Out Curve
> > +
> > +   HAL
> > +      Hardware Abstraction Layer
> 
> This is an androidism, but it is used by other OSes and frameworks as
> well.. Not sure it has anything to do with imaging though

I don't think this is an Androidism. The term 'HAL' as 'hardware
abstraction layer' has been around long before Android was born. Or I've
been around too long. One of those....

But at least here 'git grep -wi HAL' does show this to only come up in
the Android components, so we really use it as the 'Android Camera HAL'.

> 
> > +
> > +   HDR
> > +      High Dynamic Range
> > +
> > +   IPA
> > +      Image Processing Algorithm
> 
> That's indeed a libcamera-specific term
> 
> > +
> > +   IPC
> > +      Inter-process communication
> 
> Not really related to imaging

Yet we definitely don't mean "Infection Prevention and Control".

> 
> > +
> > +   IPU3
> > +      Intel 3rd generation Image Processing Unit
> > +
> 
> Why IPU3 and not all the other ISPs names ? I mean, I understand it
> might be useful to quickly know what it means, but ... not sure it's
> the right place here

Perhaps we should add others then?

RKISP1 might be good to expand here especially as we can say

  RKISP1
    The Rockchip ISP driver component, which supports several ISP
    implementations including the RK3399 and the NXP i.MX8MP.


> > +   ISP
> > +      Image Signal Processor
> > +
> > +   NLL
> > +      Noise Level Lookup
> > +

I think we just lost alphabetical ordering here ;-)

> > +   LSC
> > +      Lens Shading Correction
> > +
> > +   PDAF
> > +      Phase Detection Auto Focus
> > +
> > +   SDN
> > +      Spatial Denoise
> > +
> > +   TDN
> > +      Temporal Denoise
> > +
> > +   UVC
> > +      USB Video Class
> > +
> > +   V4L2
> > +      Video for Linux 2
> > +
> > +   VIMC
> > +      Virtual Media Controller
> 
> That's just the name of a driver in Linux...

I think we should say that - we use it for testing.

> 
> > +
> > +   WBG
> > +      White Balance Gain
> 
> First time I see this one :)
> 
> > +
> > +   WDR
> > +      Wide Dynamic Range
> 
> I'm not sure.. Again, I understand why it might be useful, but it
> feels there are a lot terms there which either refers to standards,
> informal acronyms, driver names.. it's a bit mixed.. maybe it's just
> what a glossary should look like.

Assuming doxygen will handle all the :term:`TLA` links here - I don't
think the mix matters. It's just the database to store all of the
defintions or expansions of any term we use which merits a bit of
context. And if a user has come in and said "I don't know what this term
refers to in the context of libcamera" that would automatically make it
appropriate to explain in my view.



> In general, I'm a bit skeptical on the idea of trying to create
> definitions for things 'bigger' than libcamera. It's not the job of
> a software library to provide a knowledge base for imaging concepts
> and technologies, as the risk of providing incomplete/misleading
> information is higher than the benefit. Here we have just terms, so
> the risk of mis-guiding people is low, but still it feels
> underspecified for some entries (standards in particular).
> 
> What do the others think ?

It's not the job of libcamera to teach people about DMA ... but it's the
job of *any documentation* to clearly reference and define all of it's
terms. So I honestly think this is a good idea.

I'd even go a step further and put a short brief (or external link to
further information like wikipedia) to each term. But I haven't checked
how it will look in the output yet.

> 
> 
> > diff --git a/Documentation/index.rst b/Documentation/index.rst
> > index 8109b4295c92d722a2a215b97fd50af2f9babb9c..2eb0b894f1139d43389b2b450be003b054f6e335 100644
> > --- a/Documentation/index.rst
> > +++ b/Documentation/index.rst
> > @@ -21,6 +21,7 @@
> >
> >     Contribute <contributing>
> >     Getting Started <getting-started>
> > +   Glossary <glossary>
> >     Camera Sensor Model <camera-sensor-model>
> >     IPA Writer's guide <guides/ipa>
> >     libcamera Architecture <libcamera_architecture>
> > diff --git a/Documentation/meson.build b/Documentation/meson.build
> > index 51899c19c1667c8ac07c6e7776e1faaa14915e20..158825e398c48f41fbfebe4b4ac7afecb1a5b2a2 100644
> > --- a/Documentation/meson.build
> > +++ b/Documentation/meson.build
> > @@ -161,6 +161,7 @@ if sphinx.found()
> >          'guides/ipa.rst',
> >          'guides/pipeline-handler.rst',
> >          'guides/tracing.rst',
> > +        'glossary.rst',
> >          'index.rst',
> >          'internal-api/index.rst',
> >          'introduction.rst',
> >
> > --
> > 2.51.1
> >

Hi

2025. 12. 29. 10:39 keltezéssel, Kieran Bingham írta:
> Hi Walter,
> 
> Thank you for working on this.
> 
> Quoting Jacopo Mondi (2025-12-23 11:02:09)
>> Hi Walter,
>>
>> On Fri, Dec 19, 2025 at 09:06:30PM +0200, Walter Werner Schneider wrote:
>>> The page currently contains acronyms and abbreviations commonly used
>>> troughout libcamera and related projects, but can be expanded to also
>>> explain technical terms.
>>
>> Thanks, as said on irc I'm in two minds about this.
> 
> I think this is a positive and helpful contribution.

I also think it can be useful.


> 
>> On one side, I clearly understand it might be helpful to newcomers to
>> navigate the code base and documentation. On the other hand, most
>> concepts here are not libcamera specific, and just providing an
>> explanation for the acronym might not be sufficient to clarify the
>> concepts in full.
> 
> It might not be fully describing the concepts, but it's at least more
> clearly expanding the definition to /our/ usage. As you stated below -
> sometimes TLAs (The literal abbreviations) can be MUA
> (Multi-use-acronyms) and at the very least a DUI (defined ultimate
> intent) can prevent them from being misconstrued.
> 
> 
>> On some terms, specifically the ones that refers to standards, just
>> spelling the names out might even be confusing. See below
> 
> I'm not sure I understand this how can spelling out the names be more
> confusing than just leaving an ambiguity ?
> 
>>
>>>
>>> Signed-off-by: Walter Werner Schneider <contact@schnwalter.eu>
>>> ---
>>>   Documentation/glossary.rst | 158 +++++++++++++++++++++++++++++++++++++++++++++
>>>   Documentation/index.rst    |   1 +
>>>   Documentation/meson.build  |   1 +
>>>   3 files changed, 160 insertions(+)
>>>
>>> diff --git a/Documentation/glossary.rst b/Documentation/glossary.rst
>>> new file mode 100644
>>> index 0000000000000000000000000000000000000000..d8679a1148d2b520c301891745e78f5033b1235d
>>> --- /dev/null
>>> +++ b/Documentation/glossary.rst
>>> @@ -0,0 +1,158 @@
> [...]
>>
>> First time I see this one :)
>>
>>> +
>>> +   WDR
>>> +      Wide Dynamic Range
>>
>> I'm not sure.. Again, I understand why it might be useful, but it
>> feels there are a lot terms there which either refers to standards,
>> informal acronyms, driver names.. it's a bit mixed.. maybe it's just
>> what a glossary should look like.
> 
> Assuming doxygen will handle all the :term:`TLA` links here - I don't
> think the mix matters. It's just the database to store all of the
> defintions or expansions of any term we use which merits a bit of
> context. And if a user has come in and said "I don't know what this term
> refers to in the context of libcamera" that would automatically make it
> appropriate to explain in my view.
> 
> 
> 
>> In general, I'm a bit skeptical on the idea of trying to create
>> definitions for things 'bigger' than libcamera. It's not the job of
>> a software library to provide a knowledge base for imaging concepts
>> and technologies, as the risk of providing incomplete/misleading
>> information is higher than the benefit. Here we have just terms, so
>> the risk of mis-guiding people is low, but still it feels
>> underspecified for some entries (standards in particular).
>>
>> What do the others think ?
> 
> It's not the job of libcamera to teach people about DMA ... but it's the
> job of *any documentation* to clearly reference and define all of it's
> terms. So I honestly think this is a good idea.
> 
> I'd even go a step further and put a short brief (or external link to
> further information like wikipedia) to each term. But I haven't checked
> how it will look in the output yet.

I believe that makes a lot of sense, most people will probably make a
search for a new term in any case, so directing them to a useful resource
seems a good addition.


Regards,
Barnabás Pőcze


> 
>>
>>
>>> diff --git a/Documentation/index.rst b/Documentation/index.rst
>>> index 8109b4295c92d722a2a215b97fd50af2f9babb9c..2eb0b894f1139d43389b2b450be003b054f6e335 100644
>>> --- a/Documentation/index.rst
>>> +++ b/Documentation/index.rst
>>> @@ -21,6 +21,7 @@
>>>
>>>      Contribute <contributing>
>>>      Getting Started <getting-started>
>>> +   Glossary <glossary>
>>>      Camera Sensor Model <camera-sensor-model>
>>>      IPA Writer's guide <guides/ipa>
>>>      libcamera Architecture <libcamera_architecture>
>>> diff --git a/Documentation/meson.build b/Documentation/meson.build
>>> index 51899c19c1667c8ac07c6e7776e1faaa14915e20..158825e398c48f41fbfebe4b4ac7afecb1a5b2a2 100644
>>> --- a/Documentation/meson.build
>>> +++ b/Documentation/meson.build
>>> @@ -161,6 +161,7 @@ if sphinx.found()
>>>           'guides/ipa.rst',
>>>           'guides/pipeline-handler.rst',
>>>           'guides/tracing.rst',
>>> +        'glossary.rst',
>>>           'index.rst',
>>>           'internal-api/index.rst',
>>>           'introduction.rst',
>>>
>>> --
>>> 2.51.1
>>>