Skip to content

Statistics Extension Syntax

Jump to bottom
Christian edited this page Sep 19, 2021 · 4 revisions

The Statistics File Syntax

The output file is written as a csv file (columns seperated by ';'), and therefore the words "column" and "row" will be used to describe the entries of the file. The file can be devided into a "header" and a "data-part", where each line in the header starts with a '%'.

The Data-Part

First of all, each line in the data-part represents an object that shall be displayed by the YUView player. The first eigth columns in each line always contain the following entries:

  1. Picture Order Count (POC)
  2. X-position of the left top pixel in the block
  3. Y-position of the left top pixel in the block
  4. Width of the block
  5. Height of the block
  6. Type-ID
  7. Type specific value or x-component of a vector
  8. (Y-Component of a vector)

The first five columns should be self explaining. The sixth line (type-ID) however "links" the objekt to to a certain type, specified in the header. The seventh column may contain either a "type specific value" (more to that when explaing the header) or the x-component of a vector, if this line represents a vector. The eigth column is only filled (with the y-component of a vector), if the line represents a vector.

❗ Note: The order of the entries in the stats file is important. For performance reasons we do not support a random mixture of POC and type values. Internally, we save a pointer into the file for each POC/type combination for efficient on the fly parsing. This means that all values for each combination of POC and Type must be grouped together in the file. If this is not the case then part of the data will not be displayed.

The Header

Each line in the Header starts with a '%'; commentaries (that is lines not meant for automatic interpretation) shall start with two columns that containing a '%' each. In the first line of the Header, the syntax-version of the file is specified:

  1. '%'
  2. 'syntax-version'
  3. vx.xx

In the second line of the Header, the sequence specifications are specified:

  1. '%'
  2. 'seq-specs'
  3. sequence basename (string)
  4. layer id (string)
  5. sequence width (int)
  6. sequence height (int)
  7. framerate (float)

Declaration of types

For each type declared in the Header, there is a line containg the keyword "type" in its first column. The entries in these lines always are:

  1. '%'
  2. 'type'
  3. Type-ID, which can be referenced in the lines in the data-part
  4. Type-name, e.g. "IntraLumaDir" or "MVSkipL1"
  5. One of the keywords "map", "range" or "vector"

The keyword "map" implies, that for this type, each "type specific value" of a line of this type in the data-part is mapped to a specific colour (RGBa 8bit). To specify these colors, the "type-line" is followed by lines starting with the keyword "mapColor", which all have the following entries:

  1. '%'
  2. 'mapColor'
  3. Value, for which the specified color shall be used (if the "type specific value" of a line of this type in the data-part equals this value)
  4. Red-component of the specified color
  5. Green-component of the specified color
  6. Blue-component of the specified color
  7. Alpha-component of the specified color

The keyword "range" implies, that a range for possible values of the "type specific value"s of lines of this type in the data-part is mapped on a color range specified in the following line, which starts with the keyword "range" and contains the following entries:

  1. '%'
  2. 'range'
  3. Minimum possible value for the "type specific value"
  4. Maximum possible value for the "type specific value"
  5. Minimum red-component
  6. Maximum red-component
  7. Minimum green-component
  8. Maximum green-component
  9. Minimum blue-component
  10. Maximum blue-component
  11. Minimum alpha-component
  12. Maximum alpha-component

Alternatively you can select from one of the built-in color ranges using the keyword "defaultRange":

  1. '%'
  2. 'defaultRange'
  3. Minimum possible value for the "type specific value"
  4. Maximum possible value for the "type specific value"
  5. Name of the default color range

You can choose from one of the following built-in color ranges: heat, jet, hsv, hot, cool, spring, summer, autumn, winter, gray, bone, copper, pink and lines. You might recognize them from matlabs 'colormap' command.

Additionally the following color maps support maps with 3 colors on a linear scale. They are especially useful if you have values that are centered around zero. This way positive values map to the one color and negative values to the other one.

The 3 color color maps

Another line with the keyword "scaleToBlockSize" can follow (at type "range" and at type "defaultRange"), signaling if the actual value written in the "type specific value"-fields should be visualized as is, or if the "type specific value" should be scaled relative to the size of the current block (e.g. the number of significant coefficients in TUs can be scaled to the size of each TU, giving something like a density of coefficients).

CAVE: in this case the minimum and maximum value specified with "range" or "defaultRange" command should also be scaled. (i.e. a defaultRange for significant coefficients could look like this: %;defaultRange;0;1;hsv - 0 meaning no significant coefficients, 1 meaning that all coefficients from that block are significant)

  1. '%'
  2. 'scaleToBlockSize'
  3. flag: 1->"type specific value" is scaled, 0->"type specific value" is not scaled

The keyword "vector" implies, that each entry of this type in the data-part shall be displayed as a vector. To specifie the color of this type (also RGBa 8bit), the "type-line" is followed by one line, which starts with the keyword "vectorColor" and contains the following entries:

  1. '%'
  2. 'vectorColor'
  3. Red-component of the specified color
  4. Green-component of the specified color
  5. Blue-component of the specified color
  6. Alpha-component of the specified color

Another line follows, that specifies the scaling of the vector components (x,y), which are placed in the seventh and eigth column of each line of this type in the data-part:

  1. '%'
  2. 'scaleFactor'
  3. scaling factor (i.e. 4); to gain pixel accuracy, the vector components must by divided by this factor.

Example for a Header

%	syntax-version	        v1.22
%	%	                width and height of Chroma TUs are scaled to luma resolution				
%	seq-specs		foreman	layer2		352	288	30
%	type	                0	PCM	        map							
%	mapColor	        0	0	        0	0	120					
%	type	                1	IntraDirLuma	range
%	defaultRange	        0	35	        Autumn
%	type	                2	IntraDirChroma	range
%	defaultRange	        0	36	        Autumn
%	type	                3	RefIdxSkipL0	range							
%	range	                0	4	        0	65	75	154	160	255	255	255
%	type	                4	RefIdxSkipL1	range							
%	range	                0	4	        53	128	0	66	160	255	255	255
%	type	                5	RefIdxMergeL0	range							
%	range	                0	4	        75	154	160	255	0	65	255	255
%	type	                6	RefIdxMergeL1	range							
%	range	                0	4	        0	65	160	255	56	132	255	255
%	type	                7	RefIdxInterL0	range							
%	range	                0	4	        160	255	113	199	0	65	255	255
%	type	                8	RefIdxInterL1	range							
%	range	                0	4	        146	239	160	255	0	65	255	255
%	type	                9	MVSkipL0	vector							
%	vectorColor	        0	0	        0	255						
%	scaleFactor	        4									
%	type	                10	MVSkipL1	vector							
%	vectorColor	        255	255	        255	255						
%	scaleFactor	        4									
%	type	                11	MVMergeL0	vector							
%	vectorColor	        0	0	        0	255						
%	scaleFactor	        4									
%	type	                12	MVMergeL1	vector							
%	vectorColor	        255	255	        255	255						
%	scaleFactor	        4									
%	type	                13	MVInterL0	vector							
%	vectorColor	        0	0	        0	255						
%	scaleFactor	        4									
%	type	                14	MVInterL1	vector							
%	vectorColor	        255	255	        255	255						
%	scaleFactor	        4									
%	type	                15	NumSigCoeffY	range							
%	range	                0	1024	        0	255	0	255	0	255	255	255
%	scaleToBlockSize	1									
%	type	                16	NumSigCoeffU	range							
%	range	                0	1024	        0	255	0	255	0	255	255	255
%	scaleToBlockSize	1									
%	type	                17	NumSigCoeffV	range							
%	range	                0	1024	        0	255	0	255	0	255	255	255
%	scaleToBlockSize	1
Clone this wiki locally