nimbus-geojs

name

nimbus-geojs

description

Use when working with GeoJS in AnnotationViewer.vue or ImageViewer.vue — adding/removing/reusing annotation features, the draw path, coordinate handling, drawing-tool interaction events, or writing/debugging AnnotationViewer.test.ts. Symptoms this skill explains: annotations invisible though layer.annotations() has them, features drifting off-image or mirrored after re-add, dots in bands above/below the image, live drag positions not updating, annotations vanishing after z-scrubbing.

GeoJS in NimbusImage — traps and testing

GeoJS's annotation layer has several asymmetric, mutating APIs. Each trap below caused a real shipped bug or a multi-hour debug in this repo. Read the row for your symptom first.

Symptom → cause quick reference

Symptom	Cause	Fix
Features in layer.annotations() (count correct) but nothing paints	Adds with update=false don't bump modified(); layer.draw() alone doesn't force _update	Call layer.modified() when the add pass grew the feature count, then draw()
Re-added feature drifts off-image; dots in bands above/below image, worse each zoom in→out	addAnnotation runs ingcs→gcs conversion on EVERY add, mutating coords in place — a re-add double-converts	Re-add already-added features with gcs = null; fresh features with gcs = undefined
Annotation renders mirrored above the image / invisible after coordinate update	annotation._coordinates(v) sets raw gcs (y-up) with NO conversion, but coordinates() and evt.geo return ingcs (image px, y-down)	Never mutate an added annotation's coords — remove and recreate via factory + addAnnotation so conversion happens exactly once
No position updates during a drag	GeoJS suppresses mousemove during an active drag action; it fires actionmove instead	Bind both geo_event.mousemove and geo_event.actionmove if you need live drag positions
currentAnnotation non-null but user isn't drawing	Completing an annotation resets layer mode to null; refreshAnnotationMode re-arms with a fresh EMPTY in-create annotation	Non-null ≠ drawing — check currentAnnotation.coordinates().length

Coordinate systems

The image map has ingcs !== gcs (y-flipped/scaled pixel system from geojs.util.pixelCoordinateParams), so conversions are non-trivial and every mistake is visible.

• annotation.coordinates() returns ingcs; mouse evt.geo is ingcs; annotation._coordinates(v) sets raw gcs — asymmetric.
• addAnnotation(a, gcs) / addMultipleAnnotations(list, gcs, update) convert ingcs→gcs on every call, mutating the feature. The gcs param contract:
  • undefined → treat coords as ingcs, convert once (correct for freshly created features)
  • null → map.gcs(), conversion skipped (correct for retained/pooled features being re-added)
• The GeoJS mock in unit tests does NOT model conversion — tests can only assert the gcs arg contract (toHaveBeenCalledWith([...], null, ...)). Visual drift must be verified in-browser (see in-browser-testing skill).

Render gating

_update (the WebGL feature-data rebuild) only runs when the layer's modified() timestamp advanced. clearOldAnnotations marks modified only when it removes something; a pure add pass with update=false marks nothing → invisible features. Debugging tell: run layer.modified(); layer.draw() in the console — if features appear instantly, it's this, not missing data. Guard the modified() call on "count actually grew" so pure pans keep the incremental-draw optimization.

Testing AnnotationViewer (unit)

Full guide: codebaseDocumentation/FRONTEND_COMPONENT_TESTING.md. Non-obvious conventions in src/components/AnnotationViewer.test.ts:

• Store mocks are reactive() — drive watchers/computeds after mount by mutating mockedStore.z / mockedAnnotationStore.annotations, then await wrapper.vm.$nextTick().
• Fake timers are active; the draw path is throttle(drawAnnotationsNoThrottle, 100) — flush trailing draws with vi.advanceTimersByTime(101).
• You cannot spy on <script setup> closures — assert via side effects: annotationLayer.draw (a vi.fn) or exposed computeds like wrapper.vm.displayedAnnotations.
• geojsAnnotationFactory mock ignores its args — to read drawn features by id, mockImplementation((shape, coords, options) => { const f = mockGeoJSAnnotation(shape); if (options) f.options(options); return f; }).
• @/utils/annotation is mocked with hand-copied pure helpers (importing the real module OOMs the file). If the component starts using a new exported helper, add it to the mock or you get "No export defined on the mock".
• layerSliceIndexes is a constant vi.fn by default; mockImplementation(() => ({ zIndex: mockedStore.z, ... })) to make the displayed set turn over per frame.

Related

• Driving GeoJS drawing tools from browser automation (synthetic drags, CDP pitfalls): in-browser-testing skill.
• Tool template/interaction structure: tool-development skill (references/tool-interaction-patterns.md).