IES TM-25 · Rust · WebAssembly

tm25ray

Reader, writer and far-field converter for the ray files LED manufacturers publish: the near-field emission of a source, stored as millions of individual rays.

The viewer runs in the browser at tm25.eu, no install: as far as I can tell the only TM-25 viewer that does. Needs WebGPU (Chrome, Edge, or Safari 26). Your own files are read locally and never uploaded.

A rendered far-field solid, coloured green to blue, with the bright rectangular emitting surface of the LED die visible inside it.
An ams OSRAM UV-C emitter: 500 000 rays leaving the die, wrapped in the far-field solid computed from all of them. The bright rectangle in the middle is the emitting surface itself, which is the thing a ray file records and an ordinary photometric file cannot.

What a TM-25 file is

An LDT or IES photometric file describes a luminaire as a point: intensity in every direction, measured far enough away that the size of the source no longer matters. That is all a lighting designer needs for a room.

It is not enough for someone designing the optic itself. Put a lens two millimetres above a die and the point-source assumption collapses, because different parts of the lens see different parts of the emitter. So LED makers publish ray files instead: every ray with a start point in millimetres, a direction, a flux, and optionally a wavelength, polarisation state or colour coordinates. Packages run from 100 000 to 20 million rays.

IES TM-25 is the vendor-neutral format for that data, consumed by Zemax OpticStudio, LightTools, SPEOS and similar tools. ams OSRAM, Lumileds, Nichia and Cree all ship it. The specification itself is paywalled, so the open implementations are how the format is actually documented in public: Julius Muschaweck's C++ TM25RaySetTools, whose field names carry the specification's section numbers and which this crate was checked against line by line, and Larry Boxler's C# IESTM25RayFiles. What was missing was a reader you can depend on as a library, and a way to look at a ray file without installing anything. The existing viewers are a Windows desktop application or a feature of Zemax, TracePro and SPEOS; this is, as far as I can tell, the only one that runs in a browser.

Two vendors, two shapes. ams OSRAM files start the ray block at 36 704, Lumileds files at 36 288: the spectral-table block is padded to a multiple of 32 bytes, and only one of them has a table. An earlier version of this crate mistook that padding for an optional trailer. Lumileds also writes the “value unknown” sentinel with its bytes reversed, which read little-endian is not a NaN but the denormal 2.36 × 10⁻³⁸ — small enough to pass for a real measurement. Both are handled, the layout was checked against the standard’s own table, and the details are written up in the format notes.

What the viewer shows

The rays

Drawn from their real start points, so the die, the lens exit and the package geometry are visible.

Far-field solid

Every ray binned into a C/γ grid with solid-angle normalisation — the same distribution an LDT would carry.

Near-field irradiance

A target plane from 0.1 mm to 500 mm above the source, in W/m², where the point-source model breaks down.

Spectrum and safety

PPFD for horticultural sources, and ICNIRP actinic dose for UV emitters, from the header spectrum.

The viewer exports what it computes as EULUMDAT, IES, ATLA XML with the spectrum attached, or a relative .spd. It can also hand the ray set to a Monte Carlo goniophotometer, which replays the stored rays through a cover or reflector you place millimetres away.

The same emitter drawn as rays only, a dense cloud of fine lines spreading outward and downward from a small rectangular source.
The same file with the solid switched off: 200 000 flux-weighted rays, additively blended.

Performance

Apple M2 Max, release build, warm page cache, 28-byte records. The 20-million ray file is 560 MB.

StageTimeThroughput
Header only0.4 ms—
Stream and decode every ray0.22 s91 M rays/s
Memory-mapped decode0.21 s96 M rays/s
Plus reservoir, 200k rays kept0.33 s61 M rays/s
Plus far field, 10°/5° grid0.95 s21 M rays/s
Far field and reservoir together1.08 s19 M rays/s

Throughput is flat from 100 000 to 20 million rays, so the files most people download finish in milliseconds. Decoding is a bounds-checked reinterpret of f32 columns and runs at memory speed; the far-field stage costs more because every ray needs a trigonometric call and a solid-angle-weighted bin write. Reproduce it with cargo run --release --example tm25_bench -- file.TM25RAY.

Using the crate

[dependencies]
tm25ray = "0.2"

No dependencies beyond thiserror, std-only, and it builds unchanged for wasm32.

Read a file and bin its far field

use tm25ray::{FarField, FluxKind, Tm25File};

let bytes = std::fs::read("rayfile_100k.TM25RAY")?;
let file = Tm25File::parse(&bytes)?;
let h = &file.header;
println!("{} rays, {:?}, {} W", h.n_rays, h.flux_kind(), h.radiant_flux_w);

let rays: Vec<_> = file.rays.iter().collect();
let ff = FarField::from_rays(&rays, 10.0, 5.0, FluxKind::Radiometric);
println!("half intensity at {:?}°", ff.half_intensity_gamma());

Stream a file too large to hold

use std::io::BufReader;
use tm25ray::{Reservoir, Tm25Reader};

let file = std::fs::File::open("rayfile_20M.TM25RAY")?;
let mut reader = Tm25Reader::new(BufReader::with_capacity(1 << 20, file))?;
let mut keep = Reservoir::new(200_000, 1);
loop {
    let chunk = reader.read_chunk(65_536)?;
    if chunk.is_empty() { break; }
    keep.extend(chunk);
}
let rays = keep.finish(); // flux rescaled to the file total

In the browser the same reader is fed Blob.slice chunks, which is how the viewer handles a 560 MB file without loading it. The subsampling keeps a fixed number of rays and rescales their flux, so the total is preserved.

A file to try

Vendor licences permit use but not redistribution, so no manufacturer's file can ship here. Instead there is a generated one, free to copy, ray-traced from an analytic model: a 1 mm square chip emitting Lambertian under a 1.4 mm silicone dome, refracted at the dome surface by Snell's law, with a small fraction escaping past the rim. Each ray starts where it leaves the package, on the dome or in the rim gap, as in a vendor file. It carries a phosphor-white spectrum and a per-ray wavelength, so the spectral colouring in the viewer has something to show.

Open the sample in the viewer Open the 100k version

One click: the viewer fetches the file and loads it. To keep a copy instead, download 25k rays (0.8 MB) or 100k rays (3.2 MB) and drop it on the page. Both describe the same source: 1.05 W radiant, half intensity at 61°.

It is a simulation and its header says so, in the creation-method field and in the description strings. The numbers are plausible rather than a real product's. Regenerate it at any size with cargo run --release --example tm25_sample -- out.TM25RAY 250000.

For checking luminance code there is also a ground truth: a flat 1 × 1 mm Lambertian square, 1 W, 1M equal-flux rays with a flat 360–830 nm spectrum, whose radiance is exactly 318 310 W/(sr·m²) at every point and in every direction. Download it (32 MB), and see the luminance notes for the method and the noise to expect.

For real measured data, ams OSRAM, Lumileds, Nichia and Cree publish ray files on their product pages, usually beside the datasheet and in several ray counts. Those are the files this crate was verified against.