tm25ray
Rust reader, writer and far-field converter for IES TM-25 ray files
(.TM25RAY) — the vendor-neutral format for the near-field emission of LEDs
and other light sources.
A TM-25 file describes a source as individual rays: start point (mm), unit
direction, flux, optionally wavelength, polarisation and colour data. It is
what LED makers publish for optics design (ams OSRAM ships packages with
100k to 20M rays) and what Zemax OpticStudio, LightTools, SPEOS and the like
consume. This crate reads and writes those files without pulling in anything
else: no dependencies beyond thiserror, std-only, runs unchanged on
wasm32, and streams multi-GB files without loading them.
[]
= "0.1"
What you get
- Zero-copy reader —
Tm25File::parse(&bytes)parses the header and exposes the ray block as a view, no per-ray allocation. - Streaming reader —
Tm25Reader::new(any_read)yields rays in chunks; the 20M-ray / 560 MB vendor file streams at ~19 M rays/s on a laptop. In the browser, feed itBlob.slicechunks. - All record layouts — the column set follows the file's known-data flags: radiant / luminous flux, per-ray wavelength, Stokes and polarisation ellipse, tristimulus, spectrum index, user-defined items. Not just the 28-byte case.
- Writer —
write_tm25(...)produces files that round-trip byte-for-byte on the header; use it to export subsets or synthetic sources. - Flux-preserving subsampling —
subsample(Floyd) and a streamingReservoir; the kept rays are rescaled so their flux still sums to the file total. Deterministic per seed, built-in PRNG. - Far field —
FarField::from_rays(...)bins directions into a C/γ grid with solid-angle normalisation (W/sr or cd), gives the azimuthal profile, half-intensity angle, forward fraction, bilinear sampling and a Monte-Carlo-aware smoother. - Coordinate helpers —
direction_to_c_gamma(EULUMDAT/IES angles) andto_bevy/from_bevyfor y-up engines. - Validation — the consistency rules of the reference implementation (flag combinations, positive wavelengths, non-negative weights), strict by default, lenient on request. No panics on untrusted input.
Quick start
use ;
let bytes = read?;
let file = parse?;
let h = &file.header;
println!;
// Every ray, decoded on the fly.
let peak_dir = file.rays.iter.map.fold;
// Far field: 10° C planes, 5° γ rings.
let rays: = file.rays.iter.collect;
let ff = from_rays;
println!;
# Ok::
Streaming a large file with a reservoir of 200k rays:
use BufReader;
use ;
let file = open?;
let mut reader = new?;
let mut keep = new;
loop
let rays = keep.finish; // flux rescaled to the file total
# Ok::
The format
TM-25-13 (IES TM-25-13, revised as ANSI/IES TM-25-20) is a little-endian
binary file: a 36 288-byte fixed header (magic TM25, version, creation
method, luminous and radiant flux, u64 ray count, date, spectral identifier,
wavelength range, table and item counts, known-data flags, nine UTF-32
description strings), then spectral tables, column names and additional
text, then the ray records as f32 columns.
The layout was reverse-engineered from real vendor files and cross-checked
field by field against the field names of the C++ reference implementation
(which carry the specification's section numbers). The standard text is
paywalled; the few details only it can settle are marked VERIFY in the code
and listed in docs/format.md.
Examples
Tests
cargo test runs synthetic round-trips (written with the crate's own writer)
and, when a real vendor file is available, a regression test against it:
set TM25RAY_FIXTURE=/path/to/rayfile_100k.TM25RAY. Vendor files are not
redistributed; their licences allow use, not redistribution.
Related
- eulumdat-rs — EULUMDAT/IES photometry,
ATLA, spectral tools. Its
eulumdat-tm25crate converts aFarFieldinto an EULUMDAT document and attaches the header spectrum, and its Bevy viewer renders ray files in 3D. - TM25RaySetTools — the C++ reference implementation this crate was verified against.
Licence
AGPL-3.0-or-later, like the rest of the eulumdat-rs family. If that does not fit your product, get in touch.