|
| 1 | +<!-- SPDX-License-Identifier: CC-BY-4.0 --> |
| 2 | +<!-- Copyright OpenFX and contributors to the OpenFX project. --> |
| 3 | +# ofxColourConvert — header-only colour conversion |
| 4 | + |
| 5 | +`ofxColourConvert.h` is a small, dependency-free, header-only C++17 library |
| 6 | +that converts RGB triplets between the OFX native colourspaces (see |
| 7 | +[`include/ofxColour.h`](../../include/ofxColour.h)) and the ACES2065-1 (AP0) |
| 8 | +reference colourspace. |
| 9 | + |
| 10 | +It is a convenience for plug-in and host authors who want simple, exact colour |
| 11 | +conversions without taking on a full [OpenColorIO](https://opencolorio.org/) |
| 12 | +dependency. It is **not** a replacement for OCIO. |
| 13 | + |
| 14 | +## Scope |
| 15 | + |
| 16 | +Every supported space reduces to: |
| 17 | + |
| 18 | +``` |
| 19 | +code value --(transfer function)--> linear RGB --(3x3 matrix)--> AP0 |
| 20 | +``` |
| 21 | + |
| 22 | +and back, so each conversion is colorimetrically exact and round-trips to |
| 23 | +ACES2065-1. The gamut matrices are derived at compile time from the published |
| 24 | +primaries using the Normalized Primaries Matrix plus a von Kries chromatic |
| 25 | +adaptation, matching the OCIO ACES config the OFX native colourspaces are based |
| 26 | +on. |
| 27 | + |
| 28 | +Covered: the scene-referred working spaces (ACES2065-1, ACEScg, ACEScc/cct, |
| 29 | +linear Rec.709/Rec.2020/P3-D65) and the camera/texture encodings (ARRI, Sony, |
| 30 | +Canon, Panasonic, RED, Blackmagic, DaVinci, sRGB and pure-gamma texture |
| 31 | +spaces). |
| 32 | + |
| 33 | +Out of scope (these need OCIO): display rendering (the ACES Output Transform / |
| 34 | +RRT+ODT), the display-referred `*_display` spaces, the ADX film-density |
| 35 | +encodings, and the abstract "basic" `ofx_*` spaces. |
| 36 | + |
| 37 | +## Usage |
| 38 | + |
| 39 | +It is header-only — just include it (C++17 or later required): |
| 40 | + |
| 41 | +```cpp |
| 42 | +#include "ofxColourConvert.h" |
| 43 | + |
| 44 | +using namespace ofx::colour; |
| 45 | +RGB c = { 0.2, 0.5, 0.8 }; // an S-Log3/S-Gamut3 pixel |
| 46 | +RGB aces = toACES2065_1(c, Colourspace::slog3_sgamut3); |
| 47 | +RGB out = fromACES2065_1(aces, Colourspace::lin_rec709_srgb); |
| 48 | +// or directly: |
| 49 | +RGB out2 = convert(c, Colourspace::slog3_sgamut3, Colourspace::lin_rec709_srgb); |
| 50 | +``` |
| 51 | +
|
| 52 | +`colourspaceFromName()` maps the OFX colourspace identifier strings (e.g. |
| 53 | +`"slog3_sgamut3"`) to the `Colourspace` enum. |
| 54 | +
|
| 55 | +### CMake |
| 56 | +
|
| 57 | +The header is exposed as an `INTERFACE` target: |
| 58 | +
|
| 59 | +```cmake |
| 60 | +target_link_libraries(my_plugin PRIVATE OpenFX::ColourConvert) |
| 61 | +``` |
| 62 | + |
| 63 | +### Conan |
| 64 | + |
| 65 | +The OpenFX package exposes it as the `ColourConvert` component |
| 66 | +(`openfx::ColourConvert`), header-only. |
| 67 | + |
| 68 | +## Tests |
| 69 | + |
| 70 | +The [`tests/`](tests) directory validates the header against OpenColorIO in |
| 71 | +both directions for every supported colourspace. They are off by default |
| 72 | +(OCIO is heavy to build); enable with `-DOFX_BUILD_COLOUR_TESTS=ON`. See |
| 73 | +[`tests/README.md`](tests/README.md). |
0 commit comments