@meta-sam/graphics 0.1.5 → 0.1.7

package/README.md

@@ -15,45 +15,28 @@ npm install @meta-sam/graphics @meta-sam/parser @meta-sam/video
 
 The renderer accepts image or video results and snapshots from `@meta-sam/parser`.
 Call and await `update()` before `render()`; rendering is synchronous and sees only
-the last successfully committed update.
+the last successfully committed update. The example parses one frame of SAM API
+output for a 320×334 image and draws it onto a canvas:
 
 <!-- readme-example -->
 
 ```ts
 import { SegmentationRenderer } from '@meta-sam/graphics';
-import type { ImageSegmentationResult } from '@meta-sam/parser';
+import { parseImageStream, type ResponsesEvent } from '@meta-sam/parser';
+
+// One SAM API line: object 0 with its box and mask, in a 320×334 source image.
+const outputText =
+  '<0f>0<|box;x1=211;y1=228;x2=270;y2=254;w=320;h=334|>' +
+  "<|mask;x=0;y=0;data=27,60,~!!!!M!0c[0o91w?q1!pIH4pPRVp2B3'7`e.ioeAf6-k/#Xd8%dX9x(|>\n";
+
+async function* responseEvents(): AsyncIterable<ResponsesEvent> {
+  const lane = { item_id: 'message-1', output_index: 0, content_index: 0 };
+  yield { type: 'response.output_text.delta', ...lane, delta: outputText };
+  yield { type: 'response.output_text.done', ...lane, text: outputText };
+  yield { type: 'response.completed' };
+}
 
-const result: ImageSegmentationResult = {
-  media: 'image',
-  revision: 1,
-  records: [
-    {
-      kind: 'mask',
-      order: 0,
-      objectId: 'bus',
-      identity: 'image:*:bus',
-      revision: 1,
-      mask: {
-        encoding: 'one_bit',
-        width: 5,
-        height: 5,
-        payload: '!!!!!(QO(0lu8?',
-      },
-    },
-    {
-      kind: 'box',
-      order: 1,
-      objectId: 'bus',
-      left: 1,
-      top: 1,
-      right: 4,
-      bottom: 4,
-    },
-  ],
-  diagnostics: [],
-  rawOutput: '',
-  outcome: { status: 'completed' },
-};
+const result = await parseImageStream(responseEvents()).finalResult;
 
 const canvas = document.querySelector<HTMLCanvasElement>('#overlay');
 if (canvas === null) throw new Error('Missing overlay canvas.');
@@ -65,7 +48,9 @@ const renderer = new SegmentationRenderer();
 await renderer.update(result);
 renderer.render(context, {
   media: 'image',
-  source: { x: 0, y: 0, width: 5, height: 5 },
+  // The source rectangle is the frame the API reported as `w` × `h`; each mask
+  // is placed at its own box (`bounds`) inside that frame.
+  source: { x: 0, y: 0, width: 320, height: 334 },
   target: { x: 0, y: 0, width: canvas.width, height: canvas.height },
 });
 
@@ -75,9 +60,9 @@ renderer.clear();
 renderer.dispose();
 ```
 
-The mask payload in this example is one complete, canonical `one_bit` payload. A
-real application normally passes parser snapshots to `update()` as they arrive and
-then passes the final result when parsing completes.
+A real application passes parser snapshots to `update()` as they arrive and then
+passes the final result when parsing completes. The renderer does not need the
+request, the media bytes, or the transport.
 
 ## Video and frame selection
 
@@ -168,8 +153,7 @@ complete current view to every `update()` call.
 
 - `update()` calls are serialized in invocation order. Always await the update that
   must be visible before calling `render()`.
-- Masks and boxes are retained. Text and point records are accepted but are not
-  drawn.
+- Masks and boxes are retained. Text records are accepted but are not drawn.
 - Mask records are collapsed by `identity`; the greatest per-mask `revision` wins.
   At the same revision, conflicting mask data is rejected.
 - Boxes are collapsed by frame and `objectId`; the last box in the accepted view
@@ -187,7 +171,10 @@ collapsed.
 
 ## Complete mask payloads
 
-Graphics accepts only complete masks with this shape:
+Graphics accepts only complete masks with this shape, where `encoding` is
+`lossless` (the SAM API default, payloads starting with `~`) or `one_bit`
+(payloads starting with `!`) and `payload` is the opaque base85 text from the
+wire, passed through unchanged:
 
 ```ts
 {
@@ -198,12 +185,16 @@ Graphics accepts only complete masks with this shape:
 }
 ```
 
+A mask record parsed from SAM API output also carries `bounds`, the half-open box
+the raster covers in source pixels; the renderer scales the `width × height`
+raster into that box. A mask without `bounds` is drawn as a full-frame raster.
+
 `width` and `height` must be positive safe integers, their area must be within the
 configured and codec limits, and `payload` must be within the configured and codec
 length limits. During `update()`, the renderer strictly decodes the entire payload,
-verifies decoder finalization, verifies that the representation is canonical, and
-traces the resulting binary raster. Partial, truncated, trailing, invalid, and
-noncanonical payloads reject the update. Unsupported encodings reject the update.
+verifies decoder finalization, verifies that a `one_bit` representation is
+canonical, and traces the resulting binary raster. Partial, truncated, trailing,
+and invalid payloads reject the update, as does any other encoding.
 
 Use `@meta-sam/parser` to produce complete mask records. Graphics does not accept
 streaming mask fragments.
@@ -243,7 +234,8 @@ A hidden object contributes neither its mask nor its box, and its mask `Path2D`
 not created. Colors and geometry are intentionally fixed; fill and outline opacity
 are configurable:
 
-- Each `objectId` hashes deterministically to one of eight colors.
+- Each `objectId` hashes deterministically to one of eight colors; `objectColor(id)`
+  returns the same color so legends can match the overlay.
 - Every mask is traced once into a marching-squares contour: its vertices are the
   midpoints of the edges between neighbouring pixel centers, so a straight
   boundary follows the pixel edge while corners and diagonals are cut at 45°
@@ -371,8 +363,9 @@ Only the package root is public; deep imports are not supported.
 | Export                           | Purpose                                                     |
 | -------------------------------- | ----------------------------------------------------------- |
 | `SegmentationRenderer`           | Retain parser views and render masks and boxes.             |
+| `objectColor`                    | The color assigned to an object ID, for legends and labels. |
 | `SegmentationGraphicsError`      | Base class for package-specific errors.                     |
-| `UnsupportedMaskEncodingError`   | Reject a mask encoding other than `one_bit`.                |
+| `UnsupportedMaskEncodingError`   | Reject a mask encoding other than `lossless` or `one_bit`.  |
 | `InvalidMaskPayloadError`        | Reject invalid mask data or a conflicting mask revision.    |
 | `SegmentationResourceLimitError` | Reject an update that exceeds a configured resource limit.  |
 | `InvalidRenderOptionsError`      | Reject invalid result, frame, rectangle, or transform data. |

package/dist/renderer.js

@@ -52,8 +52,6 @@ export function objectColor(objectId) {
  */
 const RETAINED_MASK_OVERHEAD = 64;
 function sameBounds(left, right) {
-    if (left === undefined || right === undefined)
-        return left === right;
     return (left.left === right.left &&
         left.top === right.top &&
         left.right === right.right &&
@@ -150,7 +148,7 @@ function retainMask(record) {
         ...(record.frame === undefined ? {} : { frameIndex: record.frame.frameIndex }),
         width: record.mask.width,
         height: record.mask.height,
-        ...(record.bounds === undefined ? {} : { bounds: record.bounds }),
+        bounds: record.bounds,
     };
 }
 function traceMask(mask, limit) {
@@ -375,22 +373,18 @@ export class SegmentationRenderer {
                     continue;
                 const color = colorFor(mask.objectId);
                 context.fillStyle = color;
-                if (mask.bounds === undefined) {
-                    this.#paintMask(context, traced.path, color, outlineWidth);
+                // The raster covers the record's box: scale width × height into bounds.
+                context.save();
+                try {
+                    const boundsScaleX = (mask.bounds.right - mask.bounds.left) / mask.width;
+                    const boundsScaleY = (mask.bounds.bottom - mask.bounds.top) / mask.height;
+                    context.translate(mask.bounds.left, mask.bounds.top);
+                    context.scale(boundsScaleX, boundsScaleY);
+                    this.#paintMask(context, traced.path, color, outlineWidth /
+                        Math.max(Math.abs(boundsScaleX), Math.abs(boundsScaleY), Number.MIN_VALUE));
                 }
-                else {
-                    context.save();
-                    try {
-                        const boundsScaleX = (mask.bounds.right - mask.bounds.left) / mask.width;
-                        const boundsScaleY = (mask.bounds.bottom - mask.bounds.top) / mask.height;
-                        context.translate(mask.bounds.left, mask.bounds.top);
-                        context.scale(boundsScaleX, boundsScaleY);
-                        this.#paintMask(context, traced.path, color, outlineWidth /
-                            Math.max(Math.abs(boundsScaleX), Math.abs(boundsScaleY), Number.MIN_VALUE));
-                    }
-                    finally {
-                        context.restore();
-                    }
+                finally {
+                    context.restore();
                 }
             }
             for (const box of state.boxes.values()) {
@@ -555,13 +549,16 @@ export class SegmentationRenderer {
             mask.height <= 0) {
             throw new InvalidMaskPayloadError('Mask dimensions must be positive safe integers.');
         }
-        if (record.bounds !== undefined) {
-            const { left, top, right, bottom } = record.bounds;
-            if (![left, top, right, bottom].every(Number.isFinite) ||
-                right <= left ||
-                bottom <= top) {
-                throw new InvalidMaskPayloadError('Mask bounds are invalid.');
-            }
+        if (record.bounds === undefined ||
+            ![
+                record.bounds.left,
+                record.bounds.top,
+                record.bounds.right,
+                record.bounds.bottom,
+            ].every(Number.isFinite) ||
+            record.bounds.right <= record.bounds.left ||
+            record.bounds.bottom <= record.bounds.top) {
+            throw new InvalidMaskPayloadError('Mask bounds are invalid.');
         }
         const area = mask.width * mask.height;
         if (!Number.isSafeInteger(area) || area > this.#limits.maxMaskArea) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meta-sam/graphics",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Retained Canvas 2D renderer for SAM 3 segmentation",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://github.com/meta-models/meta-sam#readme",
@@ -33,7 +33,7 @@
     "node": "^20.17.0 || >=22.9.0"
   },
   "dependencies": {
-    "@meta-sam/parser": "0.0.8"
+    "@meta-sam/parser": "0.0.10"
   },
   "scripts": {
     "build": "tsc -b",