Latent Space Visualizer
+Mark makeup steps and measure face-descriptor drift over short, comparable time windows using a camera or local video.
+ +diff --git a/.gitignore b/.gitignore index 8d3437b..200996b 100644 --- a/.gitignore +++ b/.gitignore @@ -23,8 +23,15 @@ EXTRACTED-text-*.md # Generated technical reference /docs/jsdoc/ -# Fake-webcam fixtures and measurements built by scripts-dev/build-face-fixtures.cjs -/tests/fixtures/synthetic-faces/y4m/ +# Local research videos. The small synthetic MP4 remains committed for CI. +/tests/fixtures/*.mp4 +/tests/fixtures/*.webm +/tests/fixtures/*.mkv +/tests/fixtures/*.mov +/tests/fixtures/*.m4v +!/tests/fixtures/my-moving-face.mp4 + +# Local measurements produced while calibrating model thresholds. /tests/fixtures/synthetic-faces/lab-measurements.json # scripts-dev/lab-capture.cjs render writes candidate pictures here. They are diff --git a/JSDOC_index.md b/JSDOC_index.md index 21d82b0..0bebdf5 100644 --- a/JSDOC_index.md +++ b/JSDOC_index.md @@ -1,7 +1,7 @@ # Ghostmaxxing technical reference -> Version 0.9.11 -> Last updated: September 2026 +> Version 0.9.11 +> Last updated: October 2026 > Functional documentation: [use the tools and understand the results](/docs/) Ghostmaxxing is a static browser lab for testing how selected face-analysis models respond to visible interventions. This site is the generated developer reference. It documents runtime modules, functions, parameters, events, and the Ghostyle extension contract. @@ -12,7 +12,7 @@ If you want to operate an interface, begin with the functional guides. If you ar | Question | Documentation | |---|---| -| How do I use the Lab, Video Loader, Transfer, or Face Brush? | [Functional guides](/docs/) | +| How do I use the Lab, Video Loader, Latent Space Visualizer, or Face Brush? | [Functional guides](/docs/) | | What does a match state, threshold, descriptor, or landmark mean? | [Understand the results](/docs/understand/) and [technical glossary](/docs/glossary/) | | How do I create a Ghostyle? | [Ghostyle Authoring Guide](tutorial-ghostyle-authoring.html), then [`ghostyles/00-template.js`](module-ghostyles_00-template.html) | | Which module, function, parameter, or event do I need? | Generated API reference in this site's sidebar | @@ -34,7 +34,17 @@ Use it when exact media time matters more than a live webcam. Use it to explore appearance transfer. A visually successful transfer is not evidence that the target image evades recognition. -`realtime.html` is not part of the initial released documentation set. +### Latent Space Visualizer + +`realtime.html` loads `lab-js/realtime/realtime.js`. It captures a temporal 2D +face-api baseline, filters frames whose 2D pose, framing, or ambient light is not +comparable, and lets the operator mark and aggregate successive makeup steps. +The input may be a live camera or a local video. The timeline, equalizer, and +radial fingerprint are different views of the same descriptor-distance session. + +Begin with the [functional guide](/docs/guides/realtime.html), then use the +[combined operating guide and methodology](/docs/jsdoc/tutorials/realtime) before +interpreting the threshold, noise floor, or per-coordinate plots. ## Runtime architecture @@ -53,6 +63,13 @@ lab.html loader.html └─ lab-js/loader.js +realtime.html + └─ lab-js/realtime/realtime.js + ├─ realtime-capture.js (quality, temporal collectors, spike/frame buffer) + ├─ realtime-graph.js + realtime-radial.js + ├─ realtime-settings.js + └─ realtime-gallery.js + ``` ### Core state and lifecycle diff --git a/README.md b/README.md index 4eec4f3..4d1fac1 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Ghostmaxxing -[](coverage/) +[](coverage/) [](https://github.com/vecna/ghostmaxxing/actions/workflows/ci.yml) @@ -76,6 +76,7 @@ npm run check # validator + unit tests (run before proposing change npm run test:unit # Vitest unit tests npm run test:unit -- --coverage npm run test:e2e # Playwright browser tests +npm run test:e2e:realtime # Focused realtime camera/video workflow npm run docs # generate the JSDoc site into docs/jsdoc/ npm run validate:ghostyles # validate every ghostyle in ghostyles/ npm run validate:ghostyle -- ghostyles/your-slug.js # validate one diff --git a/about.html b/about.html index f341307..4e485fa 100644 --- a/about.html +++ b/about.html @@ -472,6 +472,7 @@
lab-js/ sourceGhostmaxxing.d.tswindow.gstmxx in main.jslab-js/realtime/ sourcescripts-dev/lab.htmllab-js/main.jsloader.htmllab-js/loader.jsrealtime.htmllab-js/realtime/realtime.jsmediapipe-loop.js, engine-3d.jsauto-find-loop.js, bbox-overlay.js, analyze-panel.jsghostyles-manager.js, plugins3d-loader.js, ghostyle3d-uv-renderer.jsrealtime.js, realtime-capture.js, realtime-graph.js, realtime-radial.jsMark makeup steps and measure face-descriptor drift over short, comparable time windows using a camera or local video.
+ +packages.jsonnpm run validate:ghostylesnpm run checknpm testnpm run test:e2e:realtimenpm run codemapnpm run i18n:extractCapture a clean baseline, mark each application interval, and aggregate the descriptor change after every finished step.
+The visualizer uses only the 2D face-api/dlib path. It excludes sufficiently different pose, framing, and ambient-light frames; it does not mathematically correct them or predict another recognition system.
+ +The camera is the default. Open Source to select a local video; the file remains on this device and can be paused, sought, and replayed. Changing source invalidates the current baseline.
+Source → Brightness changes only how bright the video looks on screen. The model reads the original video pixels, so this control cannot improve lighting or change a measurement.
Use a neutral frontal pose and stable light, then press Set baseline. Hold still and follow the centre target while five accepted samples are distributed across at least two seconds.
Press Start makeup step before applying one change. The timeline marks the event and shades the application interval.
Finish the change, then return to the baseline pose, framing, and room light. Leaving the frame during application produces a marked no-face interval without an invented distance line.
Press Measure this step and hold still. Eight comparable frames over at least three seconds become one temporal snapshot.
Record the distance, baseline noise floor, and step temporal spread together. Use Start next step for the next cumulative change.
Baseline capture checks confidence, scale, framing, 2D roll/yaw, and face-crop exposure. After makeup starts, confidence and face-crop exposure may legitimately change, so they no longer reject a frame. Scale, framing, roll, and yaw still apply, followed by a comparison with the baseline's averaged 2D conditions and ambient luminance outside the face box.
+The gate reduces obvious confounds; it cannot prove that makeup caused the remaining distance. It does not estimate pitch and cannot separate every intervention from every shadow.
| View | What it shows | Do not infer |
|---|---|---|
| Distance timeline | Smoothed live distance, gaps, phase backgrounds, event lines, measured noise floor, and the cited 0.60 dlib reference. | That the space between the two reference lines has a calibrated meaning. |
| Equalizer | Absolute change for each of 128 descriptor coordinates. | That one row corresponds to a facial region. |
| Radial distribution | All 128 deltas sorted into 16 ranked RMS bands, with the live reading as an outline and the latest measured step as a filled shape. | That a spoke or direction identifies a makeup line, cheek, or eyebrow. |
| Step capture | The sharpest accepted frame from the measurement window, watermarked with local result metadata. | That one model-local result transfers to a deployed system. |
Local-video event labels include media time. Pause or seek to inspect the recording, then mark application and measurement moments. Starting either interval resumes a paused video so the temporal collector does not repeatedly inspect one frozen frame.
+