PageRenderTime 58ms CodeModel.GetById 53ms app.highlight 3ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/configurations/allocation_vars.rst

http://github.com/imageworks/OpenColorIO
ReStructuredText | 123 lines | 93 code | 30 blank | 0 comment | 0 complexity | 6f18b266c0f982e7b6b987d43d7f9e56 MD5 | raw file
  1..
  2  SPDX-License-Identifier: CC-BY-4.0
  3  Copyright Contributors to the OpenColorIO Project.
  4
  5.. _allocationvars:
  6
  7How to Configure ColorSpace Allocation
  8======================================
  9
 10The allocation / allocation vars are utilized using during GPU 3dlut / shader
 11text generation. (Processor::getGpuShaderText, Processor::getGpuLut3D).
 12
 13If, in the course of GPU processing, a 3D lut is required, the "allocation /
 14allocation vars" direct how OCIO should sample the colorspace, with the intent
 15being to maintain maximum fidelity and minimize clamping.
 16
 17Currently support allocations / variables:
 18
 19ALLOCATION_UNIFORM::
 20    2 vars: [min, max]
 21
 22ALLOCATION_LG2::
 23    2 vars: [lg2min, lg2max]
 24    3 vars: [lg2min, lg2max, linear_offset]
 25
 26So say you have an srgb image (such as an 8-bit tif), where you know the data
 27ranges between 0.0 - 1.0 (after converting to float).  If you wanted to apply
 28a 3d lut to this data, there is no danger in sampling that space uniformly and
 29clamping data outside (0,1).   So for this colorspace we would tag it:
 30
 31.. code-block:: yaml
 32
 33    allocation: uniform
 34    allocationvars: [0.0, 1.0]
 35
 36These are the defaults, so the tagging could also be skipped.
 37
 38But what if you were actually first processing the data, where occasionally
 39small undershoot and overshoot values were encountered? If you wanted OCIO to
 40preserve this overshoot / undershoot pixel information, you would do so by
 41modifying the allocation vars.
 42
 43.. code-block:: yaml
 44
 45    allocation: uniform
 46    allocationvars: [-0.125, 1.125]
 47
 48This would mean that any image data originally within [-0.125, 1.125] will be
 49preserved during GPU processing.  (Protip: Data outside this range *may*
 50actually be preserved in some circumstances - such as if a 3d lut is not needed
 51- but it's not required to be preserved).
 52
 53So why not leave this at huge values (such as [-1000.0, 1000.0]) all the time?
 54Well, there's a cost to supporting this larger dynamic range, and that cost is
 55reduced precision within the 3D luts sample space.   So in general you're best
 56served by using sensible allocations (the smallest you can get away with, but
 57no smaller).
 58
 59Now in the case of high-dynamic range color spaces (such as float linear), a
 60uniform sampling is not sufficient because the max value we need to preserve is
 61so high.
 62
 63Say you were using a 32x32x32 3d lookup table (a common size).  Middle gray is
 64at 0.18, and specular values are very much above that.  Say the max value we
 65wanted to preserve in our coding space is 256.0, each 3d lut lattice coordinates
 66would represent 8.0 units of linear light! That means the vast majority of the
 67perceptually significant portions of the space wouldn't be sampled at all!
 68
 69unform allocation from 0-256\:
 700
 718.0
 7216.0
 73...
 74240.0
 75256.0
 76
 77So another allocation is defined, lg2
 78
 79.. code-block:: yaml
 80
 81      - !<ColorSpace>
 82        name: linear
 83        description: |
 84                        Scene-linear, high dynamic range. Used for rendering and compositing.
 85        allocation: lg2
 86        allocationvars: [-8, 8]
 87
 88In this case, we're saying that the appropriate ways to sample the 3d lut are
 89logarithmically, from 2^-8 stops to 2^8 stops.
 90
 91Sample locations:
 922^-8\: 0.0039
 932^-7\: 0.0078
 942^-6\: 0.0156
 95...
 962^0\:  1.0
 97...
 982^6\:  64.0
 992^7\:  128.0
1002^8\:  256.0
101
102Which gives us a much better perceptual sampling of the space.
103
104The one downside of this approach is that it can't represent 0.0,
105which is why we optionally allow a 3d allocation var, a black point
106offset.  If you need to preserve 0.0 values, and you have a high
107dynamic range space, you can specify a small offset.
108
109Example:
110
111.. code-block:: yaml
112
113    allocation: lg2
114    allocationvars: [-8, 8, 0.00390625]
115
116The [-15.0, 6.0] values in spi-vfx come from the fact that all of the
117linearizations provided in that profile span the region from 2^-15
118stops, to 2^6 stops.   One could probably change that black point to a
119higher number (such as -8), but if you raised it too much you would
120start seeing black values be clipped.   Conversely, on the high end
121one could raise it a bit but if you raised it too far the precision
122would suffer around gray, and if you lowered it further you'd start to
123see highlight clipping.