Python SDK¶

The Python SDK is designed for notebook users, labs, and module developers.

Capture From Serial¶

from luxspec import SerialLuxNode, analyze_frame

with SerialLuxNode("/dev/tty.usbmodem1101") as node:
    dark = node.capture("dark")
    white = node.capture("white")
    sample = node.capture("raw")

analysis = analyze_frame(sample, dark=dark, reference=white, mode="reflectance", module="plants")
print(analysis.metrics)
print(analysis.processed.quality.ok)

Prototype Measurement Bundle¶

Use this when you want the SDK to capture the complete dark/reference/sample triplet, run readiness checks, process the spectrum, dispatch module metrics, and save one JSON bundle.

from luxspec import capture_prototype_measurement, connect_serial

measurement = capture_prototype_measurement(
    connect_serial(),
    mode="reflectance",
    module="minerals",
)
measurement.write_json("runs/mineral-first-light.json")

Real-Time Streaming¶

The V0 firmware emits one JSON line per scan, so the same serial protocol can stream directly into Python, a notebook, or a local web page.

from luxspec import LuxStream, connect_serial

node = connect_serial()  # auto-selects a likely USB Luxnode/ESP32 port
stream = LuxStream(node, log_path="runs/first-light.jsonl")

try:
    for frame in stream.frames(max_frames=100):
        print(frame.device_id, frame.measurement_kind, frame.counts.mean())
finally:
    stream.stop()

Jupyter Notebook Monitor¶

from luxspec import connect_serial, notebook_monitor

node = connect_serial()
monitor = notebook_monitor(node, log_path="runs/notebook-live.jsonl")
monitor.run(duration_s=60)

The notebook monitor renders an inline SVG spectrum and appends every frame to JSONL. It has no hard plotting dependency; install luxspec[notebook] for the IPython display helper.

Web Embed / SSE¶

from luxspec import connect_serial, run_stream_server

run_stream_server(
    connect_serial(),
    host="127.0.0.1",
    port=8765,
    log_path="runs/web-live.jsonl",
)

Open http://127.0.0.1:8765 for the live viewer, or embed EventSource("http://127.0.0.1:8765/events") in another web dashboard.

Parse a Saved Frame¶

from luxspec import LuxFrame

frame = LuxFrame.from_json(open("scan.json").read())
spectrum = frame.to_spectrum()

Analyze Minerals¶

from luxspec.processing import module_metrics

result = module_metrics(reflectance_spectrum, "minerals")
for match in result.matches:
    print(match.name, match.score)

CLI¶

luxspec inspect-frame scan.json
luxspec match-mineral reflectance-frame.json
luxspec ports
luxspec stream --port /dev/tty.usbmodem1101 --stream-interval-ms 250 --log runs/live.jsonl --frames 100
luxspec stream --port /dev/tty.usbmodem1101 --stream-interval-ms 250 --http-port 8765 --log runs/live.jsonl
luxspec measure --port /dev/tty.usbmodem1101 --mode reflectance --module minerals --out runs/mineral-first-light.json