.. default-role:: math Parameters ========== All parameters are implemented as `properties `_ (managed attributes). They are parsed when set: values are clipped to the allowed range and usually several types are accepted, e.g. ``bool``, ``int``, ``float`` for `numbers `_ and additionally ``list``, ``tuple``, ``numpy.ndarray`` for `sequences `_. Note that some attributes have sub-dependencies, hence dependent attributes might change as well. Circular dependencies are resolved automatically. .. (cf. :numref:`interdependencies`), .. _interdependencies: .. figure:: params/interdependencies.svg :align: center :alt: interdependencies Parameters and their interdependencies. Video Shape ----------- :attr:`~fringes.fringes.Fringes.shape` is the standardized shape ( :attr:`~fringes.fringes.Fringes.T`, :attr:`~fringes.fringes.Fringes.Y`, :attr:`~fringes.fringes.Fringes.X`, :attr:`~fringes.fringes.Fringes.C`) of the fringe pattern sequence, with - :attr:`~fringes.fringes.Fringes.T`: number of frames - :attr:`~fringes.fringes.Fringes.Y`: height (in pixel units) - :attr:`~fringes.fringes.Fringes.X`: width (in pixel units) - :attr:`~fringes.fringes.Fringes.C`: number of color channels (depends on the :ref:`coloring ` and `multiplexing`_ schemes activated). .. :attr:`~fringes.fringes.Fringes.T` = :attr:`~fringes.fringes.Fringes.H` `\cdot \sum` :attr:`~fringes.fringes.Fringes.N`. If a `multiplexing`_ scheme is activated, :attr:`~fringes.fringes.Fringes.T` reduces further. :attr:`~fringes.fringes.Fringes.L` is the maximum of :attr:`~fringes.fringes.Fringes.X` and :attr:`~fringes.fringes.Fringes.Y` and denotes the length (in pixel units) to be encoded. :attr:`~fringes.fringes.Fringes.a` can be used to extend :attr:`~fringes.fringes.Fringes.L` by the factor `\in [1, 2]` to :attr:`~fringes.fringes.Fringes.Lext`. Coordinate System ------------------ The following coordinate systems can be used by setting :attr:`~fringes.fringes.Fringes.grid` to: - ``'image'``: The top left corner pixel of the grid is the origin (0, 0) and positive directions are right- resp. downwards. .. - ``'Cartesian'``: The center of grid is the origin (0, 0) and positive directions are right- resp. upwards. - ``'polar'``: The center of grid is the origin (0, 0) and positive directions are clockwise resp. outwards. - ``'log-polar'``: The center of grid is the origin (0, 0) and positive directions are clockwise resp. outwards. - ``'spiral'``: The origin (0, 0) resides in the center of the generated grid and positive directions are counterclockwise, cf. [Klu18]_. :attr:`~fringes.fringes.Fringes.axes` defines the order of the coordinate system's axes. Default is (1, 0) i.e. Cartesian indexing. :attr:`~fringes.fringes.Fringes.D` = len(:attr:`~fringes.fringes.Fringes.axes`) is the number of directions/dimensions of the coordinate system to use. .. (not to be confused with ``'Cartesian'`` coordinate system i.e. :attr:`~fringes.fringes.Fringes.grid`, see above). .. :attr:`~fringes.fringes.Fringes.angle` can be used to tilt the coordinate system. The origin remains the same. :attr:`~fringes.fringes.Fringes.x` are the coordinate matrices to be encoded. Intensity Values ---------------- :attr:`~fringes.fringes.Fringes.bits` is the number of bits. :attr:`~fringes.fringes.Fringes.dtype` denotes the data type which can hold `2` ^ :attr:`~fringes.fringes.Fringes.bits` of information. Possible values are: - ``'uint8'`` (the default) - ``'uint16'`` - ``'uint32'`` - ``'float32'`` - ``'float64'`` :attr:`~fringes.fringes.Fringes.Imax` is the maximum gray value and equals 1 for ``float`` and `2` ^ :attr:`~fringes.fringes.Fringes.bits` `- 1` for ``unsigned integers``. :attr:`~fringes.fringes.Fringes.A` is the offset, also called brightness (of the background) `\in [0,` :attr:`~fringes.fringes.Fringes.Imax` `]`. :attr:`~fringes.fringes.Fringes.B` is the amplitude of the cosinusoidal fringes `\in [0,` :attr:`~fringes.fringes.Fringes.Imax` `]`. :attr:`~fringes.fringes.Fringes.V` is the fringe :ref:`visibility ` (also called fringe contrast). :attr:`~fringes.fringes.Fringes.V` = :attr:`~fringes.fringes.Fringes.A` / :attr:`~fringes.fringes.Fringes.B`, with :attr:`~fringes.fringes.Fringes.V` `\in [0, 1]`. :attr:`~fringes.fringes.Fringes.E` is the :ref:`exposure ` (relative brightness) `\in [0, 1]`. :attr:`~fringes.fringes.Fringes.g` denotes the gamma correction factor and can be used to compensate non-linearities of the display response curve. Set --- :attr:`~fringes.fringes.Fringes.K` is the number of sets. It is equal for all directions :attr:`~fringes.fringes.Fringes.D`. Each set consists of the following attributes: .. (cf. black box in :numref:`interdependencies`): - :attr:`~fringes.fringes.Fringes.N`: number of shifts - :attr:`~fringes.fringes.Fringes.l`: wavelength (in pixel units) - :attr:`~fringes.fringes.Fringes.v`: spatial frequency, i.e. number of periods (per screen length :attr:`~fringes.fringes.Fringes.L`) - :attr:`~fringes.fringes.Fringes.f`: temporal frequency, i.e. number of periods to shift over Each is an array with shape (number of directions :attr:`~fringes.fringes.Fringes.D`, number of sets :attr:`~fringes.fringes.Fringes.K`). For example, if :attr:`~fringes.fringes.Fringes.N`.shape = (2, 3), it means that we encode :attr:`~fringes.fringes.Fringes.D` = 2 directions with :attr:`~fringes.fringes.Fringes.K` = 3 sets each. Changing :attr:`~fringes.fringes.Fringes.D` (resp. :attr:`~fringes.fringes.Fringes.axes`) or :attr:`~fringes.fringes.Fringes.K` directly, changes the shape of all set attributes. When setting a set attribute with a new shape, :attr:`~fringes.fringes.Fringes.D` (resp. :attr:`~fringes.fringes.Fringes.axes`) and :attr:`~fringes.fringes.Fringes.K` are updated as well as the shape of the other set attributes. If a set attribute is 0D, i.e. a scalar, then all values are simply replaced by the new one. If a set attribute is 1D, then it is stacked to match the number of directions :attr:`~fringes.fringes.Fringes.D`. :attr:`~fringes.fringes.Fringes.l` and :attr:`~fringes.fringes.Fringes.v` are related by :attr:`~fringes.fringes.Fringes.l` = :attr:`~fringes.fringes.Fringes.L` / :attr:`~fringes.fringes.Fringes.v`. When :attr:`~fringes.fringes.Fringes.L` changes, :attr:`~fringes.fringes.Fringes.v` is kept constant and only :attr:`~fringes.fringes.Fringes.l` is changed. :attr:`~fringes.fringes.Fringes.f` = 1 almost always. The most common exception is when :ref:`frequency division multiplexing ` :attr:`~fringes.fringes.Fringes.FDM` is activated. :attr:`~fringes.fringes.Fringes.reverse` is a boolean which reverses the direction of the shifts (by multiplying :attr:`~fringes.fringes.Fringes.f` with -1). :attr:`~fringes.fringes.Fringes.p0` denotes the phase offset, which can be used to e.g. let the fringe patterns start (at the origin) with a gray value of zero. Coloring and Averaging ---------------------- :attr:`~fringes.fringes.Fringes.h` denotes hues and is a sequence of RGB color triplets `\in [0, 255]`. They are used to colorize the fringe patterns. However, black (0, 0, 0) is not allowed. :attr:`~fringes.fringes.Fringes.h` must be in shape (:attr:`~fringes.fringes.Fringes.H`, 3), where :attr:`~fringes.fringes.Fringes.H` is the number of hues and 3 is the length of the RGB color triplet. The hues :attr:`~fringes.fringes.Fringes.h` can also be set by assigning any combination of the following characters as a string: - ``'r'``: red - ``'g'``: green - ``'b'``: blue - ``'c'``: cyan - ``'m'``: magenta - ``'y'``: yellow - ``'w'``: white :attr:`~fringes.fringes.Fringes.C` is the number of color channels required for either the set of hues :attr:`~fringes.fringes.Fringes.h` or :ref:`wavelength division multiplexing `. For example, if all hues are monochromatic, i.e. the RGB values are identical for each hue, :attr:`~fringes.fringes.Fringes.C` equals 1, else 3. :attr:`~fringes.fringes.Fringes.M` is the number of averaged intensity samples (repeating hues will be fused by averaging them before decoding). Multiplexing ------------ The following multiplexing methods can be activated by setting them to ``True``: - :attr:`~fringes.fringes.Fringes.SDM`: Spatial Division Multiplexing This results in crossed fringe patterns. It can only be activated if we have two directions :attr:`~fringes.fringes.Fringes.D` = 2. The number of frames :attr:`~fringes.fringes.Fringes.T` is reduced by a factor of 2. - :attr:`~fringes.fringes.Fringes.WDM`: Wavelength Division Multiplexing The shifts are multiplexed into the color channel, resulting in an RGB fringe pattern. All shifts :attr:`~fringes.fringes.Fringes.N` must equal 3. The number of frames :attr:`~fringes.fringes.Fringes.T` is reduced by a factor of 3. - :attr:`~fringes.fringes.Fringes.FDM`: Frequency Division Multiplexing Here, the directions :attr:`~fringes.fringes.Fringes.D` and the sets :attr:`~fringes.fringes.Fringes.K` are multiplexed. This results in crossed fringe patterns if :attr:`~fringes.fringes.Fringes.D` = 2. It can only be activated if :attr:`~fringes.fringes.Fringes.D` > 1 or :attr:`~fringes.fringes.Fringes.K` > 1. If one wants a static pattern, i.e. one that remains congruent when shifted, set :attr:`~fringes.fringes.Fringes.static` to ``True``. :attr:`~fringes.fringes.Fringes.SDM` and :attr:`~fringes.fringes.Fringes.WDM` can be used together (reducing :attr:`~fringes.fringes.Fringes.T` by a factor of 2 * 3 = 6), :attr:`~fringes.fringes.Fringes.FDM` with neither. For more details, please refer to :doc:`Multiplex `. .. Unwrapping ---------- :attr:`~fringes.fringes.Fringes.uwr` denotes the phase unwrapping method and is either ``'none'``, ``'temporal'``, ``'spatial'`` or ``'FTM'``. See :ref:`unwrapping ` for more details. :attr:`~fringes.fringes.Fringes.mode` denotes the mode used for [temporal phase unwrapping](#temporal-phase-unwrapping--tpu-). Choose either ``'fast'`` (the default) or ``'precise'``. Quality Metrics --------------- :attr:`~fringes.fringes.Fringes.UMR` denotes the unambiguous measurement range. The coding is only unique within the interval [0, :attr:`~fringes.fringes.Fringes.UMR`); after that it repeats itself. It is derived from :attr:`~fringes.fringes.Fringes.l` and :attr:`~fringes.fringes.Fringes.v`: - If :attr:`~fringes.fringes.Fringes.l` `\in \mathbb{N}`, :attr:`~fringes.fringes.Fringes.UMR` = `lcm(` :attr:`~fringes.fringes.Fringes.l` `)`, with `lcm` being the least common multiple. - Else, if :attr:`~fringes.fringes.Fringes.v` `\in \mathbb{N}`, :attr:`~fringes.fringes.Fringes.UMR` = :attr:`~fringes.fringes.Fringes.L` / `gcd(` :attr:`~fringes.fringes.Fringes.v` `)`, with `gcd` being the greatest common divisor. - Else, if :attr:`~fringes.fringes.Fringes.v` `\lor` :attr:`~fringes.fringes.Fringes.l` `\in \mathbb{Q}` , `lcm` resp. `gcd` are extended to rational numbers. - Else, if :attr:`~fringes.fringes.Fringes.v` `\land` :attr:`~fringes.fringes.Fringes.l` `\in \mathbb{R} \setminus \mathbb{Q}` , :attr:`~fringes.fringes.Fringes.UMR` = `prod(` :attr:`~fringes.fringes.Fringes.l` `)`, with `prod` being the product operator. :attr:`~fringes.fringes.Fringes.uq` denotes the minimum possible positional uncertainty (standard deviation) of the measurement in pixels when considering only quantization noise. It is based on the phase noise model from [Sur97]_ and propagated through the unwrapping process and the phase fusion. It is influenced by the parameters - `1 / \sqrt{12}`: standard deviation of quantization noise of the light source or camera, - :attr:`~fringes.fringes.Fringes.B`: modulation of the fringe patterns, - :attr:`~fringes.fringes.Fringes.M`: number of averaged intensity samples, - :attr:`~fringes.fringes.Fringes.N`: number of phase shifts, - :attr:`~fringes.fringes.Fringes.l`: wavelengths :attr:`~fringes.fringes.Fringes.SQNR` = :attr:`~fringes.fringes.Fringes.L` / :attr:`~fringes.fringes.Fringes.uq` is the signal-to-quantization-noise ratio of the phase shift coding. It is a measure of how many points can be distinguished at most within the screen length [0, :attr:`~fringes.fringes.Fringes.L`). It remains constant if :attr:`~fringes.fringes.Fringes.L` and hence :attr:`~fringes.fringes.Fringes.l` is scaled (the scaling factor cancels out). :attr:`~fringes.fringes.Fringes.DRQ` = :attr:`~fringes.fringes.Fringes.UMR` / :attr:`~fringes.fringes.Fringes.uq` is the dynamic range of the phase shift coding. It a measure of how many points can be distinguished at most within the unambiguous measurement range `[0,` :attr:`~fringes.fringes.Fringes.UMR` `)`. Again, it remains constant if :attr:`~fringes.fringes.Fringes.L` and hence :attr:`~fringes.fringes.Fringes.l` is scaled (the scaling factor cancels out). :attr:`~fringes.fringes.Fringes.eta` = :attr:`~fringes.fringes.Fringes.L` / :attr:`~fringes.fringes.Fringes.UMR` is the spatial coding efficiency and is a measure of how well the coding range :attr:`~fringes.fringes.Fringes.UMR` fits the screen length :attr:`~fringes.fringes.Fringes.L`. It makes no sense to choose :attr:`~fringes.fringes.Fringes.UMR` much larger than :attr:`~fringes.fringes.Fringes.L`, because then a significant part of the coding range remains unused. .. :attr:`~fringes.fringes.Fringes.eta_temp` = :attr:`~fringes.fringes.Fringes.SNR` / :attr:`~fringes.fringes.Fringes.T` is the temporal coding efficiency and is a measure of how many code words, i.e. frames :attr:`~fringes.fringes.Fringes.T`, can distinguish how many screen points :attr:`~fringes.fringes.Fringes.SNR`. .. .. [Bot08] `Bothe, "Grundlegende Untersuchungen zur Formerfassung mit einem neuartigen Prinzip der Streifenprojektion und Realisierung in einer kompakten 3D-Kamera", Dissertation, ISBN 978-3-933762-24-5, BIAS Bremen, 2008. `_ .. [EMV] `European Machine Vision Association, "Standard for Characterization of Image Sensors and Cameras", EMVA Standard 1288 Release 4.0 Linear, 2021. `_ .. [Klu18] `Kludt and Burke, "Coding strategies for static patterns suitable for UV deflectometry", Forum Bildverarbeitung 2018, 2018. `_ .. [Sur97] `Surrel, "Additive noise effect in digital phase detection", Applied Optics, 1997. `_