This component provides an interactive overlay for sonar spectrogram images, enabling users to place harmonic cursors, adjust scaling via a rate input, and switch between multiple analysis modes.
- Modes: Pan (default), Analysis, Harmonics, Sidebands, Doppler
- Harmonic line overlays with frequency labels
- Retro-style LED readouts for measurement
- Drag-to-place cursor system with unlimited cursors
- Embedded via HTML config tables
- Fully self-contained JavaScript (no build step)
- Developer diagnostics mode available via standalone page
- Getting Started — Prerequisites, setup, and development workflow
- Technical Architecture — System architecture, mode system, rendering pipeline, state management
- HTML Integration Guide — Embedding GramFrame in HTML pages
- Adding Graphical Features — Code area guide for new visual features
- Data and State Guide — State management patterns and data flow
- Rendering Troubleshooting — Debugging rendering and coordinate issues
- Architecture Decision Records — Design decisions and rationale
Annotations (analysis markers, harmonic sets, sideband sets, and Doppler curves) are saved to browser storage automatically. The storage backend depends on whether the page is detected as a trainer or student context:
| Context | Storage | Lifetime |
|---|---|---|
| Trainer | localStorage |
Permanent — survives browser restarts |
| Student | sessionStorage |
Cleared when the browser tab/session closes |
A page is treated as a trainer page if either of the following is true:
- The page contains an element with
id="gf-persistent"(anywhere in the DOM), or - The page contains an anchor (
<a>) element whose exact trimmed text isANALYSIS.
If neither is present, the page is treated as a student page.
To opt a page into permanent (trainer) persistence, add a marker element, e.g.:
<span id="gf-persistent" hidden></span>The detection is re-evaluated on every save/load, and the storage key is
namespaced per page path (gramframe::<pathname>) — only the storage backend
(local vs. session) differs between contexts.
Trainees or students using sonar training manuals in HTML format.
Include the JavaScript file via <script>, and place a config table with the appropriate class on your HTML page. The component will auto-initialize after page load.
To identify which version of GramFrame an instance is running — useful when reporting or debugging an issue:
- In the UI: hover over the Pan button. A tooltip shows
GramFrame vX.Y.Z. (The tooltip is available even before zooming in, while the button is disabled.) - Programmatically: read
state.versionvia the public API:GramFrame.addStateListener(state => console.log(state.version))
Released builds show the real version (e.g. v0.1.12); local development builds
show vDEV until yarn generate-version runs.