EXR Header Metadata


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: "{
    "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},
        "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},
        "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},
        "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},
    oiio:ColorSpace: "Linear"
    oiio:subimagename: "main"
    oiio:subimages: 12
    openexr:chunkCount: 51