openUC2 OptiKit Modules — v0.2

Reference-based module database for the openUC2 OptiKit configurator, Optiland simulation, and Inventor CAD pipeline.

Design principle: this repo holds pointers, not files. Each module is a single module.yaml that references the real assets in their canonical home repositories.

What's in v0.2

• Schema v0.2 with renderings (top/front/side), 3D model references, Odoo ERP links, full transform (dx/dy/dz/rx/ry/rz), Markdown documentation, and private: true flag for repos that need a GitHub token
• Three example modules that all validate end-to-end:
  • lens-pos-50mm — Thorlabs LA1131-A plano-convex
  • mirror-45deg — static fold mirror with 90° port transform
  • stage-z-motorized — exercises every reference layer (CAD + electronics + firmware + ImSwitch) plus a real ESP32StageManager config snippet
• Web editor (editor/) — Vite + React frontend with a Node/Express backend that lets you create/edit/validate/export module.yaml files, generate UUIDs, check reference availability (with optional GitHub token for private repos), export to YAML, copy modules.json snippets, or download a complete bundle ZIP with all referenced assets
• Python tooling — validator (with GITHUB_TOKEN env var support), index builder, and Optiland round-trip test

Quick start

Validate everything

pip install jsonschema pyyaml
python scripts/validate_modules.py            # online — checks every URL
python scripts/validate_modules.py --offline  # schema only
GITHUB_TOKEN=ghp_xxx python scripts/validate_modules.py  # also checks private refs

Build the configurator index

python scripts/build_index.py                 # writes index/modules.json

Run the web editor

# Terminal 1
cd editor/server
npm install
node server.js                 # http://localhost:5174

# Terminal 2
cd editor/client
npm install
npm run dev                    # http://localhost:5173

Open http://localhost:5173. The Vite dev server proxies /api/* to the backend.

End-to-end Optiland round-trip test

# Clone LLM_Optics next to this repo, then:
python scripts/test_optiland_load.py --all --local-root LLM_Optics=../LLM_Optics

Repository layout

openuc2-optikit-modules/
├── README.md                    this file
├── schemas/
│   └── module.schema.json       JSON Schema 2020-12, v0.2
├── modules/
│   ├── lenses/lens-pos-50mm/module.yaml
│   ├── mirrors/mirror-45deg/module.yaml
│   └── stages/stage-z-motorized/module.yaml
├── scripts/
│   ├── validate_modules.py      schema + URL checks (supports GITHUB_TOKEN)
│   ├── build_index.py           builds index/modules.json
│   └── test_optiland_load.py    end-to-end Optiland round-trip
├── editor/
│   ├── README.md
│   ├── server/                  Express backend (Node 20+)
│   │   ├── package.json
│   │   └── server.js
│   └── client/                  Vite + React frontend
│       ├── package.json
│       ├── vite.config.js
│       ├── index.html
│       └── src/
│           ├── main.jsx
│           ├── App.jsx
│           ├── components/      ModuleEditor, ReferenceField, TransformField,
│           │                    PortsField, MarkdownField, PreviewPane
│           └── lib/             api.js, defaults.js
├── index/
│   └── modules.json             built artifact for the configurator
└── .github/workflows/
    └── modules.yml              validate on PR, rebuild index on merge

The minimal module.yaml

schema_version: "0.2"
id: lens-pos-50mm
uuid: 01HPQ7K8XJ2N3R4S5T6V7W8Y9Z
name: "Positive Lens, f=50 mm"
category: lens
version: 0.2.0

display:
  group: lenses
  color: "#7CC142"
  grid_size: [1, 1]
  renderings:
    top: "https://.../top.png"
    front: "https://.../front.png"
    side: "https://.../side.png"
  model_3d:
    format: glb
    ref:
      repo: "https://github.com/openUC2/openUC2-CAD-new"
      path: "workspace/exports/lens-pos-50mm.glb"
      private: true

transform:
  dx_mm: 0
  dy_mm: 0
  dz_mm: 0
  rx_deg: 0
  ry_deg: 90       # optical Z (Optiland) → cube +X
  rz_deg: 0

references:
  optics:
    repo: "https://github.com/haikew/LLM_Optics"
    path: "optilib/catalog_corebox/AC254-050-A-ML-Zemax-ZMX.json"
    commit: null
  cad:
    repo: "https://github.com/openUC2/openUC2-CAD-new"
    path: "workspace/ASS/ASS - 2021 - CUBLEND40F50 - V04.iam"
    private: true

ports:
  - { id: in,  face: "+X", type: optical, beam_height_mm: 25 }
  - { id: out, face: "-X", type: optical, beam_height_mm: 25 }

Connected repositories

Layer	Repository	Notes
Optical models	haikew/LLM_Optics	optilib/catalog_corebox/*.json
CAD	openUC2/openUC2-CAD-new	Private — needs GitHub token
Electronics	openUC2/FRAME-electronics-hardware	KiCad
Firmware	youseetoo/uc2-esp32	PlatformIO
ImSwitch	openUC2/ImSwitch	Python
CAD bridge	openUC2/PyInventor	iAssembly.load_from_optikit_layout()

License

MIT for code, CC-BY-SA-4.0 for docs, CERN-OHL-S-2.0 for hardware references.