Optics Solid Trace
optics_solid_traceTrace non-sequential rays through solid STL optical parts using refractive index. Simulates light pipes, prisms, and lenses; returns bend angles and exit paths for leakage mapping.
Instructions
NON-SEQUENTIAL ray trace through a real solid (STL mesh) with a refractive
index — the lane for molded optical parts (light-pipes, prisms, lenses). Backed
by KrakenOS, which is GPL-3.0 and is run ONLY in a subprocess (the parent never
imports it — same arm's-length isolation as the GPL Elmer/OpenFOAM binaries).
Requires the optics_gpl extra; degrades to {ok:false, reason, install} otherwise.
Geometry: pass a model handle (exported to STL here) OR a ready stl_path.
Material: glass (KrakenOS catalog name, e.g. 'BK7') or n_refractive (constant
index). rays: [{origin:[x,y,z], dir:[l,m,n]}]; each ray's turn_deg is its
input->exit bend (~90 for a TIR corner prism, ~0 for a straight pass). solid:
{diameter, thickness, axis_move} placement. wavelength_um default 0.55.
want_paths (default False): also return each valid ray's polyline as
paths — the per-surface hit points [[x,y,z], ...] in the traced frame.
The LAST point of each path is the ray's EXIT LOCATION on the solid, so the
spatial exit/leakage map a diffuser needs can be reconstructed from it.
Returns the degradation dict, or {ok, backend:'KrakenOS (subprocess-isolated, GPL-3.0)', n_launched, n_valid, valid_fraction, mean_turn_deg, max_turn_deg, rays:[{valid, exit_dir, turn_deg}], stl_path, paths?:[[[x,y,z],...],...]}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rays | Yes | ||
| glass | No | ||
| model | No | ||
| solid | No | ||
| stl_path | No | ||
| want_paths | No | ||
| n_refractive | No | ||
| wavelength_um | No |