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: Analysis, Harmonics, 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, 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.