EXR Header Metadata

Format

MoonRay outputs internal Checkpoint and Resume render information as metadata of the EXR header. The metadata information is added to the output image file when at least one of the following settings is true.

checkpoint_rendering = true
resume_rendering = true
resumable_output = true

The metadata information can be retrieved by the command-line

oiiotool -info -v filename.exr

The following is a description of the available metadata information:

Meta data	Description
adaptiveSamplingV1: min max err	The adaptive sampling values for this render result
AovFilterMinAdaptiveSamples: N	The minimum adaptive sample number for AOV filter
progressCheckpointTileSamples: N	The final tile sample totals for this file in checkpoint mode
resumeHistory:	All resume history of this image in JSON format. Each resume render history info is stored as a JSON object inside the "history" JSON array. One resumeHistory consists of four different sections: "sampling", "execEnv", "timingSummary" and "timingDetail". The "sampling" section includes sampling related information The "execEnv" section includes environment related information, such as hostname and timezone The "timingSummary" section includes summary timing information The "timingDetail" records all detailed timing information

sampling section:

Key	Type	Description
samplingType	string	"ADAPTIVE" or "UNIFORM". Indicates the sampling type
minSamples	int	The minimum samples per pixel
maxSamples	int	The maximum samples per pixel
adaptiveTargetError	float	The adaptive sampling target error (which only exists for Adaptive sampling mode)
sampleResult	Detailed sampling information about the internal sampling count. This is useful to compare image quality by a sampling number.
sample result:
Key	Type	Description
PixelSamples	int	The total number of PIXEL samples
lightSamples	int	The total number of LIGHT samples
bsdfSamples	int	The total number of BSDF samples
bssrdfSamples	int	The total number of BSSRDF samples
totalSamples	int	The total of the above samples

execEnv section:

Key	Type	Description
hostname	string	The hostname which generated this file
numberOfThreads	int	The number of threads used by renderer
UTCOffsetHours	float	The UTC offset, in hours, for timezone calculation
DWA_HOST_RU	string	The "DWA_HOST_RU" environment value
DWA_FULL_ID	string	The "DWA_FULL_ID" environment value
Note that DWA_HOST_RU and DWA_FULL_ID info only exists when they are specified as environment variables

timingSummary section:

Key	Type	Description
renderPrepSec	float	The time in seconds spent in the RenderPrep stage
mcrtSec	float	The time in seconds spent in the MCRT computation stage
checkpointTotalSecExcludeLast	float	The total time in seconds spent during the checkpoint data output operation but not including the last checkpoint output cost, nor the background thread writing cost
checkpointTotal	int	The total count of output checkpoint data writtent to the disk
checkpointAverageSec	float	Average time in seconds spent during the checkpoint data output operation, but not including the background thread writing cost
timeSaveSecBySignalCheckpoint	float	The time in seconds that was saved compared with regular (time/quality) checkpoint if this file is created by signal-based checkpoint logic.

timingDetail section:

Key	Type	Description
bgCheckpointWrite	bool(true/false)	true if background checkpoint write logic created this file, false if not
startTileSamplesId	unsigned int	start tileSamples id
procStartTime	time format	Process start time (start time of this render process)
frameStartTime	time format	Frame computation start time (the renderPrep start time for this frame)
MCRT	MCRT info format	The detailed MCRT phase information consists of multiple checkpoint stint information
Note that calculating the (frameStartTime - procStartTime) is useful to determine the spend for process boot time, including initializing dso's and related activities.

time format:

Key	Type	Description
date	string	Human readable time display
sec	unsigned long	Seconds since the Epoch (1970-01-01 00:00:00 -0000 (UTC))
usec	unsigned long	Microseconds since the Epoch (1970-01-01 00:00:00 -0000 (UTC))

MCRT info format:

detailed MCRT phase timing information. This info consists of multiple checkpoint stint information.

Each checkpoint stint info:

Key	Type	Description
stint	int	ID of the checkpoint stint. Start from id = 0
extraSnapshot	bool(true/false)	true if extraSnapshot (i.e. signal-based checkpoint) logic created this data, false if not
MCRTStartTime	time format	Timing of when the MCRT computation started
MCRTEndTime	time format	Timing of when the MCRT computation ended
endTileSamplesId	unsigned int	The end tileSamples ID
Note: Calculating the first (MCRTStartTime - frameStartTime) would equal renderPrep time span. Calculating the second (MCRTStartTime - 1stMCRTEndTime) would equal the first checkpoint output time span. ... Calculating the (Nth MCRTStartTime - (N-1 )th MCRTEndTime) would equal the (N-1 )th checkpoint output time span

Example Metadata Output

In this example, sample.exr was overwritten 3 times by checkpoint output logic. 1st and 2nd checkpoint write was done by regular checkpoint output. 3rd checkpoint write was done by signal-based checkpoint.

> oiiotool -info -v sample.exr
Reading sample.exr
ENVIR::btyLFT.101.exr : 1920 x  816, 4 channel, half openexr
    12 subimages: 1920x816 [h,h,h,h], 1920x816 [h,h,h], 1920x816 [h,h,h], 1920x816 [h,h,h], 1920x816 [h,h,h], 1920x816 [h,h,h], 1920x816 [h,h,h], 1920x816 [h,h,h], 1920x816 [h,h,h], 1920x816 [h,h,h], 1920x816 [h,h,h], 1920x816 [h,h,h]
    channel list: R, G, B, A
    adaptiveSamplingV1: 2, 16, 0.0015
    AovFilterNumConsistentSamples: 2
    compression: "zip"
    DateTime: "2023:07:13 15:03:35"
    max_adaptive_samples: 16
    min_adaptive_samples: 1
    pixel_samples: 8
    progressCheckpointTileSamples: 446
    resumeHistory: "{
"history":[
{
  "sampling":{
    "samplingType":"ADAPTIVE",
    "minSamples":2,
    "maxSamples":16,
    "adaptiveTargetError":15.000000,
    "sampleResult":{
      "PixelSamples":8698792,
      "lightSamples":122329571,
      "bsdfSamples":252977045,
      "bssrdfSamples":48994734,
      "totalSamples":433000142
    }
  },
  "execEnv":{
    "hostname":"pearldiva.gld.dreamworks.net",
    "numberOfThreads":36,
    "UTCOffsetHours":-8.000000
  },
  "timingDetail":{
    "bgCheckpointWrite":true,
    "startTileSamplesId":0,
    "procStartTime":{"date":"2023/Jul/13 Thu 15:1:29:139","sec":1689285689,"usec":139997},
    "frameStartTime":{"date":"2023/Jul/13 Thu 15:1:29:420","sec":1689285689,"usec":420374},
    "MCRT":[
      {
        "stint":0,
        "extraSnapshot":false,
        "MCRTStartTime":{"date":"2023/Jul/13 Thu 15:2:0:608","sec":1689285720,"usec":608143},
        "MCRTEndTime":{"date":"2023/Jul/13 Thu 15:2:21:69","sec":1689285741,"usec":69478},
        "endTileSamplesId":63
      },
      {
        "stint":1,
        "extraSnapshot":false,
        "MCRTStartTime":{"date":"2023/Jul/13 Thu 15:2:21:547","sec":1689285741,"usec":547620},
        "MCRTEndTime":{"date":"2023/Jul/13 Thu 15:3:10:518","sec":1689285790,"usec":518026},
        "endTileSamplesId":319
      },
      {
        "stint":2,
        "extraSnapshot":true,
        "MCRTStartTime":{"date":"2023/Jul/13 Thu 15:3:11:144","sec":1689285791,"usec":144124},
        "MCRTEndTime":{"date":"2023/Jul/13 Thu 15:3:25:310","sec":1689285805,"usec":310274},
        "endTileSamplesId":445
      }
    ]
  },
  "timingSummary":{
    "renderPrepSec":31.187769,
    "mcrtSec":83.597893,
    "checkpointTotalSecExcludeLast":1.104240,
    "checkpointTotal":3,
    "checkpointAverageSec":0.552120,
    "timeSaveSecBySignalCheckpoint":14.166150
  }
}
]
}"
    oiio:ColorSpace: "Linear"
    oiio:subimagename: "main"
    oiio:subimages: 12
    openexr:chunkCount: 51
>