Light Paths File Format
The Light Paths file format is a binary file format designed to efficiently store light paths generated by appleseed lighting engines (unidirectional path tracer, bidirectional path tracer, SPPM, etc.).
Light Paths files conventionally use the .aspaths file extension (where as stands for appleseed).
This specification is implemented in the form of aspaths2json.py, a command line utility written in Python that converts .aspaths files to JSON.
- All offsets are zero-based (the first byte of the file is at offset 0).
- All offsets and lengths are expressed in bytes.
- All multi-byte fields are using the little-endian (Intel) convention.
A valid Light Paths file contains the following blocks, in this order:
- A file header
- An index
- A name table
- A collection of light paths
| Field Length | Field Type | Description |
|---|---|---|
| 7 | string | File signature. Must be equal to ASPATHS (in capitals) for the file to be considered valid. |
| 2 | uint16 | File format version. Must be equal to 1. |
| 4 | uint32 | Number of paths stored in the file |
| 2 | uint16 | Width (W) in pixels of the index |
| 2 | uint16 | Height (H) in pixels of the index |
The index is a simple data structure that allows to map pixels of a rendered image to light paths that contributed to that pixel. The index is a 2D rectangular array of W * H entries.
An entry in the index is a structure containing two fields:
- The offset in the file of the first path for that pixel.
- The number of paths for that pixel.
Layout of a single index entry:
| Field Length | Field Type | Description |
|---|---|---|
| 8 | uint64 | Offset in the file of the first path for that pixel |
| 2 | uint16 | Number of paths for that pixel |
In the absence of participating media, light path vertices lie on objects. Instead of storing object names for every vertices, object names are listed once in a name table and are then referenced by light path vertices. Names in the tables are numbered, starting from 0 (the first name is assigned number 0, the second name is assigned number 1, etc.) Path vertices then reference names by their number.
| Field Length | Field Type | Description |
|---|---|---|
| 2 | uint16 | Number of names in the name table |
Layout of a single name table entry:
| Field Length | Field Type | Description |
|---|---|---|
| 2 | uint16 | Length (L) in characters of the name |
| L | char | Name |
A light path is made of a light path header and a collection of light path vertices.
| Field Length | Field Type | Description |
|---|---|---|
| 4 | float | X coordinate in Normalized Device Coordinates of the image sample, i.e. the intersection between this path and the camera's image (film) plane. This can also be understood as a floating point expression of the pixel's X coordinates for that path. |
| 4 | float | Y coordinate in Normalized Device Coordinates of the image sample |
| 2 | uint16 | Number of vertices for that path. This number is always >= 2 since there is always at least one vertex on the light emitter and one vertex at the camera. |
Vertices of a light path are stored immediately after the light path's header. They are ordered according to the direction of travel of the light: from a light emitter to the camera.
The first vertex is always on a light emitter and the last vertex is always at the camera.
The radiance at a vertex is expressed in Watt/steradian/m², assuming that the scene is modeled in meters (1 unit of distance = 1 meter) and that lights power are expressed in Watts.
| Field Length | Field Type | Description |
|---|---|---|
| 2 | uint16 | Index in the name table of the name of the object on which this vertex lies. For the first vertex of a path, this is the name of the light emitter. For the last vertex of a path, this is the name of the camera. |
| 4 | float | X coordinate of the world space position of that vertex |
| 4 | float | Y coordinate of the world space position of that vertex |
| 4 | float | Z coordinate of the world space position of that vertex |
| 4 | float | Red component of the radiance carried by the path up to this vertex |
| 4 | float | Green component of the radiance carried by the path up to this vertex |
| 4 | float | Blue component of the radiance carried by the path up to this vertex |