pixel_cursor/selectors.py

"""Selectors: WHAT a cursor targets in pixel space.

Hierarchy (each subsumes the previous as a special case):
    Point < Mask < Region < Layer < Anchor3D

Token is orthogonal — semantic rather than spatial; the cross-attention map
of the bound model materializes the spatial extent at op time.
"""
from __future__ import annotations
from dataclasses import dataclass
from typing import Optional, Tuple, Union

import numpy as np


@dataclass(frozen=True, slots=True)
class Point:
    x: float
    y: float
    z: Optional[float] = None


@dataclass(frozen=True, slots=True)
class Region:
    x: int
    y: int
    w: int
    h: int


@dataclass(frozen=True, slots=True, eq=False)
class Mask:
    bitmap: np.ndarray
    is_soft: bool = False


@dataclass(frozen=True, slots=True)
class Token:
    text: str
    embedding_id: Optional[str] = None


@dataclass(frozen=True, slots=True)
class Layer:
    layer_id: str


@dataclass(frozen=True, slots=True)
class Anchor3D:
    anchor_id: str
    bbox: Tuple[float, float, float, float, float, float]


Selector = Union[Point, Region, Mask, Token, Layer, Anchor3D]