Light Paths File Format

Introduction

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.

File Layout

Conventions

• 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.

High-Level Structure

A valid Light Paths file contains the following blocks, in this order:

1. A file header
2. An index
3. A name table
4. A collection of light paths

File Header

Field Offset	Field Length	Field Type	Description
0	7	string	File signature. Must be equal to ASPATHS (in capitals) for the file to be considered valid.
7	2	uint16	File format version. Must be equal to 1.
9	4	uint32	Number of paths stored in the file
13	2	uint16	Width (W) in pixels of the index
15	2	uint16	Height (H) in pixels of the index

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:

1. The offset in the file of the first path for that pixel.
2. The number of paths for that pixel.

Layout of a single index entry:

Field Offset	Field Length	Field Type	Description
N	8	uint64	Offset in the file of the first path for that pixel
N + 8	2	uint16	Number of paths for that pixel

Name Table

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 Offset	Field Length	Field Type	Description
N	2	uint16	Number of names in the name table

Layout of a single name table entry:

Field Offset	Field Length	Field Type	Description
N	2	uint16	Length (L) in characters of the name
N + 2	L	char	Name

Light Paths

A light path is made of a light path header and a collection of light path vertices.

Light Path Header

Field Offset	Field Length	Field Type	Description
N	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.
N + 4	4	float	Y coordinate in Normalized Device Coordinates of the image sample
N + 8	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.

Light Path Vertices

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 Offset	Field Length	Field Type	Description
N	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.
N + 2	4	float	X coordinate of the world space position of that vertex
N + 6	4	float	Y coordinate of the world space position of that vertex
N + 10	4	float	Z coordinate of the world space position of that vertex
N + 14	4	float	Red component of the radiance carried by the path up to this vertex
N + 18	4	float	Green component of the radiance carried by the path up to this vertex
N + 22	4	float	Blue component of the radiance carried by the path up to this vertex