Write generic keys instead of dive_-prefixed ones - #1866
Conversation
Attributes, notes and confidence pairs are not DIVE concepts, so export writes attributes, track_attributes, notes and confidence_pairs. Import still reads the prefixed spellings, so older files keep working.
The repo's eslint config disallows for...of.
|
I'm hesitant about dropping the dive_ prefix on these annotation keys, even though the concepts (attributes, notes, confidence pairs) aren't DIVE-only. The concepts being generic doesn't make the wire encoding a shared convention. DIVE's shapes are specific: notes as a string array, confidence_pairs as an ordered sparse vector with explicit-zero vs absent semantics, attributes / track_attributes as free-form dicts with DIVE reserved keys. Writing those under bare names reads like "this is how everyone should spell this in COCO," when it's really still DIVE's profile. We already acknowledge that with info.dive_extensions and dive_dataset_info listing unprefixed keys inside a DIVE-owned extensions list is a bit inconsistent. More practically, unprefixed names are collision-prone. attributes and notes are exactly the kind of keys another exporter (or a future KWCOCO/COCO convention) might already use with a different schema. Once we prefer the generic spelling on import, a foreign file that happens to carry attributes or notes gets silently interpreted as DIVE's. The prefix was cheap insurance against that; reclaiming a common name after we've published it as our write path is hard. annotation_fps was a different case — VIAME and DIVE aligned on a shared name for a shared meaning. Here we're unilaterally claiming common slots without that coordination, and it's a breaking change for anything that already reads dive_* off our exports. |
Per-detection attributes, track attributes, notes and confidence pairs are generic annotation concepts — nothing about them is specific to DIVE — so export should not brand them. Export now writes
attributes,track_attributes,notesandconfidence_pairs.Import already fell back to the unprefixed names for attributes and notes (
kwcoco.py:345,349,coco.ts:452,462,466); this makes those the preferred spelling and keeps thedive_-prefixed ones as legacy aliases, so files DIVE wrote earlier keep importing.confidence_pairsgains the same treatment on both readers.Kept prefixed, because they really are DIVE-specific:
info.dive_dataset_info— DIVE's dataset metadata blockinfo.dive_extensions— DIVE describing which optional keys it used (its contents are now the generic names)This changes DIVE's output format. Anything downstream reading
dive_detection_attributes,dive_track_attributes,dive_notesordive_confidence_pairsoff a DIVE export needs updating; the readers here are covered, third parties are not.info.dive_extensionsstill advertises which keys a given file uses.Tests: export assertions moved to the generic keys; existing prefixed documents were left as-is so they now serve as legacy-import coverage, and both suites gained an explicit generic-vs-prefixed pair.
docs/DataFormats.mdupdated, including the worked example and the legacy-alias notes.Verified: 44 server tests pass locally, and a real export/import round trip writes
['attributes', 'confidence_pairs', 'notes', 'prob', 'track_attributes']and reads every value back.Not run: vitest, eslint and tsc — no
node_modulesin this checkout.Stacked context: #1865 renames
videos[].fpstoannotation_fpsand is still open. Both touch these files, so whichever lands second will need a trivial rebase.