talmolab
diff --git a/‎README.md‎
Lines changed: 2 additions & 1 deletion b/‎README.md‎
Lines changed: 2 additions & 1 deletion
diff --git a/‎docs/api.md‎
Lines changed: 85 additions & 11 deletions b/‎docs/api.md‎
Lines changed: 85 additions & 11 deletions
diff --git a/‎docs/index.md‎
Lines changed: 3 additions & 3 deletions b/‎docs/index.md‎
Lines changed: 3 additions & 3 deletions
diff --git a/‎docs/usage.md‎
Lines changed: 24 additions & 8 deletions b/‎docs/usage.md‎
Lines changed: 24 additions & 8 deletions
diff --git a/‎src/codecs/dictionary.ts‎
Lines changed: 4 additions & 2 deletions b/‎src/codecs/dictionary.ts‎
Lines changed: 4 additions & 2 deletions
@@ -11,10 +11,11 @@ JavaScript/TypeScript utilities for reading and writing SLEAP `.slp` files with
 
 ## Features
 
-- SLP read/write with format compatibility (including embedded frames via HDF5 video datasets).
+- SLP read/write with format compatibility (format 1.0–1.7, including embedded frames via HDF5 video datasets).
 - Browser-compatible SLP writing via `saveSlpToBytes()`.
 - Streaming-friendly file access (URL, `File`, `FileSystemFileHandle`, `Blob`).
 - Core data model (`Labels`, `LabeledFrame`, `Instance`, `Skeleton`, `Video`, etc.).
+- ROI, segmentation mask, and bounding box annotations with GeoJSON I/O.
 - Video backends accept `string`, `File`, or `Blob` sources.
 - Browser-safe: Node.js-only dependencies (`skia-canvas`, `child_process`) are dynamically imported, so bundlers can tree-shake them.
 - Dictionary and numpy codecs for interchange.
 
@@ -18,12 +18,18 @@ import {
   LabelsSet,
   SuggestionFrame,
   ROI,
-  AnnotationType,
   SegmentationMask,
+  BoundingBox,
+  UserBoundingBox,
+  PredictedBoundingBox,
   toDict,
   fromDict,
   toNumpy,
   fromNumpy,
+  roisToGeoJSON,
+  roisFromGeoJSON,
+  writeGeoJSON,
+  readGeoJSON,
 } from "@talmolab/sleap-io.js";
 ```
 
@@ -142,7 +148,8 @@ Key types:
 - `Video`, `SuggestionFrame`, `LabelsSet`
 - `Camera`, `CameraGroup`, `RecordingSession` (camera utilities)
 - `LazyDataStore`, `LazyFrameList` (lazy loading)
-- `ROI`, `SegmentationMask`, `AnnotationType` (spatial annotations)
+- `ROI`, `SegmentationMask` (spatial annotations)
+- `BoundingBox`, `UserBoundingBox`, `PredictedBoundingBox` (detection/tracking)
 - `Point` has fields `{ xy, visible, complete, score? }` where `score` is an optional confidence value.
 - `LabeledFrame.isNegative` (`boolean`, default `false`): marks negative-annotated frames.
 - `SuggestionFrame.group` (`string`, default `"default"`): the suggestion group name.
@@ -179,16 +186,15 @@ Key classes:
 
 ## ROI & Segmentation Masks
 
-Spatial annotations stored alongside pose data in SLP format 1.5.
+Spatial annotations stored alongside pose data (SLP format 1.5+).
 
 ### `ROI`
-Region of interest with GeoJSON-like geometry.
+Region of interest with GeoJSON-like geometry. Supports `Polygon`, `Point`, `MultiPolygon`, `MultiPoint`, `LineString`, and `GeometryCollection` types.
 
 ```ts
 // Create from bounding box
 const roi = ROI.fromBbox(100, 200, 50, 80, {
   category: "arena",
-  annotationType: AnnotationType.ARENA,
   video: labels.videos[0],
 });
 
@@ -197,12 +203,24 @@ const roi = ROI.fromPolygon([[0,0], [100,0], [100,100], [0,100]], {
   category: "region",
 });
 
+// Create from multi-polygon
+const roi = ROI.fromMultiPolygon([
+  [[[0,0], [10,0], [10,10], [0,10], [0,0]]],
+  [[[20,20], [30,20], [30,30], [20,30], [20,20]]],
+]);
+
 // Properties
 roi.bounds;    // { minX, minY, maxX, maxY }
 roi.area;      // polygon area
 roi.centroid;  // { x, y }
 roi.isBbox;    // true if axis-aligned rectangle
 
+// Explode multi-geometries into individual ROIs
+const parts = roi.explode();  // ROI[]
+
+// Convert to GeoJSON Feature
+const feature = roi.toGeoJSON();
+
 // Convert to mask
 const mask = roi.toMask(480, 640);
 ```
@@ -225,21 +243,77 @@ mask.bbox;  // { x, y, width, height }
 const roi = mask.toPolygon();
 ```
 
-### `Labels` ROI/Mask Access
+### `BoundingBox`
+Axis-aligned or rotated bounding box for detection/tracking workflows (SLP format 1.7).
+
+```ts
+// Create user-annotated bbox
+const bbox = new UserBoundingBox({
+  xCenter: 50, yCenter: 60, width: 100, height: 80,
+  video: labels.videos[0], frameIdx: 3, category: "animal",
+});
+
+// Create predicted bbox with confidence score
+const bbox = new PredictedBoundingBox({
+  xCenter: 50, yCenter: 60, width: 100, height: 80,
+  score: 0.95,
+});
+
+// Factory methods
+const bbox = BoundingBox.fromXyxy(10, 20, 110, 100);  // corner coords
+const bbox = BoundingBox.fromXywh(10, 20, 100, 80);   // top-left + size
+
+// Properties
+bbox.xyxy;       // [x1, y1, x2, y2] (axis-aligned)
+bbox.xywh;       // { x, y, width, height }
+bbox.corners;    // number[][] (4 corner points, respects rotation)
+bbox.bounds;     // { minX, minY, maxX, maxY }
+bbox.area;       // width * height
+bbox.centroid;   // { x, y }
+bbox.isPredicted; // true for PredictedBoundingBox
+bbox.isStatic;   // true if no frameIdx
+bbox.isRotated;  // true if angle != 0
+
+// Conversion
+const roi = bbox.toRoi();              // Polygon ROI
+const mask = bbox.toMask(480, 640);    // SegmentationMask
+```
+
+### `Labels` ROI/Mask/BBox Access
 
 ```ts
 // Direct access
-labels.rois;       // ROI[]
-labels.masks;      // SegmentationMask[]
-labels.staticRois; // ROIs without frame index
+labels.rois;         // ROI[]
+labels.masks;        // SegmentationMask[]
+labels.bboxes;       // BoundingBox[]
+labels.staticRois;   // ROIs without frame index
 labels.temporalRois; // ROIs with frame index
+labels.staticBboxes; // BBoxes without frame index
+labels.temporalBboxes; // BBoxes with frame index
 
 // Filtered queries
 labels.getRois({ video, frameIdx: 0, category: "arena" });
-labels.getMasks({ video, annotationType: AnnotationType.SEGMENTATION });
+labels.getMasks({ video, category: "segmentation" });
+labels.getBboxes({ video, frameIdx: 0, predicted: true });
 ```
 
-ROIs and masks are read/written in SLP format 1.5 files. The format ID is automatically set to 1.5 when ROIs or masks are present.
+The format ID is set automatically: 1.5 for ROIs/masks, 1.6 for ROIs with instance associations, 1.7 when bounding boxes are present.
+
+## GeoJSON I/O
+
+Convert ROIs to/from GeoJSON format.
+
+```ts
+// Convert ROIs to GeoJSON FeatureCollection
+const geojson = roisToGeoJSON(labels.rois);
+
+// Serialize to JSON string
+const json = writeGeoJSON(labels.rois);
+
+// Parse GeoJSON back to ROIs
+const rois = roisFromGeoJSON(geojson);
+const rois = readGeoJSON(jsonString);
+```
 
 ## Skeleton Codecs
 
 
@@ -24,11 +24,11 @@ await saveSlp(labels, "/tmp/session-roundtrip.slp", { embed: false });
 
 ## Features
 
-- SLP read/write with embedded frame support (format 1.0–1.5).
-- ROI and segmentation mask annotations (format 1.5).
+- SLP read/write with embedded frame support (format 1.0–1.7).
+- ROI and segmentation mask annotations (format 1.5), ROI-instance associations (format 1.6), bounding boxes (format 1.7).
 - Browser-compatible SLP writing via `saveSlpToBytes()`.
 - Streaming inputs (URL, `File`, `FileSystemFileHandle`, `Blob`).
-- Data model types (`Labels`, `LabeledFrame`, `Instance`, `Skeleton`, `Video`, `ROI`, `SegmentationMask`).
+- Data model types (`Labels`, `LabeledFrame`, `Instance`, `Skeleton`, `Video`, `ROI`, `SegmentationMask`, `BoundingBox`).
 - Video backends accept `string`, `File`, or `Blob` sources.
 - Browser-safe: Node.js-only code is fully isolated from the browser bundle.
 - Dictionary and numpy codecs.
 
@@ -301,30 +301,46 @@ const trainLabels = set.get("train");
 await saveSlpSet(set);
 ```
 
-## ROI & Segmentation Masks
+## ROI, Segmentation Masks & Bounding Boxes
 
-SLP format 1.5 supports spatial annotations (regions of interest and segmentation masks) alongside pose data:
+SLP format 1.5+ supports spatial annotations alongside pose data: ROIs (format 1.5), ROI-instance associations (format 1.6), and bounding boxes (format 1.7).
 
 ```ts
-import { loadSlp, ROI, SegmentationMask, AnnotationType } from "@talmolab/sleap-io.js";
+import {
+  loadSlp, ROI, SegmentationMask,
+  UserBoundingBox, PredictedBoundingBox, BoundingBox,
+  writeGeoJSON, readGeoJSON,
+} from "@talmolab/sleap-io.js";
 
 const labels = await loadSlp("dataset.slp");
 
-// Access ROIs and masks
-console.log(`${labels.rois.length} ROIs, ${labels.masks.length} masks`);
+// Access ROIs, masks, and bounding boxes
+console.log(`${labels.rois.length} ROIs, ${labels.masks.length} masks, ${labels.bboxes.length} bboxes`);
 
 // Query by video and frame
 const frameRois = labels.getRois({ video: labels.videos[0], frameIdx: 0 });
 const frameMasks = labels.getMasks({ video: labels.videos[0], frameIdx: 0 });
+const frameBboxes = labels.getBboxes({ video: labels.videos[0], frameIdx: 0 });
 
 // Create new ROIs
-const bbox = ROI.fromBbox(100, 200, 50, 80, {
+const roi = ROI.fromBbox(100, 200, 50, 80, {
   category: "arena",
   video: labels.videos[0],
 });
-labels.rois.push(bbox);
+labels.rois.push(roi);
 
-// Save — format 1.5 is used automatically when ROIs/masks are present
+// Create bounding boxes
+const bbox = new UserBoundingBox({
+  xCenter: 150, yCenter: 240, width: 50, height: 80,
+  category: "animal", video: labels.videos[0], frameIdx: 0,
+});
+labels.bboxes.push(bbox);
+
+// Export ROIs to GeoJSON
+const geojsonStr = writeGeoJSON(labels.rois);
+const restoredRois = readGeoJSON(geojsonStr);
+
+// Save — format version is set automatically based on content
 await saveSlp(labels, "output.slp");
 ```
 
 
@@ -26,6 +26,7 @@ export type LabelsDict = {
     frame_idx: number;
     video_idx: number;
     instances: Array<Record<string, unknown>>;
+    is_negative?: boolean;
   }>;
   suggestions: Array<Record<string, unknown>>;
   provenance: Record<string, unknown>;
@@ -61,13 +62,14 @@ export function toDict(
   const labeledFrames: LabelsDict["labeled_frames"] = [];
   for (const frame of labels.labeledFrames) {
     if (videoFilter && !frame.video.matchesPath(videoFilter.video, true)) continue;
-    if (options?.skipEmptyFrames && frame.instances.length === 0) continue;
+    if (options?.skipEmptyFrames && frame.instances.length === 0 && !frame.isNegative) continue;
     const videoIdx = videos.indexOf(frame.video);
     if (videoIdx < 0) continue;
     labeledFrames.push({
       frame_idx: frame.frameIdx,
       video_idx: videoIdx,
       instances: frame.instances.map((instance) => instanceToDict(instance, labels, trackIndex)),
+      ...(frame.isNegative ? { is_negative: true } : {}),
     });
   }
 
@@ -121,7 +123,7 @@ export function fromDict(data: LabelsDict): Labels {
   const labeledFrames = data.labeled_frames.map((frame) => {
     const video = videos[frame.video_idx];
     const instances = frame.instances.map((inst) => dictToInstance(inst, skeletons, tracks));
-    return new LabeledFrame({ video, frameIdx: frame.frame_idx, instances });
+    return new LabeledFrame({ video, frameIdx: frame.frame_idx, instances, isNegative: frame.is_negative ?? false });
   });
 
   const suggestions = data.suggestions.map((suggestion) => {