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:
- 简体中文快速说明:这是面向物理实验的可复用软件传感器基础层,当前有 9 个软件传感器和 4 个配套处理工具,共 13 项公开能力。它记录图像/屏幕/OCR/追踪的直接观测,不把像素或 OCR 数值自动说成物理量。公开
v0.6.0包含 7 个 Sensor Bundle;vector.compose-3d仍是未发布的 experimental 工具。三语文档网站现已由 GitHub Pages 从main /docs提供。 - 日本語クイックガイド:これは物理実験向けの再利用可能なソフトウェアセンサー基盤です。9 個の Software Sensor と 4 個の Companion Processing Tool、合計 13 項目の公開 capability があります。画像・画面・OCR・追跡の直接観測と、下流の物理量を区別します。公開
v0.6.0には 7 個の Sensor Bundle が含まれ、vector.compose-3dは未リリースの experimental Tool です。3 言語の静的 reader は GitHub Pages のmain /docsから公開されています。
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.
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 |
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
- Do not break or silently rewrite source projects.
- Pin provenance to repository, full commit SHA, path and symbol.
- Preserve raw observations and distinguish downstream derivations.
- Make time, coordinates, units, confidence and uncertainty explicit.
- 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
- Documentation Website
- Sensor Catalog
- Companion Tool Catalog
- Capability Showcase
- Getting Started
- Evidence and Maturity
- Sensor Intake
- First Complete Reuse Loop and Maintenance Guide
- Current Project Status
- Terminology and i18n Style Guide
- Demo Asset Inventory
- Architecture, data format, benchmarking
- Release v0.6.0
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
- No stable, production-ready, measurement-grade or metrology claim.
- No automatic YOLO model download or bundled model weight.
- No forced migration of historical experiment projects.
- No PyPI/npm registry publication; the first merged E5 integration is an offline replay path and does not replace the downstream live-camera implementation.
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

