Physics Software Sensors

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:

简体中文快速说明：这是面向物理实验的可复用软件传感器基础层，当前有 7 个软件传感器和 1 个配套处理工具，共 8 项公开能力。它记录图像/屏幕/OCR/追踪的直接观测，不把像素或 OCR 数值自动说成物理量。公开 v0.6.0 包含 7 个 Sensor Bundle；vector.compose-3d 仍是未发布的 experimental 工具。完整三语静态阅读页已准备在 docs/，待 GitHub Pages 从 main /docs 启用。
日本語クイックガイド：これは物理実験向けの再利用可能なソフトウェアセンサー基盤です。7 個の Software Sensor と 1 個の Companion Processing Tool、合計 8 項目の公開 capability があります。画像・画面・OCR・追跡の直接観測と、下流の物理量を区別します。公開 v0.6.0 には 7 個の Sensor Bundle が含まれ、vector.compose-3d は未リリースの experimental Tool です。3 言語の静的 reader は docs/ に準備済みで、GitHub Pages の main /docs 設定後に公開されます。

Project status

7 Software Sensors · 1 Companion Processing Tool · 8 reusable public capabilities · English / 简体中文 / 日本語

All 7 adapters and the Tool 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

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

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

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

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

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.

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

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