Physics Software Sensors

Markdown sources: English | 简体中文 | 日本語

What is this?

A reusable software sensing layer for physics experiments. It turns camera frames, screen pixels and image-processing observations into traceable FramePacket and SensorEvent records that future physics projects can reuse.

The repository also hosts reusable Companion Processing Tools that operate on Sensor outputs without pretending to create new direct observations.

This is a long-lived capability library, not a new experiment application. Source projects remain unchanged and continue to be the historical source of truth.

Physics Project
      ↓
Reusable Capability
      ↓
Physics Software Sensors
      ↓
Future Physics Projects

Mature capabilities are extracted through adapters, tested against fixed source commits, documented, benchmarked and then reused. Pixel position, OCR text, confidence and bounding boxes are direct software observations—not automatically calibrated physical quantities.

Physical / Software Source
        ↓
Capture Sensors → FramePacket
        ↓
Processor Sensors → SensorEvent / scalar measurements
        ↓
Companion Processing Tools
        ↓
Physics Application

For example: screen.capture → ocr.number → vector.compose-3d → 3D resultant vector. The final step reconstructs existing scalar measurements; it does not sense a new quantity.

Language access

Repository multilingual content integrity: PASS. English, Simplified Chinese and Japanese Markdown are maintained as complete source documents. If a regional GitHub file-view route fails, this repository still provides the following quick orientation from the root README:

Project status

9 Software Sensors · 4 Companion Processing Tools · 13 reusable public capabilities · English / 简体中文 / 日本語

All 9 adapters and 4 Tools are experimental. The public v0.6.0 Release contains 7 Sensor Bundles; the Tool is unreleased. The first E5 downstream reuse is complete, but no Sensor is claimed as fully validated.

Sensor catalog

Sensor Purpose Language Maturity Evidence Example Download
camera.capture Camera frames with timing/backend metadata Python experimental E1 example bundle
screen.capture User-authorized screen/window pixels TypeScript experimental E1 example bundle
ocr.number Numeric OCR from an image ROI TypeScript experimental E3 example bundle
tracker.color-marker HSV/contour color-marker tracking Python experimental E2 example bundle
tracker.spot-centroid Brightness-weighted light-spot centroid Python experimental E5 example bundle
tracker.template ROI-initialized single-object tracking Python experimental E3 example bundle
tracker.yolo Multi-target detection/tracking adapter Python experimental E2 example bundle
image.strip-profile Rotated ROI strip profile with native RGBA channel and saturation metadata TypeScript experimental E2 demo unreleased 0.1.0
vision.ruler-ticks Automatic physical-ruler ticks and scale candidates TypeScript experimental E2 demo unreleased 0.1.0

See the full Sensor Catalog. Evidence describes exercised paths; maturity is a separate release decision.

Companion Processing Tools

Tool Purpose Language Status Example Documentation
vector.compose-3d 3D vector composition and reconstruction from scalar components TypeScript experimental web demo Tool Page
calibration.scale-1d Confirmed two-point and piecewise multi-point 1D calibration TypeScript experimental Web demo Tool Page
signal.profile-features Smoothing, background subtraction, peaks, widths and period TypeScript experimental Web demo Tool Page
optics.fringe-wavelength Slit/diffraction wavelength inversion, regression and uncertainty TypeScript experimental Web demo Tool Page

See the full Tool Catalog. Companion Tools form an extensible processing layer and are not counted as Sensors.

Quick start

Start with Getting Started, then choose either the Python wheel or TypeScript tgz from the v0.6.0 Experimental Release. Nothing is published to PyPI or the npm registry.

python -m pip install './physics_software_sensors-0.5.0-py3-none-any.whl[classical-trackers]'
npm install ./physics-software-sensors-core-0.3.0.tgz

FringeLab adds two Sensors, three processing Tools and reusable calculator/ROI/ruler UI. Both extraction batches are complete in a separate 0.1.0 package; the immutable v0.6.0 download still contains the original seven bundles. FringeLab toolkit · runnable demo

Download

The Release contains one Python wheel, one TypeScript tgz, seven Sensor Bundles, release-manifest.json and SHA256SUMS. A Sensor Bundle is a readable documentation/example package; it does not duplicate the shared core. Read Downloading Sensors and Installation.

Capability Showcase

New: FringeLab toolkit — calculator, ROI, manual/automatic rulers, calibration, profiles, OCR, camera and optics. Component guide.

Physics Software Sensors: 7 Software Sensors and 1 Companion Processing Tool

Representative standalone, synthetic and replay demonstrations. Evidence level varies by capability; the YOLO tile is recorded detector replay, not real YOLO inference. The image is an enhancement, while the text links below remain the canonical navigation when image delivery is unavailable.

Camera Capture · Screen Capture · Number OCR · Color Marker · Spot Centroid · Template Tracker · YOLO Tracker · 3D Vector Composition

Baseline image coverage: 7/7 Software Sensors + 1/1 Companion Processing Tool = 8/8 reusable public capabilities. Open the trilingual Capability Showcase for all eight detailed demo images and evidence boundaries.

FringeLab image and optics toolkit

Reusable components extracted from the light-distribution experiment, available together or independently in @physics-software-sensors/fringelab 0.1.0. Both batches are collected.

Batch 1: calculator, ROI, virtual ruler, manual calibration and profile analysis.

Batch 2: automatic ruler, ruler-number OCR, browser camera and optical inversion.

Component Reusable behavior Entry point
Floating calculator Movable panel, independent instances, arithmetic and scientific notation UI
ROI and virtual ruler Rotate/move/resize a native-pixel ROI; ruler endpoints, ticks and snapping UI
Manual calibration Confirm a known interval or editable multi-point readings calibration.scale-1d
Profile and signal analysis Relative image response, channel quality, smoothing, peaks and widths image.strip-profile
Automatic ruler Locate physical ticks; retain manual/region modes, contrast and snapping options vision.ruler-ticks
Ruler OCR and camera Draft centimetre readings; capture/freeze camera frames and inspect settings browser
Optical inversion Interference/diffraction wavelength, regression, uncertainty and simulation optics.fringe-wavelength

FringeLab image and optics toolkit — synthetic example

Chinese guide · API and install · runnable example · profile features · FringeLab guide

Automatic/OCR readings remain drafts until confirmed; manual and multi-point modes are fully retained. The screenshot is a working synthetic 650 nm example. DN is relative response, and real-device precision is not established.

Current catalog: 9/9 Sensors + 4/4 processing Tools = 13/13 capabilities. Calculator and overlay UI are additional reusable components, outside Sensor counts.

Core principles

  1. Do not break or silently rewrite source projects.
  2. Pin provenance to repository, full commit SHA, path and symbol.
  3. Preserve raw observations and distinguish downstream derivations.
  4. Make time, coordinates, units, confidence and uncertainty explicit.
  5. State evidence, maturity, licensing and model boundaries conservatively.

Long-term workflow

New Physics Project
      ↓
Reusable mature capability
      ↓
Sensor Intake
      ↓
Physics Software Sensors
      ↓
Experimental / Validation / Release
      ↓
Future Physics Projects

Future work enters through Sensor Intake, the Add New Sensor recipe, or an existing-Sensor maintenance track. The first completed extraction-to-reuse cycle is documented in First Complete Reuse Loop.

Documentation

Development and validation

python3 tools/validate_repo.py
pytest
npm --prefix packages/typescript test

See CONTRIBUTING.md. A new Sensor or major capability follows the formal intake workflow; ordinary bug fixes do not.

Current non-goals

License

Repository-owned code and documentation are MIT licensed. Historical source code, models, data and dependencies retain their own licensing boundaries; see THIRD_PARTY_NOTICES.md.

Latest development handoff: .agent-handoff/latest.md · .agent-handoff/latest.json