ResearchControls

Development biography · earlier archive

Development profile compiled from project source and retained records in October 2026. Dates and test results describe those records; they do not imply a new build, live acceptance test or public release.

Biography

Most UI toolkits treat a control as a thin wrapper over a single number. Research and professional tools need more: a gesture that carries several linked meanings at once, a value that survives switching views, a record of every edit for replay, and an honest boundary between "a measurement exists" and "a widget happens to show zero." ResearchControls is built around those needs. It is a SwiftUI package — not an application — whose job is to be the trustworthy input and display layer that a research host can wire into its own runtime.

The centrepiece is SemanticPad4D. On screen it looks like a familiar XY pad, but underneath it owns exactly one canonical SemanticPad4DValue with X, Y, Z and W components. The visible pad is always a projection of that 4D value onto one of six planes (.xy, .xz, .xw, .yz, .yw, .zw); switching planes never resets the hidden axes because there is only ever one vector. That discipline — "the visible control is a view of a canonical value" — is the package's core idea, and the project's operating contract treats it as non-negotiable: plane pickers, numeric fields, pose snapping, regions, calibration, replay and semantic export must all keep the same vector as source of truth, rather than degenerating into "an XY pad plus two unrelated sliders."

From that seed the package grew into a full control family. The catalogue in README.md lists discrete selectors (ResearchSelector/EnumSelector), scalar rotaries and faders (ResearchKnob, ResearchFader), a unit-aware ResearchStepper, an endless ResearchJogWheel, a DICOM-style WindowLevelControl (window width/level in Hounsfield units with CT presets), a 3-axis SemanticPad3D, a 6-DoF Pose6DControl, a ColormapEditor, read-only ResearchMeter/ResearchScope, a DistributionSlider (value plus uncertainty band), a four-point ADSR EnvelopeEditor, a RoutingGraphCanvas patchbay, and a ParallelCoordinatesEditor. A separate Medical/ family adds cross-section, crosshair-link, slab/band, volume-ROI, transfer-function, 3D-gizmo, cine-timeline and evidence-graph controls. A document-backed Timeline Studio block editor rounds it out, with tracks, folders, fades, automation, takes/comps, groove grids down to 1/128 and tempo/meter maps.

The design method is consistent and visible in the source: a pure, Sendable/Codable value model and a pure reducer with unit tests come first, and the SwiftUI view second. Every interactive control emits app-neutral semantic routes that resolve into assignments carrying descriptor ID, control ID, value kind, raw and normalized value, weight, tags, confidence, stability and provenance. The package never decides what a route means — a host app maps it into its own state. This is why AGENTS.md forbids ResearchControls from importing SemanticControlCore or any host runtime: the semantic runtime, registries and value-kind validation live in the host or a bridge package, and the controls stay reusable.

Two more themes run throughout. First, honesty about missing data: clamp helpers map NaN to a bound but that "does not establish that a measurement exists"; colormaps treat nonfinite positions as transparent no-data; waterfalls treat NaN/∞/empty rows as missing; meters keep a complete snapshot rather than repeating the last value when a sample is absent. Second, non-clinical framing: the package can support brain-model navigation, ocular tuning and adaptive displays, but it is explicitly "not a clinical inference system," and neuro-adjacent uses are described as research navigation, calibration or model exploration.

A concrete user journey: a developer adds the package by local path, drops a SemanticPad4D into a view bound to a @State value, and gets a plane picker, all-axis numeric fields, pose snapping and an assignment inspector for free. On macOS they can opt into cursor lock for high-resolution relative input (pointer deltas drive the plane; scroll and magnify drive latent Z/W; Escape or app-deactivation releases capture), tune it live with the SemanticPad4DCalibrationPanel, and record a SemanticPad4DTrace of every edit for JSON replay. A sibling "Research Visuals" area supplies the read-only chrome — level meters with VU/PPM ballistics, scrolling spectrograms through any colormap, a vectorscope goniometer, an interactive RBJ-biquad EQ curve, and dial faces that draw a parameter's real transfer function — all driven by one TimelineView(.animation) clock, with optional opt-in Metal fast-paths for the goniometer and waterfall.

The intended audience is builders of research, scientific, medical-imaging and pro-audio tooling who want controls that are precise, testable, accessible, and app-neutral at the semantic boundary — and who need the toolkit to be candid about where package verification ends and physical-device/host acceptance begins.

Main modules / what a visitor can see or try

Authored functionality (in-package):

• SemanticPad4D + sidecars: plane picker, all-axis numeric entry, pose snap, assignment inspector/matrix editor, region editor, calibration panel, Codable replay traces.
• Control family — each source file carries an // Applies to note mapping it to a host surface.
• Research Visuals (Sources/ResearchControls/Visuals/): ResearchWaterLevel, ResearchLevelometer, ResearchWaterfall, ResearchSpectrum, ResearchGoniometer, ResearchEQCurve, ResearchResponseFace, ResearchObservationPanel, halo/pacer/glow rings, band meter, sparkline, gauge ring .
• Timeline Studio block editor + TimelineStudioDemoView() and the ResearchControlsBlockEditorDemo executable.
• Runnable demos (code, not media): ResearchControlsDemoView (package harness), TimelineStudioDemoView, Examples/PackageConsumer (swift run --package-path Examples/PackageConsumer RCConsumer — a local AUParameterTree, no audio engine).

Dependencies: none external; Metal/AVKit used only behind #if canImport(...) and are system frameworks. ResearchControlsAUBridge depends only on the core target.

Technical foundations

• Pure-core-first architecture (Sendable/Codable model + pure reducer + unit tests, then SwiftUI). Structured ControlEditEvent telemetry; app-neutral semantic export triple (route → resolved assignment → host bridge).
• SwiftUI Canvas + single TimelineView(.animation) clock for visuals; CoreGraphics raster for the CPU waterfall; opt-in runtime-compiled Metal shaders (no .metal asset) for goniometer/waterfall fast-paths.
• Validated parameter contracts, engineering unit tokens, EQ sample-rate handling (RBJ biquads below Nyquist), DICOM LINEAR window ramp, finite-value/missing-data policy — documented in PARAMETER_CONTRACT.md, SCIENTIFIC_SEMANTICS.md, NUMERIC_AUDIT.md.
• Important local packages/paths: this package (the project archive); host AssistantApp DICOM/NeuroAtlas; bridge files Sources/Creative/NeuroAtlas/ResearchControlsSelectorBridge.swift and ResearchControlsWorkstationBridge.swift (additive — they do not modify existing views).

Current maturity by evidence

• Source implemented: Full control family + Research Visuals + Timeline Studio present (187 Swift sources under Sources/). Research Visuals is marked "feature-complete" .
• Tests passed: Latest owned pass (2026-10-03, block-editor host composition, matches HEAD 6fcb52d): 459 tests (456 package + 3 AU bridge). Other dated passes in RELEASE_READINESS.md: 453 (meter closure, baseline b47aab3), 442, 438, 434. Debug + release builds passed; DocC built with warnings-as-errors; both generic iOS targets built; Examples/PackageConsumer exercised via keyboard/accessibility actions.
• Built: swift build and swift build -c release passed in the recorded runs (release build ~239 s / ~92 s debug, per the 2026-10-03 receipts).
• Runtime/installed verified: Partial. A signed demo app was rebuilt (/tmp/RC-Completion-Demo.app); native accessibility-tree probes confirmed menus/tools and a basic region move transaction. Not verified: physical Force-Touch/touchscreen/VoiceOver acceptance, continuous drag smoothness, realtime audio/DAW, macOS cursor-capture on real devices, hosted CI, and host-build placement of the bound DICOM/NeuroAtlas panels.
• Released/deployed: No evidence of a public release, tag, or published package registry entry. Treat as an actively developed local/private package. Phase status : P0–P1 complete; P2 package-complete (host hardware QA pending); P3 package bridge complete (host integration pending); P4 package-complete first slice.
• Unknown: license/distribution decision; any public URL.

Roadmap (aspirational, from docs)

• Place the bound DICOM/NeuroAtlas panels into host view bodies and link-verify the two bridge files against a full AssistantApp build .
• Physical-device QA: macOS cursor capture (mouse/trackpad/Magic Trackpad, Escape/Fn/deactivation release, multi-display), Force-Touch/touchscreen/VoiceOver, realtime audio/DAW.
• Wire remaining RoutingGraph homes (DICOM rcApply fan-in, MISO→MESA→MEGA evidence graph); live GPU tuning for the Metal fast-paths; hosted CI on min/current Xcode.
• Package-wide scientific/engineering/audio release gates in PACKAGE_ROADMAP.md.

FAQs

• What is SemanticPad4D? A pad that looks 2D but keeps one canonical 4D value; the visible surface is a projection onto one of six planes, so hidden axes never reset.
• Does it do medical diagnosis? No. It is explicitly not a clinical inference system; neuro/ocular uses are framed as research navigation, calibration and visualization.
• How does it connect to an app? Through app-neutral semantic routes (descriptor/control ID, raw+normalized value, weight, tags, confidence, stability, provenance); the host maps them to its runtime. It never imports the host runtime or SemanticControlCore.
• Platforms/requirements? macOS 26 and iOS 26, Swift tools 6.2, SwiftUI. iOS gets everything except macOS cursor capture.
• Is it released? It builds and passes ~459 tests locally (2026-10-03), but there is no evidence of a public release, license decision, or device-acceptance sign-off.