meta-sam-parser 0.0.2__tar.gz → 0.0.3__tar.gz

{meta_sam_parser-0.0.2 → meta_sam_parser-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meta-sam-parser
-Version: 0.0.2
+Version: 0.0.3
 Summary: Native Python parsing primitives for the SAM 3 segmentation protocol
 Project-URL: Homepage, https://github.com/meta-models/meta-sam
 Project-URL: Repository, https://github.com/meta-models/meta-sam
@@ -106,24 +106,35 @@ python -m pip install .
 
 Import supported APIs only from the package root. Deep imports are unsupported;
 underscore-prefixed modules are implementation details and may change without notice.
-Format factories are zero-argument and create isolated parser state:
+Format factories are zero-argument and create isolated parser state. The example
+feeds the parser one frame of SAM 3.1 output exactly as the API emits it - one line
+per frame, `<Nf>` then comma-separated `id<|box;...|><|mask;...|>` records:
 
 ```python
 from meta_sam_parser import CompletedOutcome, video_segmentation_format
 
+output_text = (
+    "<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(|>"
+    ",1<|box;x1=155;y1=228;x2=202;y2=254;w=320;h=334|>"
+    "<|mask;x=0;y=0;data=27,48,~!!!!J!0c[q=Pj_zs=*4C4(/./x#:/`S_GnD`=o3?X{emCgO$y@|>\n"
+)
+
 format_ = video_segmentation_format()
 parser = format_.create_parser()
 
-for snapshot in parser.push(
-    "[frame=7] object=bus box=(10,20,110,80)\n"
-    "[frame=7] object=bus mask=one_bit;size=5x5;data=!!!!!(QO(0lu8?\n"
-):
+# Chunks may split anywhere, including inside a mask payload.
+split = output_text.index(",1<|box")
+for snapshot in parser.push(output_text[:split]):
     print(snapshot.revision, len(snapshot.records))
+for snapshot in parser.push(output_text[split:]):
+    print(snapshot.revision, len(snapshot.records))  # 1 4
 
 finished = parser.finish(CompletedOutcome())
 for snapshot in finished.events:
     print(snapshot.revision, len(snapshot.records))
 result = finished.result
+# Two box records and two mask records, object IDs "0" and "1", frame 0.
 ```
 
 `push()` accepts arbitrarily split text chunks and returns zero or one cumulative
@@ -228,10 +239,10 @@ All public values are frozen, slotted dataclasses. Observable collections are
 tuples. The package root exports:
 
 - Geometry, masks, and aliases: `FrameReference`, `SegmentationMaskBounds`,
-  `SegmentationMask`, `SegmentationMaskIdentity`, `SegmentationMedia`,
+  `SegmentationMask`, `SegmentationMaskEncoding`, `SegmentationMaskIdentity`, `SegmentationMedia`,
   `DiagnosticSeverity`, and `IncompleteReason`.
-- Records: `SegmentationTextRecord`, `SegmentationPointRecord`,
-  `SegmentationBoxRecord`, `SegmentationMaskRecord`, and `SegmentationRecord`.
+- Records: `SegmentationTextRecord`, `SegmentationBoxRecord`,
+  `SegmentationMaskRecord`, and `SegmentationRecord`.
 - Views: `SegmentationDiagnostic`, `ImageSegmentationSnapshot`,
   `VideoSegmentationSnapshot`, `SegmentationSnapshot`,
   `ImageSegmentationResult`, `VideoSegmentationResult`, and
@@ -258,15 +269,31 @@ the next revision.
 
 ## Parsing behavior
 
-The documented package grammar is the line form in the
+SAM 3.1 returns segmentation as special-token text in one `output_text` lane, one
+line per frame:
+
+```text
+<Nf>id<|box;x1=..;y1=..;x2=..;y2=..;w=<frameW>;h=<frameH>|><|mask;x=0;y=0;data=<H>,<W>,<enc>payload|>,id<|box;...|><|mask;...|>
+```
+
+`<Nf>` is the zero-based frame index; frames without a visible object emit no
+line, so indices can skip. Each comma-separated record is a bare integer object
+id - stable for an object across the frames of one response and not a dense
+sequence - followed by one box and one mask. The parser retains the id as a string
+in `object_id`. Box corners and the `w`/`h` frame size are source pixels; the
+inclusive wire `x2`/`y2` become half-open `right`/`bottom`. The mask tuple is
+`height,width,payload`, where the payload's first character selects the encoding:
+`~` for `lossless` (the API default) or `!` for `one_bit`. The payload is base85,
+not base64: after the marker its digits are printable ASCII `!` through `{` minus
+the wire delimiters `" \ , ; < > |`, so it contains `*`, `$`, brackets, and
+backticks, a base64 regex will not match it, and only the first character after
+`H,W,` is the marker (`!` is also digit zero). Pass it through unchanged. Each record becomes one `SegmentationBoxRecord` followed by
+one `SegmentationMaskRecord` whose `bounds` is the same half-open box. Image streams require frame zero and omit the frame from
+normalized records; video records retain `frame.frame_index`. Every mask is
+strictly decoded before insertion; an empty lane is a valid completed response
+with no records.
+The grammar is specified in the
 [SAM 3 protocol](https://github.com/meta-models/meta-sam/blob/main/protocol/sam3.md).
-The parser separately accepts compact box-first SAM API output as production
-compatibility input and normalizes it to the same records. Its object token is an
-ASCII-decimal ID retained as a string, and IDs may be multi-digit or non-contiguous.
-The compact input's inclusive `x2`/`y2` coordinates become half-open `right`/`bottom`
-bounds. Image API
-records require frame zero and omit it from normalized records; video records retain
-frame indices. Every mask is strictly decoded before insertion.
 
 Plain text remains an ordered text record. Malformed structured-looking lines
 produce diagnostics and parsing continues. `raw_output` preserves every input
@@ -359,8 +386,11 @@ by the `release PyPI distribution` workflow
 1. Bump `version` in `pyproject.toml`, run `node scripts/sync-compatibility` from
    the repository root so the compatibility matrix records the new version, and
    merge that change to `main`.
-2. Push the tag `meta-sam-parser@<version>` at that commit. The workflow refuses a
-   tag that does not match the manifest version.
+2. Push the tag `meta-sam-parser@<version>` at that merge commit on `main`. The
+   workflow refuses a tag that does not match the manifest version, a tag whose
+   commit is not on `main`, and a tag older than the latest `main` commit touching
+   `python/`, `conformance/`, or `protocol/`, so a tag created before later fixes
+   merged cannot publish stale source.
 3. The workflow builds the reproducible wheel and sdist, runs the artifact and
    clean-consumer audits and the cross-language conformance suite, and then waits
    for approval in the `pypi` GitHub environment before uploading through PyPI

{meta_sam_parser-0.0.2 → meta_sam_parser-0.0.3}/README.md

@@ -17,24 +17,35 @@ python -m pip install .
 
 Import supported APIs only from the package root. Deep imports are unsupported;
 underscore-prefixed modules are implementation details and may change without notice.
-Format factories are zero-argument and create isolated parser state:
+Format factories are zero-argument and create isolated parser state. The example
+feeds the parser one frame of SAM 3.1 output exactly as the API emits it - one line
+per frame, `<Nf>` then comma-separated `id<|box;...|><|mask;...|>` records:
 
 ```python
 from meta_sam_parser import CompletedOutcome, video_segmentation_format
 
+output_text = (
+    "<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(|>"
+    ",1<|box;x1=155;y1=228;x2=202;y2=254;w=320;h=334|>"
+    "<|mask;x=0;y=0;data=27,48,~!!!!J!0c[q=Pj_zs=*4C4(/./x#:/`S_GnD`=o3?X{emCgO$y@|>\n"
+)
+
 format_ = video_segmentation_format()
 parser = format_.create_parser()
 
-for snapshot in parser.push(
-    "[frame=7] object=bus box=(10,20,110,80)\n"
-    "[frame=7] object=bus mask=one_bit;size=5x5;data=!!!!!(QO(0lu8?\n"
-):
+# Chunks may split anywhere, including inside a mask payload.
+split = output_text.index(",1<|box")
+for snapshot in parser.push(output_text[:split]):
     print(snapshot.revision, len(snapshot.records))
+for snapshot in parser.push(output_text[split:]):
+    print(snapshot.revision, len(snapshot.records))  # 1 4
 
 finished = parser.finish(CompletedOutcome())
 for snapshot in finished.events:
     print(snapshot.revision, len(snapshot.records))
 result = finished.result
+# Two box records and two mask records, object IDs "0" and "1", frame 0.
 ```
 
 `push()` accepts arbitrarily split text chunks and returns zero or one cumulative
@@ -139,10 +150,10 @@ All public values are frozen, slotted dataclasses. Observable collections are
 tuples. The package root exports:
 
 - Geometry, masks, and aliases: `FrameReference`, `SegmentationMaskBounds`,
-  `SegmentationMask`, `SegmentationMaskIdentity`, `SegmentationMedia`,
+  `SegmentationMask`, `SegmentationMaskEncoding`, `SegmentationMaskIdentity`, `SegmentationMedia`,
   `DiagnosticSeverity`, and `IncompleteReason`.
-- Records: `SegmentationTextRecord`, `SegmentationPointRecord`,
-  `SegmentationBoxRecord`, `SegmentationMaskRecord`, and `SegmentationRecord`.
+- Records: `SegmentationTextRecord`, `SegmentationBoxRecord`,
+  `SegmentationMaskRecord`, and `SegmentationRecord`.
 - Views: `SegmentationDiagnostic`, `ImageSegmentationSnapshot`,
   `VideoSegmentationSnapshot`, `SegmentationSnapshot`,
   `ImageSegmentationResult`, `VideoSegmentationResult`, and
@@ -169,15 +180,31 @@ the next revision.
 
 ## Parsing behavior
 
-The documented package grammar is the line form in the
+SAM 3.1 returns segmentation as special-token text in one `output_text` lane, one
+line per frame:
+
+```text
+<Nf>id<|box;x1=..;y1=..;x2=..;y2=..;w=<frameW>;h=<frameH>|><|mask;x=0;y=0;data=<H>,<W>,<enc>payload|>,id<|box;...|><|mask;...|>
+```
+
+`<Nf>` is the zero-based frame index; frames without a visible object emit no
+line, so indices can skip. Each comma-separated record is a bare integer object
+id - stable for an object across the frames of one response and not a dense
+sequence - followed by one box and one mask. The parser retains the id as a string
+in `object_id`. Box corners and the `w`/`h` frame size are source pixels; the
+inclusive wire `x2`/`y2` become half-open `right`/`bottom`. The mask tuple is
+`height,width,payload`, where the payload's first character selects the encoding:
+`~` for `lossless` (the API default) or `!` for `one_bit`. The payload is base85,
+not base64: after the marker its digits are printable ASCII `!` through `{` minus
+the wire delimiters `" \ , ; < > |`, so it contains `*`, `$`, brackets, and
+backticks, a base64 regex will not match it, and only the first character after
+`H,W,` is the marker (`!` is also digit zero). Pass it through unchanged. Each record becomes one `SegmentationBoxRecord` followed by
+one `SegmentationMaskRecord` whose `bounds` is the same half-open box. Image streams require frame zero and omit the frame from
+normalized records; video records retain `frame.frame_index`. Every mask is
+strictly decoded before insertion; an empty lane is a valid completed response
+with no records.
+The grammar is specified in the
 [SAM 3 protocol](https://github.com/meta-models/meta-sam/blob/main/protocol/sam3.md).
-The parser separately accepts compact box-first SAM API output as production
-compatibility input and normalizes it to the same records. Its object token is an
-ASCII-decimal ID retained as a string, and IDs may be multi-digit or non-contiguous.
-The compact input's inclusive `x2`/`y2` coordinates become half-open `right`/`bottom`
-bounds. Image API
-records require frame zero and omit it from normalized records; video records retain
-frame indices. Every mask is strictly decoded before insertion.
 
 Plain text remains an ordered text record. Malformed structured-looking lines
 produce diagnostics and parsing continues. `raw_output` preserves every input
@@ -270,8 +297,11 @@ by the `release PyPI distribution` workflow
 1. Bump `version` in `pyproject.toml`, run `node scripts/sync-compatibility` from
    the repository root so the compatibility matrix records the new version, and
    merge that change to `main`.
-2. Push the tag `meta-sam-parser@<version>` at that commit. The workflow refuses a
-   tag that does not match the manifest version.
+2. Push the tag `meta-sam-parser@<version>` at that merge commit on `main`. The
+   workflow refuses a tag that does not match the manifest version, a tag whose
+   commit is not on `main`, and a tag older than the latest `main` commit touching
+   `python/`, `conformance/`, or `protocol/`, so a tag created before later fixes
+   merged cannot publish stale source.
 3. The workflow builds the reproducible wheel and sdist, runs the artifact and
    clean-consumer audits and the cross-language conformance suite, and then waits
    for approval in the `pypi` GitHub environment before uploading through PyPI

{meta_sam_parser-0.0.2 → meta_sam_parser-0.0.3}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meta-sam-parser"
-version = "0.0.2"
+version = "0.0.3"
 description = "Native Python parsing primitives for the SAM 3 segmentation protocol"
 readme = "README.md"
 requires-python = ">=3.10"

{meta_sam_parser-0.0.2 → meta_sam_parser-0.0.3}/src/meta_sam_parser/__init__.py

@@ -36,10 +36,10 @@ from ._types import (
     SegmentationDiagnostic,
     SegmentationMask,
     SegmentationMaskBounds,
+    SegmentationMaskEncoding,
     SegmentationMaskIdentity,
     SegmentationMaskRecord,
     SegmentationMedia,
-    SegmentationPointRecord,
     SegmentationRecord,
     SegmentationResult,
     SegmentationSnapshot,
@@ -80,10 +80,10 @@ __all__ = [
     "SegmentationDiagnostic",
     "SegmentationMask",
     "SegmentationMaskBounds",
+    "SegmentationMaskEncoding",
     "SegmentationMaskIdentity",
     "SegmentationMaskRecord",
     "SegmentationMedia",
-    "SegmentationPointRecord",
     "SegmentationRecord",
     "SegmentationResult",
     "SegmentationSnapshot",

{meta_sam_parser-0.0.2 → meta_sam_parser-0.0.3}/src/meta_sam_parser/_segmentation.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import math
 import re
 from dataclasses import dataclass
 from typing import cast
@@ -23,7 +22,6 @@ from ._types import (
     SegmentationMaskIdentity,
     SegmentationMaskRecord,
     SegmentationMedia,
-    SegmentationPointRecord,
     SegmentationRecord,
     SegmentationResult,
     SegmentationSnapshot,
@@ -40,65 +38,28 @@ _JS_WHITESPACE = (
 _JS_WHITESPACE_CLASS = (
     r"\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff"
 )
-_JS_WHITESPACE_PATTERN = rf"[{_JS_WHITESPACE_CLASS}]"
-_JS_NON_WHITESPACE_PATTERN = rf"[^{_JS_WHITESPACE_CLASS}]"
 _JS_DOT_PATTERN = r"[^\n\r\u2028\u2029]"
-_RECORD_PATTERN = re.compile(
-    rf"^(?:\[frame=([0-9]+)\]{_JS_WHITESPACE_PATTERN}+)?"
-    rf"object=([A-Za-z0-9._-]+){_JS_WHITESPACE_PATTERN}+"
-    rf"(point|box|mask)=({_JS_DOT_PATTERN}+)$"
-)
-_COMPACT_API_HEADER_PATTERN = re.compile(rf"^<([0-9]+)f>({_JS_DOT_PATTERN}*)$")
-_COMPACT_API_OBJECT_PATTERN = re.compile(
+_API_HEADER_PATTERN = re.compile(rf"^<([0-9]+)f>({_JS_DOT_PATTERN}*)$")
+_API_RECORD_PATTERN = re.compile(
     r"^(?:,)?([0-9]+)"
     r"<\|box;x1=(-?[0-9]+);y1=(-?[0-9]+);x2=(-?[0-9]+);"
     r"y2=(-?[0-9]+);w=([0-9]+);h=([0-9]+)\|>"
     r"<\|mask;x=0;y=0;data=([0-9]+),([0-9]+),([!~][^|]+)\|>"
 )
-_POINT_PATTERN = re.compile(r"^\(([^,]+),([^,]+)\)$")
-_BOX_PATTERN = re.compile(r"^\(([^,]+),([^,]+),([^,]+),([^,]+)\)$")
-_MASK_PATTERN = re.compile(
-    rf"^([^;{_JS_WHITESPACE_CLASS}]+);"
-    rf"size=([0-9]+)x([0-9]+);data=({_JS_NON_WHITESPACE_PATTERN}+)$"
-)
-_DECIMAL_NUMBER_PATTERN = re.compile(
-    r"^[+-]?(?:(?:[0-9]+(?:\.[0-9]*)?)|(?:\.[0-9]+))"
-    r"(?:[eE][+-]?[0-9]+)?$"
-)
-_HEXADECIMAL_NUMBER_PATTERN = re.compile(r"^0[xX][0-9A-Fa-f]+$")
-_BINARY_NUMBER_PATTERN = re.compile(r"^0[bB][01]+$")
-_OCTAL_NUMBER_PATTERN = re.compile(r"^0[oO][0-7]+$")
 
 
 def _trim(value: str) -> str:
     return value.strip(_JS_WHITESPACE)
 
 
-def _javascript_number(value: str) -> float | None:
-    normalized = _trim(value)
-    if not normalized:
-        return None
-    try:
-        if _HEXADECIMAL_NUMBER_PATTERN.fullmatch(normalized):
-            parsed = float(int(normalized[2:], 16))
-        elif _BINARY_NUMBER_PATTERN.fullmatch(normalized):
-            parsed = float(int(normalized[2:], 2))
-        elif _OCTAL_NUMBER_PATTERN.fullmatch(normalized):
-            parsed = float(int(normalized[2:], 8))
-        elif _DECIMAL_NUMBER_PATTERN.fullmatch(normalized):
-            parsed = float(normalized)
-        else:
-            return None
-    except (OverflowError, ValueError):
-        return None
-    return parsed if math.isfinite(parsed) else None
-
-
 def _integer_text(value: str) -> int | None:
-    parsed = _javascript_number(value)
-    if parsed is None or not parsed.is_integer() or abs(parsed) > _MAXIMUM_SAFE_INTEGER:
-        return None
-    return int(parsed)
+    """Parse a decimal integer token the way JavaScript's ``Number`` observes it.
+
+    Callers only pass regex captures of ``-?[0-9]+``; values beyond the
+    JavaScript safe-integer range are rejected so both parsers agree.
+    """
+    parsed = int(value)
+    return parsed if abs(parsed) <= _MAXIMUM_SAFE_INTEGER else None
 
 
 class _SegmentationParser:
@@ -180,50 +141,15 @@ class _SegmentationParser:
             return False
 
         if line.startswith("<"):
-            accepted = self._accept_compact_api_line(line, raw)
+            accepted = self._accept_api_line(line, raw)
             if accepted is not None:
                 return accepted
 
-        match = _RECORD_PATTERN.fullmatch(line)
-        if match is None:
-            if line.startswith("[frame=") or line.startswith("object="):
-                self._diagnose("malformed_record", "Malformed structured record.", raw)
-            else:
-                self._add_record(
-                    SegmentationTextRecord(order=len(self._records), text=raw)
-                )
-            return True
-
-        frame_index = None if match.group(1) is None else _integer_text(match.group(1))
-        if match.group(1) is not None and (frame_index is None or frame_index < 0):
-            self._diagnose(
-                "invalid_frame",
-                "Frame references must be non-negative safe integers.",
-                raw,
-            )
-            return True
-        if self._media == "image" and frame_index is not None:
-            self._diagnose(
-                "unexpected_frame",
-                "Image segmentation records cannot include a frame reference.",
-                raw,
-            )
-            return True
-
-        object_id = match.group(2)
-        kind = match.group(3)
-        value = match.group(4)
-        frame = None if frame_index is None else FrameReference(frame_index)
-        if kind == "point":
-            self._accept_point(object_id, frame, value, raw)
-        elif kind == "box":
-            self._accept_box(object_id, frame, value, raw)
-        else:
-            self._accept_mask(object_id, frame, value, raw)
+        self._add_record(SegmentationTextRecord(order=len(self._records), text=raw))
         return True
 
-    def _accept_compact_api_line(self, line: str, raw: str) -> bool | None:
-        header = _COMPACT_API_HEADER_PATTERN.fullmatch(line)
+    def _accept_api_line(self, line: str, raw: str) -> bool | None:
+        header = _API_HEADER_PATTERN.fullmatch(line)
         if header is None:
             return None
         frame_index = _integer_text(header.group(1))
@@ -247,17 +173,17 @@ class _SegmentationParser:
         if not remainder:
             self._diagnose(
                 "malformed_record",
-                "Malformed compact SAM API object record.",
+                "Malformed SAM API object record.",
                 raw,
             )
             return True
         accepted = False
         while remainder:
-            match = _COMPACT_API_OBJECT_PATTERN.match(remainder)
+            match = _API_RECORD_PATTERN.match(remainder)
             if match is None:
                 self._diagnose(
                     "malformed_record",
-                    "Malformed compact SAM API object record.",
+                    "Malformed SAM API object record.",
                     raw,
                 )
                 return True
@@ -267,7 +193,7 @@ class _SegmentationParser:
             )
             if any(value is None for value in coordinate_values):
                 self._diagnose(
-                    "invalid_box", "Canonical SAM box coordinates are invalid.", raw
+                    "invalid_box", "SAM API box coordinates are invalid.", raw
                 )
                 return True
             (
@@ -289,7 +215,7 @@ class _SegmentationParser:
                 or inclusive_bottom >= source_height
             ):
                 self._diagnose(
-                    "invalid_box", "Canonical SAM box coordinates are invalid.", raw
+                    "invalid_box", "SAM API box coordinates are invalid.", raw
                 )
                 return True
             bounds = SegmentationMaskBounds(
@@ -309,14 +235,16 @@ class _SegmentationParser:
                     bottom=inclusive_bottom + 1,
                 )
             )
-            mask_height = match.group(8)
-            mask_width = match.group(9)
             payload = match.group(10)
-            encoding = "lossless" if payload.startswith("~") else "one_bit"
             self._accept_mask(
                 object_id,
                 frame,
-                f"{encoding};size={mask_width}x{mask_height};data={payload}",
+                SegmentationMask(
+                    encoding="lossless" if payload.startswith("~") else "one_bit",
+                    payload=payload,
+                    width=int(match.group(9)),
+                    height=int(match.group(8)),
+                ),
                 raw,
                 bounds,
             )
@@ -324,109 +252,20 @@ class _SegmentationParser:
             remainder = remainder[match.end() :]
         return accepted
 
-    def _accept_point(
-        self,
-        object_id: str,
-        frame: FrameReference | None,
-        value: str,
-        raw: str,
-    ) -> None:
-        match = _POINT_PATTERN.fullmatch(_trim(value))
-        x = None if match is None else _javascript_number(match.group(1))
-        y = None if match is None else _javascript_number(match.group(2))
-        if x is None or y is None:
-            self._diagnose(
-                "malformed_point", "Point coordinates must be finite numbers.", raw
-            )
-            return
-        self._add_record(
-            SegmentationPointRecord(
-                order=len(self._records),
-                object_id=object_id,
-                frame=frame,
-                x=x,
-                y=y,
-            )
-        )
-
-    def _accept_box(
-        self,
-        object_id: str,
-        frame: FrameReference | None,
-        value: str,
-        raw: str,
-    ) -> None:
-        match = _BOX_PATTERN.fullmatch(_trim(value))
-        coordinates = (
-            None
-            if match is None
-            else tuple(_javascript_number(item) for item in match.group(1, 2, 3, 4))
-        )
-        if coordinates is None or any(item is None for item in coordinates):
-            self._diagnose(
-                "malformed_box", "Box coordinates must be finite numbers.", raw
-            )
-            return
-        left, top, right, bottom = cast(tuple[float, float, float, float], coordinates)
-        if right < left or bottom < top:
-            self._diagnose("invalid_box", "Box coordinates must be ordered.", raw)
-            return
-        self._add_record(
-            SegmentationBoxRecord(
-                order=len(self._records),
-                object_id=object_id,
-                frame=frame,
-                left=left,
-                top=top,
-                right=right,
-                bottom=bottom,
-            )
-        )
-
     def _accept_mask(
         self,
         object_id: str,
         frame: FrameReference | None,
-        value: str,
+        mask: SegmentationMask,
         raw: str,
-        bounds: SegmentationMaskBounds | None = None,
+        bounds: SegmentationMaskBounds,
     ) -> None:
-        match = _MASK_PATTERN.fullmatch(_trim(value))
-        if match is None:
-            self._diagnose(
-                "malformed_mask",
-                "Mask records require encoding, size, and one complete payload.",
-                raw,
-            )
-            return
-        encoding = match.group(1)
-        width_number = _javascript_number(match.group(2))
-        height_number = _javascript_number(match.group(3))
-        width = int(width_number) if width_number is not None else 0
-        height = int(height_number) if height_number is not None else 0
-        payload = match.group(4)
-        if encoding not in ("one_bit", "lossless"):
-            self._diagnose(
-                "unsupported_mask_encoding",
-                f"Unsupported complete mask encoding: {encoding}.",
-                raw,
-            )
-            return
-        area = float(width) * float(height)
-        if (
-            width <= 0
-            or height <= 0
-            or not math.isfinite(area)
-            or not area.is_integer()
-            or abs(area) > _MAXIMUM_SAFE_INTEGER
-        ):
+        area = mask.width * mask.height
+        if mask.width <= 0 or mask.height <= 0 or area > _MAXIMUM_SAFE_INTEGER:
             self._diagnose(
                 "invalid_mask_size", "Mask dimensions must be positive.", raw
             )
             return
-        mask = SegmentationMask(
-            encoding=encoding, payload=payload, width=width, height=height
-        )
         try:
             decode_mask_to_raster(mask)
         except InvalidSegmentationMaskError as error:

{meta_sam_parser-0.0.2 → meta_sam_parser-0.0.3}/src/meta_sam_parser/_types.py

@@ -48,11 +48,20 @@ class SegmentationMaskBounds:
     bottom: float
 
 
+SegmentationMaskEncoding: TypeAlias = Literal["lossless", "one_bit"]
+"""The wire encodings of a mask payload: ``~`` selects lossless, ``!`` one_bit."""
+
+
 @dataclass(frozen=True, slots=True)
 class SegmentationMask:
-    """One complete encoded SAM 3 segmentation mask."""
+    """One complete mask exactly as the SAM API emitted it.
+
+    ``payload`` is the base85 text after the encoding marker and is never
+    partial; ``width`` and ``height`` are the raster's own dimensions, not the
+    frame's.
+    """
 
-    encoding: str
+    encoding: SegmentationMaskEncoding
     payload: str
     width: int
     height: int
@@ -76,18 +85,6 @@ class SegmentationTextRecord:
     text: str
 
 
-@dataclass(frozen=True, slots=True)
-class SegmentationPointRecord:
-    """A point associated with one object and optional frame."""
-
-    kind: Literal["point"] = field(default="point", init=False)
-    order: int
-    object_id: str
-    x: float
-    y: float
-    frame: FrameReference | None = None
-
-
 @dataclass(frozen=True, slots=True)
 class SegmentationBoxRecord:
     """A half-open or explicitly supplied box in source-media coordinates."""
@@ -112,15 +109,12 @@ class SegmentationMaskRecord:
     identity: SegmentationMaskIdentity
     revision: int
     mask: SegmentationMask
+    bounds: SegmentationMaskBounds
     frame: FrameReference | None = None
-    bounds: SegmentationMaskBounds | None = None
 
 
 SegmentationRecord: TypeAlias = (
-    SegmentationTextRecord
-    | SegmentationPointRecord
-    | SegmentationBoxRecord
-    | SegmentationMaskRecord
+    SegmentationTextRecord | SegmentationBoxRecord | SegmentationMaskRecord
 )