Skip to content

Commit

Permalink
Improvements to the docs and OCIO config
Browse files Browse the repository at this point in the history 
To aid with versioning, the OFX OCIO config has been renamed, now including the OpenFX version number instead of the version number of the upstream OCIO config.

Basic colourspaces have been removed from the reference OCIO config, allowing hosts and plug-ins to freely choose any colourspace with the correct attributes.

Two colourspaces were missing from the core style and have been added.

Various doc improvements to fix typos and make the intended usage clearer.

Signed-off-by: John-Paul Smith <jps@borisfx.com>
  • Loading branch information
@john-paulsmith
john-paulsmith committed Jul 10, 2024
1 parent 88f35d0 commit af85e80
Show file tree
Hide file tree
Showing 5 changed files with 88 additions and 75 deletions.
41 changes: 28 additions & 13 deletions include/ofxColour.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,13 @@ colour management. OCIO is used as the reference for the colour management
API, but is not required to implement the native styles.
The colourspace strings used in the native styles are from
openfx-studio-config-v2.1.0_acces-v1.3_ocio-v2.3.ocio
and stored for OFX purposes in ofxColourspaceList.h. Additionally, there is
a scheme for cross-referencing between clips.
openfx-native-1.5.ocio, which is based on the OCIO ACES Studio built-in
config, studio-config-v2.1.0_aces-v1.3_ocio-v2.3, and stored for OFX purposes
in ofxColourspaceList.h. Additionally, there is a scheme for cross-referencing
between clips, and a set of "basic colourspaces", which are designed to be
generic names for a family of colourspaces. When a basic colourspace is used,
this means the host is free to choose any colourspace with the same encoding
and reference space (scene vs display).
The assumption is that OCIO > Full > Core > Basic, so the highest style
supported by both host and plug-in will be chosen.
Expand Down Expand Up @@ -63,10 +67,19 @@ A host must set this property on any effect instances where it has negotiated
OCIO colour management (kOfxImageEffectPropColourManagementOCIO).
Use of URIs for built-in configs, such as ocio://default is permitted.
When native colour management is in use, a host must set this
property to point to the OCIO config used to define strings for the version of
OFX it was built against. This will allow a plug-in which uses OCIO to work
directly with native styles.
When the core or full styles are in use, a host must set this property to
point to an OCIO config which defines all the colourspaces required for that
style, which will allow a plug-in that uses OCIO to work directly with native
styles. The included config, openfx-native-v1.5_aces-v1.3_ocio-v2.3.ocio, is
suitable, but hosts might provide a different config which is compatible. If
hosts choose to use their own config, its definitions for native colourspaces
must exactly match those found in openfx-native-v1.5_aces-v1.3_ocio-v2.3.ocio.
As basic colourspaces are not defined in the OpenFX native config, hosts may
set this property as they wish when using the basic style. If hosts do provide
a config, an OCIO-based plug-in may attempt to use it to look up mappings for
basic colourspaces, but leaving those undefined must not be considered an
error.
*/
#define kOfxImageEffectPropOCIOConfig "OfxImageEffectPropOCIOConfig"

Expand All @@ -81,16 +94,18 @@ it will be set to the working colourspace of the host but could be any valid
colourspace.
Plug-ins may set this property on an output clip. Plug-ins which output motion
vectors or similar images which should not be colour managed can use the data
colourspace which is present in the built-in OCIO configs.
vectors or similar images which should not be colour managed should use
kOfxColourspaceRaw,
Both host and plug-in should use the value of
kOfxImageClipPropPreferredColourspace where reasonable.
Cross-referencing between clips is possible by setting this property to
"OfxColourspace_<clip>". For example a plug-in may set this property on its
output clip to "OfxColourspace_Source", telling the host that the colourspace
of the output matches the input.
of the output matches the input. In the basic style, plug-ins are recommended
to use cross-referencing for their output clip unless kOfxColourspaceRaw is
required.
If a clip sets OfxImageClipPropIsMask or it only supports
OfxImageComponentAlpha, colour management is disabled and this property
Expand Down Expand Up @@ -122,8 +137,8 @@ The host is free to choose any colourspace from this list, but should favour
the first mutually agreeable colourspace, and set kOfxImageClipPropColourspace
to tell the plug-in which colourspace has been selected. A host does not need
to convert into the first choice just because it can, as this might be
inefficient, and should scene-to-display or display-to-scene conversions where
possible.
inefficient, and should avoid scene-to-display or display-to-scene conversions
where possible.
In the event that the host cannot supply images in a requested colourspace,
it may supply images in any valid colourspace. Plug-ins must check
Expand All @@ -147,7 +162,7 @@ both input clips to be in the same colourspace. A host might set the same
thing on the plug-in's output clip to request that the plug-in outputs the
same colourspace as the input.
If a plug-in has inputs which contain motion vectors, depth values or other
If a plug-in has inputs which expect motion vectors, depth values or other
non-colour channels, it should set the preferred colourspace to
kOfxColourspaceRaw. Similarly, if a host requests outputs in a typical scene
colourspace, but the plug-in is producing motion vectors, it should ignore
Expand Down
81 changes: 41 additions & 40 deletions include/ofxColourspaceList.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,12 @@ extern "C" {

/** @file ofxColourspaceList.h
Contains the list of supported colourspaces.
This file was auto-generated by scripts/genColour from openfx-studio-config-v2.1.0_aces-v1.3_ocio-v2.3.
This file was auto-generated by scripts/genColour from openfx-native-v1.5_aces-v1.3_ocio-v2.3.
*/


// Basic Colourspaces
// These colourspaces are generic names for any colourspace with the correct attributes.

/** @brief ofx_hdr
Any display-referred HDR video such as Rec. 2020 HLG or PQ.
Expand All @@ -39,7 +40,7 @@ Any scene-referred linear colourspace.
#define kOfxColourspaceOfxLinearIsDisplay false

/** @brief ofx_log
Any colourspace with a log transfer function.
Any scene-referred colourspace with a log transfer function.
*/
#define kOfxColourspaceOfxLog "ofx_log"
#define kOfxColourspaceOfxLogLabel "ofx_log"
Expand Down Expand Up @@ -169,6 +170,43 @@ Any display-referred SDR video such as Rec. 709.
#define kOfxColourspaceRec2100PqDisplayIsCore true
#define kOfxColourspaceRec2100PqDisplayIsDisplay true

// st2084_p3d65_display
// Convert CIE XYZ (D65 white) to ST-2084 (PQ), P3-D65 primaries
// AMF Components
// --------------
// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_1000nits_15nits_ST2084.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_1000nits_15nits_ST2084.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_2000nits_15nits_ST2084.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_2000nits_15nits_ST2084.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_4000nits_15nits_ST2084.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_4000nits_15nits_ST2084.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_108nits_7point2nits_ST2084.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_108nits_7point2nits_ST2084.a1.1.0
#define kOfxColourspaceSt2084P3d65Display "st2084_p3d65_display"
#define kOfxColourspaceSt2084P3d65DisplayLabel "ST2084-P3-D65 - Display"
#define kOfxColourspaceSt2084P3d65DisplayEncoding "hdr-video"
#define kOfxColourspaceSt2084P3d65DisplayIsData false
#define kOfxColourspaceSt2084P3d65DisplayIsBasic false
#define kOfxColourspaceSt2084P3d65DisplayIsCore true
#define kOfxColourspaceSt2084P3d65DisplayIsDisplay true

// p3d65_display
// Convert CIE XYZ (D65 white) to Gamma 2.6, P3-D65
// AMF Components
// --------------
// ACEStransformID: urn:ampas:aces:transformId:v1.5:ODT.Academy.P3D65_48nits.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvODT.Academy.P3D65_48nits.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:ODT.Academy.P3D65_Rec709limited_48nits.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:ODT.Academy.P3D65_D60sim_48nits.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvODT.Academy.P3D65_D60sim_48nits.a1.1.0
#define kOfxColourspaceP3d65Display "p3d65_display"
#define kOfxColourspaceP3d65DisplayLabel "P3-D65 - Display"
#define kOfxColourspaceP3d65DisplayEncoding "sdr-video"
#define kOfxColourspaceP3d65DisplayIsData false
#define kOfxColourspaceP3d65DisplayIsBasic false
#define kOfxColourspaceP3d65DisplayIsCore true
#define kOfxColourspaceP3d65DisplayIsDisplay true

// ACES2065-1
// The "Academy Color Encoding System" reference colorspace.
#define kOfxColourspaceACES20651 "ACES2065-1"
Expand Down Expand Up @@ -342,26 +380,6 @@ Any display-referred SDR video such as Rec. 709.
#define kOfxColourspaceCIEXYZD65IsCore false
#define kOfxColourspaceCIEXYZD65IsDisplay true

// st2084_p3d65_display
// Convert CIE XYZ (D65 white) to ST-2084 (PQ), P3-D65 primaries
// AMF Components
// --------------
// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_1000nits_15nits_ST2084.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_1000nits_15nits_ST2084.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_2000nits_15nits_ST2084.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_2000nits_15nits_ST2084.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_4000nits_15nits_ST2084.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_4000nits_15nits_ST2084.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:RRTODT.Academy.P3D65_108nits_7point2nits_ST2084.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvRRTODT.Academy.P3D65_108nits_7point2nits_ST2084.a1.1.0
#define kOfxColourspaceSt2084P3d65Display "st2084_p3d65_display"
#define kOfxColourspaceSt2084P3d65DisplayLabel "ST2084-P3-D65 - Display"
#define kOfxColourspaceSt2084P3d65DisplayEncoding "hdr-video"
#define kOfxColourspaceSt2084P3d65DisplayIsData false
#define kOfxColourspaceSt2084P3d65DisplayIsBasic false
#define kOfxColourspaceSt2084P3d65DisplayIsCore false
#define kOfxColourspaceSt2084P3d65DisplayIsDisplay true

// p3d60_display
// Convert CIE XYZ (D65 white) to Gamma 2.6, P3-D60 (Bradford adaptation)
// AMF Components
Expand All @@ -376,23 +394,6 @@ Any display-referred SDR video such as Rec. 709.
#define kOfxColourspaceP3d60DisplayIsCore false
#define kOfxColourspaceP3d60DisplayIsDisplay true

// p3d65_display
// Convert CIE XYZ (D65 white) to Gamma 2.6, P3-D65
// AMF Components
// --------------
// ACEStransformID: urn:ampas:aces:transformId:v1.5:ODT.Academy.P3D65_48nits.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvODT.Academy.P3D65_48nits.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:ODT.Academy.P3D65_Rec709limited_48nits.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:ODT.Academy.P3D65_D60sim_48nits.a1.1.0
// ACEStransformID: urn:ampas:aces:transformId:v1.5:InvODT.Academy.P3D65_D60sim_48nits.a1.1.0
#define kOfxColourspaceP3d65Display "p3d65_display"
#define kOfxColourspaceP3d65DisplayLabel "P3-D65 - Display"
#define kOfxColourspaceP3d65DisplayEncoding "sdr-video"
#define kOfxColourspaceP3d65DisplayIsData false
#define kOfxColourspaceP3d65DisplayIsBasic false
#define kOfxColourspaceP3d65DisplayIsCore false
#define kOfxColourspaceP3d65DisplayIsDisplay true

// p3_dci_display
// Convert CIE XYZ (D65 white) to Gamma 2.6, P3-DCI (DCI white with Bradford adaptation)
// AMF Components
Expand Down Expand Up @@ -784,7 +785,7 @@ A colourspace suitable for colour grading, typically a log colourspace.
#define kOfxColourspaceRoleColorTiming "color_timing"

/** @brief compositing_log
Any colourspace with a log transfer function.
Any scene-referred colourspace with a log transfer function.
*/
#define kOfxColourspaceRoleCompositingLog "compositing_log"

Expand Down
7 changes: 1 addition & 6 deletions ...io-config-v2.1.0_aces-v1.3_ocio-v2.3.ocio → ...enfx-native-v1.5_aces-v1.3_ocio-v2.3.ocio
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ environment:
search_path: ""
strictparsing: true
luma: [0.2126, 0.7152, 0.0722]
name: openfx-studio-config-v2.1.0_aces-v1.3_ocio-v2.3
name: openfx-native-v1.5_aces-v1.3_ocio-v2.3
description: |
OpenFX 1.5 Native Mode Config
Based on: Academy Color Encoding System - Studio Config [COLORSPACES v2.1.0] [ACES v1.3] [OCIO v2.3]
Expand All @@ -21,11 +21,6 @@ roles:
compositing_log: ACEScct
data: Raw
matte_paint: ACEScct
ofx_hdr: Rec.2100-HLG - Display
ofx_linear: ACEScg
ofx_log: ACEScct
ofx_raw: Raw
ofx_sdr: Rec.1886 Rec.709 - Display
scene_linear: ACEScg
texture_paint: sRGB - Texture

Expand Down
21 changes: 16 additions & 5 deletions scripts/genColour
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

# Extract information from an OCIO config to C header.
# Example invocation:
# OCIO=include/openfx-studio-config-v2.1.0_aces-v1.3_ocio-v2.3.ocio scripts/genColour > include/ofxColourspaceList.h
# OCIO=include/openfx-native-v1.5_aces-v1.3_ocio-v2.3.ocio scripts/genColour > include/ofxColourspaceList.h

import sys
import PyOpenColorIO as OCIO
Expand Down Expand Up @@ -38,14 +38,14 @@ footer = '''
role_docs = {
'ofx_sdr': 'Any display-referred SDR video such as Rec. 709.',
'ofx_hdr': 'Any display-referred HDR video such as Rec. 2020 HLG or PQ.',
'ofx_log': 'Any colourspace with a log transfer function.',
'ofx_log': 'Any scene-referred colourspace with a log transfer function.',
'ofx_linear': 'Any scene-referred linear colourspace.',
'ofx_raw': 'Image values should not be treated as colour, e.g. motion vectors or masks.',
'aces_interchange': 'Guaranteed to be ACES2065-1.',
'cie_xyz_d65_interchange': 'CIE XYZ colorimetry with the neutral axis at D65.',
'color_picking': 'The colourspace to use for colour pickers, typically a display colourspace.',
'color_timing': 'A colourspace suitable for colour grading, typically a log colourspace.',
'compositing_log': 'Any colourspace with a log transfer function.',
'compositing_log': 'Any scene-referred colourspace with a log transfer function.',
'data': 'Image values should not be treated as colour, e.g. motion vectors or masks. Mapped to the raw colourspace.',
'matte_paint': 'A colourspace suitable for matte painting.',
'scene_linear': 'Any scene-referred linear colourspace.',
Expand Down Expand Up @@ -117,14 +117,25 @@ core_spaces = ['srgb_display', 'displayp3_display', 'rec1886_rec709_display',
'lin_rec709_srgb', 'g18_rec709_tx', 'g22_ap1_tx',
'g22_rec709_tx', 'g24_rec709_tx', 'srgb_encoded_ap1_tx',
'srg_encoded_p3d65_tx', 'srgb_tx', 'Raw',
'rec1886_rec2020_display', 'rec2100_hlg_display', 'rec2100_pq_display']
'rec1886_rec2020_display', 'rec2100_hlg_display', 'rec2100_pq_display',
'st2084_p3d65_display', 'p3d65_display']

# This should be the OpenFX OCIO config created by genOCIOConfig
ofx_config = OCIO.GetCurrentConfig()

# Add OFX-specific basic colourspaces here rather than in genOCIOConfig
# to avoid creating an expectation that these mappings should always be used.
# The assigned colourspaces are chosen simply to generate the correct
# attributes in the header.
ofx_config.setRole('ofx_sdr', 'rec1886_rec709_display')
ofx_config.setRole('ofx_hdr', 'rec2100_hlg_display')
ofx_config.setRole('ofx_log', 'ACEScct')
ofx_config.setRole('ofx_linear', 'ACEScg')
ofx_config.setRole('ofx_raw', 'raw')

print(Template(header).substitute(config_name=ofx_config.getName()))

print('\n// Basic Colourspaces')
print('\n// Basic Colourspaces\n// These colourspaces are generic names for any colourspace with the correct attributes.')
for basic_role in [role for role in ofx_config.getRoles() if role[0] in basic_roles]:
print_basic_colourspace(basic_role)

Expand Down
13 changes: 2 additions & 11 deletions scripts/genOCIOConfig
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@

# Create an OCIO config equivalant to OpenFX Native colour management
# Example invocation:
# scripts/genOCIOConfig > include/openfx-studio-config-v2.1.0_aces-v1.3_ocio-v2.3.ocio
# scripts/genOCIOConfig > include/openfx-native-1.5.ocio

import PyOpenColorIO as OCIO

Expand All @@ -15,19 +15,10 @@ ofx_config = OCIO.Config.CreateFromBuiltinConfig('studio-config-v2.1.0_aces-v1.3
srgb_tx = ofx_config.getColorSpace('srgb_tx')
srgb_tx.setEncoding('sdr-video')

# Add OFX-specific roles for use as "basic colourspaces".
# Suitable colourspaces are defined for OCIO compatibility, but a plug-in/host operating
# in basic mode might not be using these exact colourspaces.
ofx_config.setRole('ofx_sdr', 'rec1886_rec709_display')
ofx_config.setRole('ofx_hdr', 'rec2100_hlg_display')
ofx_config.setRole('ofx_log', 'ACEScct')
ofx_config.setRole('ofx_linear', 'ACEScg')
ofx_config.setRole('ofx_raw', 'raw')

# Make all colourspaces active, future OCIO configs will also do this
ofx_config.setInactiveColorSpaces('')

ofx_config.setName(f'openfx-{ofx_config.getName()}')
ofx_config.setName(f'openfx-native-v1.5_aces-v1.3_ocio-v2.3')
ofx_config.setDescription(f'OpenFX 1.5 Native Mode Config\nBased on: {ofx_config.getDescription()}')

ofx_config.validate() # will throw if there's an error
Expand Down

0 comments on commit af85e80

Please sign in to comment.