software-manual.tex

Defines the index of the chroma sampling vertical filter:
\par
\begin{tabular}{cp{0.35\textwidth}}
  0 & Unspecified \\
  1 & Filters signalled within the SEI message \\
  2 & Filters as described in the 5/3 filter description of ITU-T Rec. T.800 | ISO/IEC 15444-1\\
\end{tabular}
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{Knee function SEI message encoder parameters}{tab:sei-knee-function}
\Option{SEIKneeFunctionInfo} &
\Default{false} &
Enables (true) or disables (false) the insertion of the Knee function SEI messages.
\\
\Option{SEIKneeFunctionId} &
\Default{0} &
Specifies Id of Knee function SEI message for a given session.
\\
\Option{SEIKneeFunctionCancelFlag} &
\Default{false} &
Indicates that Knee function SEI message cancels the persistance (true) or follows (false).
\\
\Option{SEIKneeFunctionPersistenceFlag} &
\Default{true} &
Specifies the persistence of the Knee function SEI message.
\\
\Option{SEIKneeFunctionInputDrange} &
\Default{1000} &
Specifies the peak luminance level for the input picture of Knee function SEI messages.
\\
\Option{SEIKneeFunctionInputDispLuminance} &
\Default{100} &
Specifies the expected display brightness for the input picture of Knee function SEI messages.
\\
\Option{SEIKneeFunctionOutputDrange} &
\Default{4000} &
Specifies the peak luminance level for the output picture of Knee function SEI messages.
\\
\Option{SEIKneeFunctionOutputDispLuminance} &
\Default{800} &
Specifies the expected display brightness for the output picture of Knee function SEI messages.
\\
\Option{SEIKneeFunctionNumKneePointsMinus1} &
\Default{2} &
Specifies the number of knee points - 1.
\\
\Option{SEIKneeFunctionInputKneePointValue} &
\Default{} &
Array of input knee point. Default table can be set to the following:
\par
\begin{tabular}{cp{0.45\textwidth}}
600 800 900
\end{tabular}
\\
\Option{SEIKneeFunctionOutputKneePointValue} &
\Default{} &
Array of output knee point. Default table can be set to the following:
\par
\begin{tabular}{cp{0.45\textwidth}}
100 250 450
\end{tabular}
\\
\end{OptionTableNoShorthand}


\begin{OptionTableNoShorthand}{Colour remapping SEI message encoder parameters}{tab:sei-colour-remapping}
\Option{SEIColourRemappingInfoFileRoot (-cri)} &
\Default{\NotSet} &
Specifies the prefix of input Colour Remapping Information file. Prefix is completed by ``_x.txt'' where x is the  POC number.
The contents of the file are a list of the SEI message's syntax element names (in decoding order) immediately followed by a `:' and then the associated value.
An example file can be found in cfg/misc/example_colour_remapping_sei_encoder_0.txt.
\\
\end{OptionTableNoShorthand}

\begin{OptionTableNoShorthand}{Equirectangular Projection SEI message encoder parameters}{tab:sei-erp}
\Option{SEIErpEnabled} &
\Default{false} &
Enables (true) or disables (false) the insertion of equirectangular projection SEI message.
\\
\Option{SEIErpCancelFlag} &
\Default{true} &
Indicates that equirectangular projection SEI message cancels the persistence (true) or follows (false).
\\
\Option{SEIErpPersistenceFlag} &
\Default{false} &
Specifies the persistence of the equirectangular projection SEI message.
\\
\Option{SEIErpGuardBandFlag} &
\Default{false} &
Indicates the existence of guard band areas in the constituent picture.
\\
\Option{SEIErpGuardBandType} &
\Default{0} &
Indicates the type of the guard bands.
\\
\Option{SEIErpLeftGuardBandWidth} &
\Default{0} &
Inicates the width of the guard band on the left side of the onstituent picture.
\\
\Option{SEIErpRightGuardBandWidth} &
\Default{0} &
Inicates the width of the guard band on the right side of the onstituent picture.
\\
\end{OptionTableNoShorthand}

\begin{OptionTableNoShorthand}{Generalized Cubemap Projection SEI message encoder parameters}{tab:sei-gcmp}
\Option{SEIGcmpEnabled} &
\Default{false} &
Enables (true) or disables (false) the insertion of generalized cubemap projection SEI message.
\\
\Option{SEIGcmpCancelFlag} &
\Default{true} &
Indicates that generalized cubemap projection SEI message cancels the persistence (true) or follows (false).
\\
\Option{SEIGcmpPersistenceFlag} &
\Default{false} &
Specifies the persistence of the generalized cubemap projection SEI message.
\\
\Option{SEIGcmpPackingType} &
\Default{0} &
Specifies the packing type.
\par
\begin{tabular}{cp{0.35\textwidth}}
 0 & 6 rows and 1 columns \\
 1 & 3 rows and 2 columns \\
 2 & 2 rows and 3 columns \\
 3 & 1 rows and 6 columns \\
 4 & 1 rows and 5 columns (hemisphere cubemap) \\
 5 & 5 rows and 1 columns (hemisphere cubemap) \\
\end{tabular}
\\
\Option{SEIGcmpMappingFunctionType} &
\Default{0} &
Specifies the mapping function used to adjust the sample locations.
\par
\begin{tabular}{cp{0.35\textwidth}}
 0 & Disabled (conventional cubemap projection) \\
 1 & Equi-angular mapping function \\
 2 & Defined by SEIGcmpFunctionCoeffU, SEIGcmpFunctionUAffectedByVFlag, SEIGcmpFunctionCoeffV, and SEIGcmpFunctionVAffectedByUFlag \\
\end{tabular}
\\
\Option{SEIGcmpFaceIndex} &
\Default{} &
An array that specifies the face index for the faces packed in the cubemap projected picture.
\par
\begin{tabular}{cp{0.35\textwidth}}
 0 & Front face \\
 1 & Back face \\
 2 & Top face \\
 3 & Bottom face \\
 4 & Right face \\
 5 & Left face \\
\end{tabular}
\\
\Option{SEIGcmpFaceRotation} &
\Default{} &
An array that specifies the rotation to be applied to the faces.
\par
\begin{tabular}{cp{0.35\textwidth}}
 0 & No rotation \\
 1 & 90 degree anticlockwise \\
 2 & 180 degree anticlockwise \\
 3 & 270 degree anticlockwise \\
\end{tabular}
\\
\Option{SEIGcmpFunctionCoeffU} &
\Default{} &
An array that specifies the coefficients used in the cubemap mapping function of the u-axis for the faces when SEIGcmpMappingFunctionType is set to 2.
\\
\Option{SEIGcmpFunctionUAffectedByVFlag} &
\Default{} &
An array that specifies whether the cubemap mapping function of the u-axis refers to the v position of the sample location for the faces when SEIGcmpMappingFunctionType is set to 2.
\\
\Option{SEIGcmpFunctionCoeffV} &
\Default{} &
An array that specifies the coefficients used in the cubemap mapping function of the v-axis for the faces when SEIGcmpMappingFunctionType is set to 2.
\\
\Option{SEIGcmpFunctionVAffectedByUFlag} &
\Default{} &
An array that specifies whether the cubemap mapping function of the v-axis refers to the u position of the sample location for the faces when SEIGcmpMappingFunctionType is set to 2.
\\
\Option{SEIGcmpGuardBandFlag} &
\Default{false} &
Indicates the existence of guard band areas in the picture.
\\
\Option{SEIGcmpGuardBandType} &
\Default{0} &
Indicates the type of the guard bands.
\par
\begin{tabular}{cp{0.35\textwidth}}
 0 & Unspecified \\
 1 & Suffice for interpolation of sample values at sub-pel sample fractional locations within the coded face. \\
 2 & Represent actual picture content that is spherically adjacent to the content in the coded face at quality that gradually changes from the picture quality of the coded face to that of the spherically adjacent region. \\
 3 & Represent actual picture content that is spherically adjacent to the content in the coded face at a similar picture quality as within the coded face. \\
\end{tabular}
\\
\Option{SEIGcmpGuardBandBoundaryExteriorFlag} &
\Default{false} &
Enables (true) or disables (false) the boundary guard bands.
\\
\Option{SEIGcmpGuardBandSamplesMinus1} &
\Default{0} &
Specifies the number of guard band samples minus 1 used in the cubemap projected picture.
\\
\end{OptionTableNoShorthand}

\begin{OptionTableNoShorthand}{Sphere Rotation SEI message encoder parameters}{tab:sei-sphere-rotation}
\Option{SEISphereRotationEnabled} &
\Default{false} &
Enables (true) or disables (false) the insertion of sphere rotation SEI message.
\\
\Option{SEISphereRotationCancelFlag} &
\Default{true} &
Indicates that the sphere rotation SEI message cancels the persistence (true) or follows (false).
\\
\Option{SEISphereRotationPersistenceFlag} &
\Default{false} &
Specifies the persistence of the sphere rotation SEI message.
\\
\Option{SEISphereRotationYaw} &
\Default{0} &
Specifies the value of the yaw rotation angle.
\\
\Option{SEISphereRotationPitch} &
\Default{0} &
Specifies the value of the pitch rotation angle.
\\
\Option{SEISphereRotationRoll} &
\Default{0} &
Specifies the value of the roll rotation angle.
\\
\end{OptionTableNoShorthand}

\begin{OptionTableNoShorthand}{Region-wise packing SEI message encoder parameters}{tab:sei-rwp}
\Option{SEIRwpEnabled} &
\Default{false} &
Enables (true) or disables (false) the insertion of region-wise packing SEI message.
\\
\Option{SEIRwpCancelFlag} &
\Default{true} &
Indicates that RWP SEI message cancels the persistence (true) or follows (false).
\\
\Option{SEIRwpPersistenceFlag} &
\Default{false} &
Specifies the persistence of the RWP SEI message.
\\
\Option{SEIRwpConstituentPictureMatchingFlag} &
\Default{false} &
Specifies the RWP SEI message applies individually to each constituent picture (true) or to the projected picture (false).
\\
\Option{SEIRwpNumPackedRegions} &
\Default{0} &
Specifies the number of packed regions when constituent picture matching flag is equal to 0.
\\
\Option{SEIRwpProjPictureWidth} &
\Default{0} &
Specifies the width of the projected picture.
\\
\Option{SEIRwpProjPictureHeight} &
\Default{0} &
Specifies the height of the projected picture.
\\
\Option{SEIRwpPackedPictureWidth} &
\Default{0} &
Specifies the width of the packed picture.
\\
\Option{SEIRwpPackedPictureHeight} &
\Default{0} &
Specifies the height of the packed picture.
\\
\Option{SEIRwpTransformType} &
\Default{} &
An array that specifies the rotation and mirroring to be applied to the packed regions.
\\
\Option{SEIRwpGuardBandFlag} &
\Default{} &
An array that specifies the existence of guard band in the packed regions.
\\
\Option{SEIRwpProjRegionWidth} &
\Default{} &
An array that specifies the width of the projected regions.
\\
\Option{SEIRwpProjRegionHeight} &
\Default{} &
An array that specifies the height of the projected regions.
\\
\Option{SEIRwpGuardBandFlag} &
\Default{} &
An array that specifies the existence of guard band in the packed regions.
\\
\Option{SEIRwpProjRegionTop} &
\Default{} &
An array that specifies the top sample row of the projected regions.
\\
\Option{SEIRwpProjRegionLeft} &
\Default{} &
An array that specifies the left-most sample column of the projected regions. 
\\
\Option{SEIRwpPackedRegionWidth} &
\Default{} &
An array that specifies the width of the packed regions.
\\
\Option{SEIRwpPackedRegionHeight} &
\Default{} &
An array that specifies the height of the packed regions.
\\
\Option{SEIRwpPackedRegionTop} &
\Default{} &
An array that specifies the top luma sample row of the packed regions.
\\
\Option{SEIRwpPackedRegionLeft} &
\Default{} &
An array that specifies the left-most luma sample column of the packed regions.
\\
\Option{SEIRwpLeftGuardBandWidth} &
\Default{} &
An array that specifies the width of the guard band on the left side of the packed regions.
\\
\Option{SEIRwpRightGuardBandWidth} &
\Default{} &
An array that specifies the width of the guard band on the right side of the packed regions.
\\
\Option{SEIRwpTopGuardBandHeight} &
\Default{} &
An array that specifies the height of the guard band above the packed regions.
\\
\Option{SEIRwpBottomGuardBandHeight} &
\Default{} &
An array that specifies the height of the guard band below the packed regions.
\\
\Option{SEIRwpGuardBandNotUsedForPredFlag} &
\Default{} &
An array that specifies if the guard bands is used in the inter prediction process.
\\
\Option{SEIRwpGuardBandType} &
\Default{} &
An array that specifies the type of the guard bands for the packed regions.
\\
\end{OptionTableNoShorthand}

\begin{OptionTableNoShorthand}{Omni Viewport SEI message encoder parameters}{tab:sei-omni-viewport}
\Option{SEIOmniViewportEnabled} &
\Default{false} &
Enables (true) or disables (false) the insertion of omni viewport SEI message.
\\
\Option{SEIOmniViewportId} &
\Default{0} &
Contains an identifying number that may be used to identify the purpose of the one or more recommended viewport regions.
\\
\Option{SEIOmniViewportCancelFlag} &
\Default{true} &
Indicates that the omni viewport SEI message cancels the persistence (true) or follows (false).
\\
\Option{SEIOmniViewportPersistenceFlag} &
\Default{false} &
Specifies the persistence of the omni viewport SEI message.
\\
\Option{SEIOmniViewportCntMinus1} &
\Default{0} &
Specifies the number of recommended viewport regions minus 1.
\\
\Option{SEIOmniViewportAzimuthCentre} &
\Default{} &
An array that indicates the centre of the i-th recommended viewport region.
\\
\Option{SEIOmniViewportElevationCentre} &
\Default{} &
An array that indicates the centre of the i-th recommended viewport region.
\\
\Option{SEIOmniViewportTiltCentre} &
\Default{} &
An array that indicates the tilt angle of the i-th recommended viewport region.
\\
\Option{SEIOmniViewportHorRange} &
\Default{} &
An array that indicates the azimuth range of the i-th recommended viewport region.
\\
\Option{SEIOmniViewportVerRange} &
\Default{} &
An array that indicates the elevation range of the i-th recommended viewport region.
\\
\end{OptionTableNoShorthand}

\begin{OptionTableNoShorthand}{Sample Aspect Ratio Information SEI message encoder parameters}{tab:sei-sari}
\Option{SEISampleAspectRatioInfo} &
\Default{false} &
Enables (true) or disables (false) the insertion of Sample Aspect Ratio Information SEI message.
\\
\Option{SEISARICancelFlag} &
\Default{true} &
Indicates that the Sample Aspect Ratio Information SEI message cancels the persistence (true) or follows (false).
\\
\Option{SEISARIPersistenceFlag} &
\Default{false} &
Specifies the persistence of the Sample Aspect Ratio Information SEI message.
\\
\Option{SEISARIAspectRatioIdc} &
\Default{0} &
Specifies aspect ratio IDC as defined in the standard.
\\
\Option{SEISARISarWidth} &
\Default{0} &
Specifies the horizontal size of the sample aspect ratio, if SEISARIAspectRatioIdc is equal to 255.
\\
\Option{SEISARISarHeight} &
\Default{0} &
Specifies the vertical size of the sample aspect ratio, if SEISARIAspectRatioIdc is equal to 255.
\\
\end{OptionTableNoShorthand}

\begin{OptionTableNoShorthand}{Frame-Field Information SEI message encoder parameters}{tab:sei-frame-field}
\Option{SEIFrameFieldInfo} &
\Default{false} &
Enables (true) or disables (false) the insertion of Frame-Field Information SEI message.
\\
\end{OptionTableNoShorthand}

\begin{OptionTableNoShorthand}{Subpicture Level Information SEI message encoder parameters}{tab:sei-subpic-level}
\Option{SEISubpictLevelInfoEnabled} &
\Default{false} &
Enables (true) or disables (false) the insertion of Subpicture Level Information SEI message.
Note, currently no other configuration options are available, because this depends on the number of subpictures,
which are still not supported in the software. An example SEI with dummy values is generated, when the option is enabled.
\\
\Option{SEISubpicLevelInfoExplicitFraction} &
\Default{false} &
Enable signalling of explicit fraction for each level and subpicture
\\
\Option{SEISubpicLevelInfoNumSubpics} &
\Default{1} &
Number of subpictures in context of the SEI. Has to be equal to NumSubpics
\\
\Option{SEISubpicLevelInfoMaxSublayers} &
\Default{1} &
Number of sublayers in context of the SEI. Has to be equal to vps_max_sublayers_minus1 + 1
\\
\Option{SEISubpicLevelInfoSublayerInfoPresentFlag} &
\Default{false} &
Enable signalling of level information for each sublayer
\par
\begin{tabular}{cp{0.45\textwidth}}
1 & Each sublayer specifies its own level information \\
0 & All sublayers use the same level information \\
\end{tabular}
\\
\Option{SEISubpicLevelInfoNonSubpicLayersFractions} &
\Default{""} &
List of fraction of levels to be signalled for non-subpicture layers.
\par
\begin{tabular}{p{0.49\columnwidth}}
When sli_sublayer_info_present_flag = 0, the number of input elements shall be equal to numReflevels. List is ordered by level.\\
When sli_sublayer_info_present_flag = 1, the number of input elements shall be equal to numReflevels * maxSublayers. List is ordered by level then sublayer. For example, let Amn denotes the reference level indices for the m-th sublayer and and n-th reference level, the first N elements (A00...A0n-1) denotes the RefLevelFractions for N levels in the 0-th sublayer, and the following N elements (A10...A1n-1) denotes the RefLevelFractions for N levels in the 1st sublayer, and so on, untill all MxN elements specified.\\
\end{tabular}
\\
\Option{SEISubpicLevelInfoRefLevels} &
\Default{""} &
List of reference levels to be signalled.
\par
\begin{tabular}{p{0.49\columnwidth}}
When sli_sublayer_info_present_flag = 0, the number of input elements shall be equal to numReflevels. List is ordered by level.\\
When sli_sublayer_info_present_flag = 1, the number of input elements shall be equal to numReflevels * maxSublayers. List is ordered by level then sublayer. For example, let Amn denotes the reference level indices for the m-th sublayer and and n-th reference level, the first N elements (A00...A0n-1) denotes the RefLevelFractions for N levels in the 0-th sublayer, and the following N elements (A10...A1n-1) denotes the RefLevelFractions for N levels in the 1st sublayer, and so on, untill all MxN elements specified.\\
\end{tabular}
\\
\Option{SEISubpicLevelInfoRefLevelFractions} &
\Default{""} &
List of fractions of levels to be signalled.
\par
\begin{tabular}{p{0.49\columnwidth}}
When sli_sublayer_info_present_flag = 0, the number of input elements shall be equal to numSubpics * numReflevels. List is ordered by subpicture then level.\\
When sli_sublayer_info_present_flag = 1, the number of elements shall be equal to numSubpics * numReflevels * maxSublayers. List is ordered by subpicture then level then sublayer. For example, let Bmnk  denotes the reference level fractions for the m-th sublayer and n-th reference level and k-th subpicture, the first K elements (B000...B00k-1) denotes the RefLevelFractions for K subpictures in the 0-th levels and 0-th sublayer, and followed by K elements (B010...B0n-1k-1) denotes the RefLevelFractions for K subpictures in the 1st level and 0-th sublayer, and so on, untill all M*N*K elements specified. In another word, among all the specified M*N*K elements, the first N*K elements specify RefLevelFractions for N*K subpictures of N levels in the 0-th sublayer, and the following N*K elements specify RefLevelFractions for N*K subpictures of N levels in the 1st sublayer, and etc.\\
\end{tabular}
\\
\end{OptionTableNoShorthand}


\begin{OptionTableNoShorthand}{Content light level info SEI message encoder parameters}{tab:sei-content-light-level}
\Option{SEICLLEnabled} &
\Default{false} &
Enables or disables the insertion of the content light level SEI message.
\\
\Option{SEICLLMaxContentLightLevel} &
\Default{4000} &
When not equal to 0, specifies an upper bound on the maximum light level among all individual samples in a 4:4:4 representation of red, green, and blue colour primary intensities in the linear light domain for the pictures of the CLVS, in units of candelas per square metre. When equal to 0, no such upper bound is indicated.
\\
\Option{SEICLLMaxPicAvgLightLevel} &
\Default{0} &
When not equal to 0, specifies an upper bound on the maximum average light level among the samples in a 4:4:4 representation of red, green, and blue colour primary intensities in the linear light domain for any individual picture of the CLVS, in units of candelas per square metre. When equal to 0, no such upper bound is indicated.
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{Alternative transfer characteristics SEI message encoder parameters}{tab:sei-alternative-transfer-characteristics}
\Option{SEIPreferredTransferCharacteristics} &
\Default{18} &
Indicates a preferred alternative value for the transfer_characteristics syntax element that is indicated by the colour description syntax of VUI parameters.
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{Ambient viewing environment SEI message encoder parameters}{tab:sei-ambient-viewing-environment}
\Option{SEIAVEEnabled} &
\Default{false} &
Enables or disables the insertion of the ambient viewing environment SEI message.
\\
\Option{SEIAVEAmbientIlluminance} &
\Default{100000} &
Specifies the environmental illuminance of the ambient viewing environment in units of 1/10000 lux. The value shall not be 0.
\\
\Option{SEIAVEAmbientLightX} &
\Default{15635} &
Specifies the x chromaticity coordinate, according to the CIE 1931 definition, of the environmental ambient light in the nominal viewing environment in normalized increments of 1/50000. The value shall be in the range of 0 to 50,000, inclusive.
\\
\Option{SEIAVEAmbientLightY} &
\Default{16450} &
Specifies the y chromaticity coordinate, according to the CIE 1931 definition, of the environmental ambient light in the nominal viewing environment in normalized increments of 1/50000. The value shall be in the range of 0 to 50,000, inclusive.
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{Content colour volume SEI message encoder parameters}{tab:sei-content-colour-volume}
\Option{SEICCVEnabled} &
\Default{false} &
Enables or disables the insertion of the content colour volume SEI message.
\\
\Option{SEICCVCancelFlag} &
\Default{0} &
Specifies the persistence of any previous content colour volume SEI message in output order.
\\
\Option{SEICCVPersistenceFlag} &
\Default{1} &
Specifies the persistence of the content colour volume SEI message for the current layer.
\\
\Option{SEICCVPrimariesPresent} &
\Default{1} &
Specifies whether the CCV primaries are present in the content colour volume SEI message.
\\
\Option{m_ccvSEIPrimariesX0} &
\Default{0.300} &
Specifies the x coordinate, according to the CIE 1931 definition, of the first (green) colour primary component in normalized increments of 1/50000.
\\
\Option{m_ccvSEIPrimariesY0} &
\Default{0.600} &
Specifies the y coordinate, according to the CIE 1931 definition, of the first (green) colour primary component in normalized increments of 1/50000.
\\
\Option{m_ccvSEIPrimariesX1} &
\Default{0.150} &
Specifies the x coordinate, according to the CIE 1931 definition, of the second (blue) colour primary component in normalized increments of 1/50000.
\\
\Option{m_ccvSEIPrimariesY1} &
\Default{0.060} &
Specifies the y coordinate, according to the CIE 1931 definition, of the second (blue) colour primary component in normalized increments of 1/50000.
\\
\Option{m_ccvSEIPrimariesX2} &
\Default{0.640} &
Specifies the x coordinate, according to the CIE 1931 definition, of the third (red) colour primary component in normalized increments of 1/50000.
\\
\Option{m_ccvSEIPrimariesY2} &
\Default{0.330} &
Specifies the y coordinate, according to the CIE 1931 definition, of the third (red) colour primary component in normalized increments of 1/50000.
\\
\Option{SEICCVMinLuminanceValuePresent} &
\Default{1} &
Specifies whether the CCV min luminance value is present in the content colour volume SEI message.
\\
\Option{SEICCVMinLuminanceValue} &
\Default{0.0} &
specifies the CCV min luminance value in the content colour volume SEI message.
\\
\Option{SEICCVMaxLuminanceValuePresent} &
\Default{1} &
Specifies whether the CCV max luminance value is present in the content colour volume SEI message.
\\
\Option{SEICCVMaxLuminanceValue} &
\Default{0.1} &
specifies the CCV max luminance value in the content colour volume SEI message.
\\
\Option{SEICCVAvgLuminanceValuePresent} &
\Default{1} &
Specifies whether the CCV avg luminance value is present in the content colour volume SEI message.
\\
\Option{SEICCVAvgLuminanceValue} &
\Default{0.01} &
specifies the CCV avg luminance value in the content colour volume SEI message.
\\
\end{OptionTableNoShorthand}




%\Option{SEITimeCode} &
%\Default{false} &
%When true, generate time code SEI messages.
%\\

%%
%%
%%
\subsection{Hardcoded encoder parameters}
\begin{MacroTable}{CommonDef.h constants}
ADAPT_SR_SCALE &
1 &
Defines a scaling factor used to derive the motion search range is
adaptive (see ASR configuration parameter). Default value is 1.
\\

MAX_GOP &
64 &
maximum size of value of hierarchical GOP.
\\

MAX_NUM_REF &
4 &
maximum number of multiple reference frames
\\

MAX_NUM_REF_LC &
8 &
maximum number of combined reference frames
\\

AMVP_MAX_NUM_CANDS &
2 &
maximum number of final candidates
\\

AMVP_MAX_NUM_CANDS_MEM &
3 &
\\

MRG_MAX_NUM_CANDS &
5 &
\\

DYN_REF_FREE &
off &
dynamic free of reference memories
\\

MAX_TLAYER &
8 &
maximum number of temporal layers
\\

ADAPT_SR_SCALE &
on &
division factor for adaptive search range
\\

EARLY_SKIP_THRES &
1.5 &
early skip if RD < EARLY_SKIP_THRES*avg[BestSkipRD]
\\

MAX_NUM_REF_PICS &
16 &
\\

MAX_CHROMA_FORMAT_IDC &
3 &
\\
\end{MacroTable}

\subsubsection*{TypeDef.h}
Numerous constants that guard individual adoptions are defined within
\url{source/Lib/TLibCommon/TypeDef.h}.


%%
%%
%%
\clearpage
\section{Using the decoder}
\subsection{General}
\begin{minted}{bash}
DecoderApp -b str.bin -o dec.yuv [options]
\end{minted}

\begin{OptionTableNoShorthand}{Decoder options}{tab:decoder-options}
\Option{(--help)} &
%\ShortOption{\None} &
\Default{\None} &
Prints usage information.
\\

\Option{BitStreamFile (-b)} &
%\ShortOption{-b} &
\Default{\NotSet} &
Defines the input bit stream file name.
\\

\Option{ReconFile (-o)} &
%\ShortOption{-o} &
\Default{\NotSet} &
Defines the reconstructed video file name. If empty, no file is generated. If the bitstream contains multiple layer and no single target layer is specified (i.e. TargetLayer=-1), a reconstructed file is written for each layer and the layer index is added as suffix to ReconFile. If one or more dots exist in the file name, the layer id is added before the last dot, e.g. 'decoded.yuv' becomes 'decoded0.yuv' for layer id 0, 'decoded' becomes 'decoded0'.
\\

\Option{OplFile (-opl)} &
%\ShortOption{-o} &
\Default{\NotSet} &
Defines the output log file name (*.opl file). If empty, no file is generated. Each output picture log file contains one row for each output picture in the bitstream, in output order. Each row contains the following information, as CSV:	PicOrderCntVal, pic\_width\_max\_in\_luma\_samples, pic\_height\_max\_in\_luma\_samples, MD5 checksum for the Y component, MD5 checksum for the U component, MD5 checksum for the V component. The format of output log file is specified in JVET-P2008. 
\\

\Option{SkipFrames (-s)} &
%\ShortOption{-s} &
\Default{0} &
Defines the number of pictures in decoding order to skip.
\\

\Option{MaxTemporalLayer (-t)} &
%\ShortOption{-t} &
\Default{-1} &
Defines the maximum temporal layer to be decoded. If -1, then all layers are decoded.
\\

\Option{TarDecLayerIdSetFile (-l)} &
%\ShortOption{-t} &
\Default{\NotSet} &
Specifies the targetDecLayerIdSet file name. The file would contain white-space separated LayerId values of the layers that are to be decoded.
Omitting the parameter, or using a value of -1 in the file decodes all layers.
\\

\Option{OutputBitDepth (-d)} &
%\ShortOption{-d} &
\Default{0 \\ (Native)} &
Specifies the luma bit-depth of the reconstructed YUV file (the value 0 indicates
that the native bit-depth is used)
\\

\Option{OutputBitDepthC} &
%\ShortOption{\None} &
\Default{0 \\ (Native)} &
Defines the chroma bit-depth of the reconstructed YUV file (the value 0 indicates
that the native bit-depth is used)
\\

\Option{TargetLayer (-p)} &
%\ShortOption{-p} &
\Default{-1 \\ (Native)} &
Specifies the target bitstream Layer to be decoded. (the value -1 indicates
that decoding the whole bitstream )
\\

\Option{SEIDecodedPictureHash} &
%\ShortOption{\None} &
\Default{1} &
Enable or disable verification of any Picture hash SEI messages. When
this parameter is set to 0, the feature is disabled and all messages are
ignored. When set to 1 (default), the feature is enabled and the decoder
has the following behaviour:
\begin{itemize}
\item
  If Picture hash SEI messages are included in the bit stream, the same type
  of hash is calculated for each decoded picture and written to the
  log together with an indication whether the calculted value matches
  the value in the SEI message. 
  Decoding will continue even if there is a mismatch.

\item
  After decoding is complete, if any MD5sum comparison failed, a warning
  is printed and the decoder exits with the status EXIT_FAILURE

\item
  The per-picture MD5 log message has the following formats:
  [MD5:d41d8cd98f00b204e9800998ecf8427e,(OK)],
  [MD5:d41d8cd98f00b204e9800998ecf8427e,(unk)],
  [MD5:d41d8cd98f00b204e9800998ecf8427e,(***ERROR***)] [rxMD5:b9e1...]
  where, "(unk)" implies that no MD5 was signalled for this picture,
  "(OK)" implies that the decoder agrees with the signalled MD5,
  "(***ERROR***)" implies that the decoder disagrees with the signalled
  MD5. "[rxMD5:...]" is the signalled MD5 if different.
\end{itemize}
\\

\Option{OutputDecodedSEIMessagesFilename} &
%\ShortOption{\None} &
\Default{\NotSet} &
When a non-empty file name is specified, information regarding any decoded SEI messages will be output to the indicated file. If the file name is '-', then stdout is used instead.
\\

\Option{SEIColourRemappingInfoFilename} &
%\ShortOption{\None} &
\Default{\NotSet} &
Specifies that the colour remapping SEI message should be applied to the output video, with the output written to this file.
If no value is specified, the SEI message is ignored and no mapping is applied.
\\

\Option{OutputColourSpaceConvert} &
\Default{\NotSet} &
Specifies the colour space conversion to apply to 444 video. Permitted values are:
\par
\begin{tabular}{lp{0.45\textwidth}}
  UNCHANGED   & No colour space conversion is applied \\
  YCrCbToYCbCr & Swap the second and third components \\
  GBRtoRGB     & Reorder the three components \\
\end{tabular}
If no value is specified, no colour space conversion is applied. The list may eventually also include RGB to YCbCr or YCgCo conversions.\\
\\

\Option{PYUV} &
\Default{false} &
When true, output 10-bit and 12-bit YUV data as 5-byte and 3-byte (respectively) packed YUV data. See doc/pyuv_format.pdf for details. Ignored for interlaced output.
\\

\Option{SEINoDisplay} &
\Default{false} &
When true, do not output frames for which there is an SEI NoDisplay message.
\\

\Option{ClipOutputVideoToRec709Range} &
%\ShortOption{\None} &
\Default{0} &
If 1 then clip output video to the Rec. 709 Range on saving when OutputBitDepth is less than InternalBitDepth.
\\

\end{OptionTableNoShorthand}


\subsection{Using the decoder analyser}
If the decoder is compiled with the macro RExt__DECODER_DEBUG_BIT_STATISTICS defined as 1 (either externally, or by editing TypeDef.h), the decoder will gather fractional bit counts associated with the different syntax elements, producing a table of the number of bits per syntax element, and where appropriate, according to block size and colour component/channel.
The Linux makefile will compile both the analyser and standard version when the `all' or `everything' target is used (where the latter will also build  high-bit-depth executables).



\section{Block statistics extension}
\label{sec:block-stat-extens}

The block statistics extension enables straightforward visualization and statistical analysis of coding tool
usage in encoded bitstreams. The extension enables the reference
software encoder and decoder to write out statistics files in a configurable
way, which in turn can be loaded into a suitable YUV player for overlay of the
reconstructed YUV sequence, or can be used for statistical analysis at a
selectable scope (e.g. block/picture/sequence level). An example implementation
for such visualization is available with the open-source YUView player
(\url{https://github.com/IENT/YUView}). 


\subsection{Usage}
\label{sec:usage}

The software has to be compiled with the macros ENABLE_TRACING and
K0149_BLOCK_STATISTICS  defined as 1. The statistics can be written by either
encoder or decoder.

The extension adds additional trace channels to the ``dtrace'' functionality of
the software. The following trace channels were added:
\begin{description}
\item[D_BLOCK_STATISTICS_ALL] All syntax elements are written, no matter whether
  they are actually encoded or derived.
\item[D_BLOCK_STATISTICS_CODED] Tries to write only syntax elements, which have
  also been encoded.
\end{description}

The following additional encoder options are available (part of ``dtrace''). See
the file dtrace_next.h for more details.

\begin{OptionTableNoShorthand}{Decoder options}{tab:decoder-block-statistics}
\Option{TraceFile} &
%\ShortOption{\None} &
\Default{\None} &
File name of the produced trace file.
\\

\Option{TraceRule} &
%\ShortOption{-b} &
\Default{\NotSet} &
Specifies which traces should be saved, and for which POCs.
\\

\end{OptionTableNoShorthand}

Concrete examples of calls for  generating a block statistics file are:
\begin{minted}{bash}
bin/DecoderAppStatic -b str/BasketballDrive_1920x1080_QP37.vvc \
    --TraceFile="stats/BasketballDrive_1920x1080_QP37_coded.vtmbmsstats" \
    --TraceRule="D_BLOCK_STATISTICS_CODED:poc>=0"

bin/DecoderAppStatic -b str/BasketballDrive_1920x1080_QP37.vvc \
    --TraceFile="stats/BasketballDrive_1920x1080_QP37_all.vtmbmsstats" \
    --TraceRule="D_BLOCK_STATISTICS_ALL:poc>=0"   
\end{minted}


\subsection{Block statistics file formats}
\label{sec:block-stat-file}
The trace file will contain a header listing information of all available block
statistics. For each statistic it lists a type and a scale for vectors or range
for integers if applicable: 
\begin{verbatim}
# VTMBMS Block Statistics
# Sequence size: [832x 480]
# Block Statistic Type: PredMode; Flag; 
# Block Statistic Type: MergeFlag; Flag; 
# Block Statistic Type: MVL0; Vector; Scale: 4
# Block Statistic Type: MVL1; Vector; Scale: 4
# Block Statistic Type: IPCM; Flag; 
# Block Statistic Type: Y_IntraMode; Integer; [0, 73]
# Block Statistic Type: Cb_IntraMode; Integer; [0, 73]
\end{verbatim}

Two formats are available for the statistics for each block, a human readable
format and a CSV based format. The header remains the same for both cases. 

For both formats each row contains the information for one block statistic. The
order of the data is: picture order count (POC), location of top left corner of
the block, size of the block, name of the statistic, and value of the
statistic. 
The macro BLOCK_STATS_AS_CSV is available in order to choose the required format.
The human readable format can also be easily processed with other software, for
example YUView, using regular expressions. The CSV based formats provides the
universal interface required by spreadsheet applications.

The human readable format is based on the format used for the other dtrace
statistics. Some examples for this format are:
\begin{verbatim}
BlockStat: POC 16 @( 112,   0) [ 8x 8] SkipFlag=1
BlockStat: POC 16 @( 112,   0) [ 8x 8] InterDir=1
BlockStat: POC 16 @( 112,   0) [ 8x 8] MergeFlag=1
BlockStat: POC 16 @( 112,   0) [ 8x 8] MergeIdx=0
BlockStat: POC 16 @( 112,   0) [ 8x 8] MergeType=0
BlockStat: POC 16 @( 112,   0) [ 8x 8] MVPIdxL0=255
BlockStat: POC 16 @( 112,   0) [ 8x 8] MVPNumL0=255
BlockStat: POC 16 @( 112,   0) [ 8x 8] RefIdxL0=0
BlockStat: POC 16 @( 112,   0) [ 8x 8] MVDL0={   0,   0}
BlockStat: POC 16 @( 112,   0) [ 8x 8] MVL0={ -70,  18}
BlockStat: POC 16 @( 112,   8) [ 8x 8] PredMode=0
BlockStat: POC 16 @( 112,   8) [ 8x 8] PartSize=0
\end{verbatim}

Some examples of the CSV based format are:
\begin{verbatim}
BlockStat;16; 112;   0; 8; 8;SkipFlag;1
BlockStat;16; 112;   0; 8; 8;InterDir;1
BlockStat;16; 112;   0; 8; 8;MergeFlag;1
BlockStat;16; 112;   0; 8; 8;MergeIdx;0
BlockStat;16; 112;   0; 8; 8;MergeType;0
BlockStat;16; 112;   0; 8; 8;MVPIdxL0;255
BlockStat;16; 112;   0; 8; 8;MVPNumL0;255
BlockStat;16; 112;   0; 8; 8;RefIdxL0;0
BlockStat;16; 112;   0; 8; 8;MVDL0;   0;   0
BlockStat;16; 112;   0; 8; 8;MVL0; -70;  18
BlockStat;16; 112;   8; 8; 8;PredMode;0
BlockStat;16; 112;   8; 8; 8;PartSize;0
\end{verbatim}

\subsection{Visualization}
\label{sec:visualization}

The block statistics can be viewed with YUView, which is freely available under
GPLv3: \url{https://github.com/IENT/YUView}. The latest releases and the master
branch have the functionality required for  viewing the block statistics. YUView
assumes that the file extension of block statistics file is
“.vtmbmsstats”. However, if a file is not recognized you can choose from a list
of supported file formats.


Statistics can be overlaid with YUV sequences. Some example snapshots are:

\begin{figure}[htpb]
  \centering
  \includegraphics[width=0.8\linewidth]{figures/YUView}
  \caption{YUView}
  \label{fig:yuview}
\end{figure}

\begin{figure}[htpb]
  \centering
  \includegraphics[width=0.5\linewidth]{figures/raceHorsesShot2MotionVectors}
  \caption{Motion vectors}
  \label{fig:motion-vectors}
\end{figure}


\begin{figure}[htpb]
  \centering
  \includegraphics[width=0.5\linewidth]{figures/raceHorsesShot3SkipFlag}
  \caption{Skip flag}
  \label{fig:skip-flag}
\end{figure}

\subsection{Adding statistics}
\label{sec:adding-statistics}

In order to add further block statistics, do the following:


\begin{description}
\item[source/Lib/CommonLib/dtrace_blockstatistics.h]
  Add your statistic to the BlockStatistic enum:	
\begin{minted}{c++}
enum class BlockStatistic {
  // general
  PredMode,
  PartSize,
  Depth,