Obtaining the sequence and clip color spaces using the Premiere Pro Effect SDK

[yergin]

Hi community,

I'd like my effect to know which color spaces both the clip (if applied to a clip) and sequence are set up as - eg. Rec709, HLG or PQ. Something like the ColorSpaceRec struct used by importers, exporters and transmitters would be perfect but I haven't encountered any API like it for effects searching through the SDK headers.

The furthest I've gotten so far is getting an "opaque" color space ID for the sequence in the render callback which I can see does change based the sequence's color space setting in Premiere, only I don't know how to get anything meaningful from that opaque ID:

        AEFX_SuiteScoper<PF_UtilitySuite4> utilitySuite(inData, kPFUtilitySuite, kPFUtilitySuiteVersion4, outData);
        AEFX_SuiteScoper<PrSDKSequenceInfoSuite> infoSuite(inData, kPrSDKSequenceInfoSuite, kPrSDKSequenceInfoSuiteVersion, outData);

        PrTimelineID timelineID;
        PrSDKColorSpaceID colourSpaceID;
        utilitySuite->GetContainingTimelineID(inData->effect_ref, &timelineID);
        infoSuite->GetWorkingColorSpace(timelineID, &colourSpaceID);

Any clues would be appreciated!

[Bruce Bullis · Accepted solution]

Here are some helpful enumerations, from an upcoming release of the SDK; these values are valid for shipping PPro.

// Supported color Primaries
enum class PrColorPrimaries : csSDK_int32
{
	kBT709 = 1,				// Rec. 709 Primaries
	kBT470M = 4,			// Rec. ITU-R BT.470-6 System M (historical)
	kBT601_625 = 5,			// Rec. ITU-R BT.601-6 625 (PAL)
	kBT601_525 = 6,			// Rec. ITU-R BT.601-6 525 (NTSC)
	kSMPTE_240M = 7,		// functionally equivalent to BT.601-525, code value 6
	kGenericFilm = 8,		// Generic film
	kBT2020 = 9,			// Rec. ITU-R BT.2020-2
	kSMPTE_ST428_1 = 10,	// SMPTE ST 428-1
	kSMPTE_RP431 = 11,		// SMPTE ST 431-2
	kP3D65 = 12,			// SMPTE ST 432-1, P3D65
	kEBU3213 = 22,			// SMPTE EBU3213
	
	// Custom primaries not defined in ITU specifications.
	kSony_SGamut = 1010,		// Sony SGamut
	kSony_SGamut3 = 1011,		// Sony SGamut3
	kSony_SGamut3Cine = 1012,	// Sony SGamut3Cine
	kPanasonic_VGamut = 1020,	// Panasonic VGamut
	kCanon_CGamut = 1030		// Canon CGamut
};

// Supported Transfer Characteristics
enum class PrTransferCharacteristic : csSDK_int32
{
	kBT709 = 1,				// Rec. 709, functionally same as code values 6, 11, 14 and 15
	kBT470M = 4,			// Assumed display gamma 2.2
	kBT470BG = 5,			// Assumed display gamma 2.8
	kBT601 = 6,				// Rec. ITU-R BT.601-6 525 or 625, functionally same as code values 1, 11, 14 and 15
	kSMPTE_240M = 7,		// SMPTE 240M, functtioonallyy same as code values 1, 11, 14, 15
	kLinear = 8,			// Linear curve.
	kIEC61966_2_4 = 11,		// xvYCC, functionally same as code values 1, 6, 14 and 15
	kIEC61966_2_1 = 13,		// IEC 61966-2-1 sRGB or sYCC
	kBT2020a = 14,			// Rec. ITU-R BT.2020, functionally same as code values 1, 6, 11 and 15
	kBT2020b = 15,			// Rec. ITU-R BT.2020, functionally same as code values 1, 6, 11 and 14
	kBT2100PQ = 16,			// SMPTE ST 2084
	kST428_1 = 17,			// DCDM, SMPTE ST428 use Gamma of 2.6
	kBT2100HLG = 18,		// Rec. 2100 HLG
	
	// Custom curves not defined in ITU specifications.
	kSony_SLog2 = 1000,		// Sony SLog2
	kSony_SLog3 = 1001,		// Sony SLog3
	kPanasonic_VLog = 1010,	// Panasonic VLog
	kCanon_CLog2 = 1020,	// Canon CLog2
	kCanon_CLog3 = 1021		// Cannon CLog3
};

// Supported Matrix equations - used for YCC <-> RGB conversions
enum class PrMatrixEquations : csSDK_int32
{
	kIdentity = 0,			// Identity matrix
	kBT709 = 1,				// Rec. ITU-R BT.709-6
	kFCCTitle47 = 4,		// United States Federal Communications Commission Title 47
	kBT601_625 = 5,			// Rec. ITU-R BT.601-6 625, functionally same as code 6
	kBT601_525 = 6,			// Rec. ITU-R BT.601-6 525. functionally same as code 5
	kSMPTE_240M = 7,		// SMPTE 240M
	kBT2020NCL = 9,			// Rec. ITU-R BT.2020-2 non-constant luminance system
	kBT2020CL = 10,			// Rec. ITU-R BT.2020-2 constant luminance system
	kBT2100ICtCp = 14		// Rec. 2100 ICtCp
};

enum class PrEncodingBitDepth : csSDK_int32
{
	k8u = 8,
	k10u = 10,
	k12u = 12,
	k15u = 15,
	k16u = 16,
	k32f = 32
};

[yergin]

Thanks Bruce, that looks promising. Is there currently a way to get these values from the PrSDKColorSpaceID GUID or do I need to wait for the upcoming SDK? And are there plans for a similar Effect API for source clips?

[Bruce Bullis · Accepted solution]

Those constants work, and the values are available, today.

There are currently no plans for any API expansion.

[yergin]

Maybe I'm not explaining myself clearly enough, because this is not really answering what I'm after. I'm making a regular Premiere video filter effect, I don't set the colour spaces anywhere. I want to read the the colourspace premiere sets on the sequence and also the colourspace used to interpret the source clip. I'm able to get a GUID only for the sequence, but I didn't create it and I assume Premiere is creating and storing those colourspaces under it's own GIUDs internally. Is it possible to get that colourspace data from the GUID? If so, can you point me to an API call which does it? Also, is there any chance of getting the source slip's interpretted colourspace?

[Chetan Nanda]

Hi Yergin,

Yes, there are further APIs to get the color space information from the GUID.

Below API which is part of PrSDKColorManagementSuite.h can be use for the same.

       /**

       **             @param1 opaque color space id passed in by the host

       **             @param2 filled in SEI color codes rec if color space

       **             in param1 is of kPrSDKColorSpaceType_SEITags

       **             @Return error code. If success, returns malNoError

       */

       prSuiteError (*GetSEIColorCodesForColorSpace)(

              const PrSDKColorSpaceID *inSDKColorSpaceID,

              prSEIColorCodesRec         *outSEIColorCodesRec);

Let us know if this is what you are looking for.

[yergin]

Thanks Chetan, this is exactly what I'm looking for, however PrSDKColorManagementSuite.h is not included in the latest SDKs available for download (October 2021) from the developer console. How do I get a hold of this API? 

[Bruce Bullis · Accepted solution]

That was an omission. I've sent you the header, directly; future SDK releases will contain PrSDKColorManagementSuite.h.

[yergin]

Wow, what are the chances of that?! No wonder we weren't quite understanding each other!

Thanks for sending that, Bruce, it works like a charm on sequences!

Am I right by assuming there's no straighforward way to get the source media's colour space? Perhaps there's a hacky way by getting the metadata or other info using PF_UtilitySuite, I'll try some things out ... I'm basically wanting to know what transfrom Premiere has done to the source footage which I can gather if I know the colourspace it's been interpretted as. Thanks again!