^jʿUdZddlmZddlZddlmZddlmZddlZ ddl mZ ddl m Z mZddZ dd Z dd Z dd Z dd Zd Zded<dZded< ddZGddZy)uCrop-RLE compact mask storage for memory-efficient instance segmentation. Dense ``(N, H, W)`` boolean masks use O(N·H·W) memory, which becomes prohibitive for aerial imagery (e.g. 1000 objects x 4K image ~ 8.3 GB). :class:`CompactMask` stores each mask as a run-length encoding of its bounding-box crop, reducing typical usage to tens of MB. The bounding boxes (``xyxy``) already present in ``Detections`` serve as the crop boundaries, so no extra metadata is required from the caller. ) annotationsN)Iterator)Any)_mask_to_rle_counts_rle_counts_to_maskintcJttj|dddS)aReturn the number of ``True`` pixels in a run-length encoded mask. Args: rle: int32 array of run lengths as produced by :func:`_mask_to_rle_counts`. Returns: Total number of ``True`` pixels. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import _rle_area >>> rle = np.array([1, 2, 1, 1, 1], dtype=np.int32) >>> _rle_area(rle) 3 ``` N)rnpsum)rles m/var/www/ramen.bs-engineer-server.com/venv/lib/python3.12/site-packages/supervision/detection/compact_mask.py _rle_arears"& rvvc!$Q$i !!c8t|Dcgc]}g}}d}d}t|D]\}}|dzdk(} t|} | dkDr||z } t| | } t ||dk(r| rV||j dnA| t ||dz dzdk(k(r'||dxx| z cc<| | z} || z }||k\rd}|dz }||j | | | z} || z }||k\rd}|dz }| dkDr||k\snt|D]} || r |g|| <|Scc}w)aSplit a flat F-order RLE into per-column run lists. With F-order (column-major) RLE the flat pixel sequence visits all rows of column 0, then all rows of column 1, etc. Each column therefore contains ``crop_h`` contiguous pixels. Runs that cross column boundaries are split at the boundary. Each returned list starts with a ``False``-run count (possibly 0), matching the convention of :func:`_mask_to_rle_counts`. Args: rle: int32 run-length array as produced by :func:`~supervision.detection.utils.converters._mask_to_rle_counts`. crop_h: Number of rows (pixels per column). crop_w: Number of columns. Returns: List of ``crop_w`` run lists, one per column. Each list sums to ``crop_h``. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import _rle_split_cols >>> from supervision.detection.utils.converters import _mask_to_rle_counts >>> mask = np.array([[True, False], [True, True]], dtype=bool) >>> rle = _mask_to_rle_counts(mask) >>> rle.tolist() [0, 2, 1, 1] >>> _rle_split_cols(rle, 2, 2) [[0, 2], [1, 1]] ``` rr r )range enumeraterminlenappend)rcrop_hcrop_w_per_colcolrowrun_idxrun_lenis_true remaining space_in_coltakecs r_rle_split_colsr&1s{N-2&M:q:G: C C%cNA+"L !m!C R D( T! t &=C1HC CL   %  I 4KCf}q+!m, &= 5:6]"qz GAJ" NK ;s Dct|}|dk(rdgStj|tj}d}t |D]\}}|dzdk(||||z||z }||krd||d||}|j tj } tjtj| } tjt| dztj} tjt| dztj} d| d<| dz| dd| dz| dd|| d<| | z j} t|dr| jdd| S)uZScale one column's run list to a new height using a precomputed row map. Each output row is mapped to a source row via ``row_map``, which implements nearest-neighbour resampling in the vertical direction. Args: col_runs: Per-column run list starting with a ``False``-run count. src_h: Height of the source column (sum of ``col_runs``). row_map: int32 array of length ``new_crop_h``; ``row_map[r']`` is the source row index for output row ``r'``. Use ``(np.arange(new_crop_h) * src_h // new_crop_h)`` for ``cv2.INTER_NEAREST``-compatible mapping. Returns: Scaled run list of total length ``len(row_map)``, always starting with a ``False``-run count. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import _rle_scale_col >>> col_runs = [0, 2, 2] # F=0, T=2, F=2 → [T, T, F, F] >>> row_map = np.array([0, 1, 2, 3, 0, 1, 2, 3], dtype=np.int32) >>> _rle_scale_col(col_runs, 4, row_map) [0, 2, 2, 2, 2] ``` rdtyper r FNr) rr emptybool_rviewuint8 flatnonzerodiffint64tolistboolinsert)col_runssrc_hrow_map new_crop_h src_valuesposrirl out_values out_uint8 boundaries run_startsrun_ends result_runss r_rle_scale_colrBs[BWJQs )+bhh(GJ CH%B%'!Vq[ 3r" r  U{ 34G$J)I 23J(*Z11DBHH(UJ&(hhs:/B"((&SHJqM!^JqrNNHSbMHRL&3;;=K JqM1a rcg}|D]}|s|j|t|dz dzdk(}|s%|dxx|dz cc<|j|ddR|ddk(r3t|dkDr%|dxx|dz cc<|j|dd|j|tj|r|n|gtjS)aConcatenate per-column run lists into a flat RLE, merging junctions. Each column run list starts with a ``False``-run count. Two junction types can be merged across column boundaries: * ``False``/``False``: the trailing False run merges with the leading False run of the next column (leading count may be zero). * ``True``/``True``: when the accumulated output ends on a True run and the next column's leading False count is zero (column starts with True), the two True runs are merged to avoid inserting a zero-length False run that would inflate ``len(rle)`` and skew the density metric in :func:`_resize_crop`. Args: scaled_cols: List of per-column run lists, each starting with a ``False``-run count. new_total: Total pixel count of the output (fallback for empty input). Returns: Flat int32 RLE array starting with a ``False``-run count. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import _rle_join_cols >>> cols = [[1, 2], [1, 2]] # each col: F=1, T=2 >>> _rle_join_cols(cols, 6).tolist() [1, 2, 1, 2] ``` r r rrNr()extendrr arrayint32) scaled_cols new_total output_runsr4 last_is_trues r_rle_join_colsrKsF K-   x ( ,q0A5:LB8A;.""8AB<0!!c(ma&7B8A;.""8AB<0""8,-" 88;KYKrxx PPrc ||z}||zdk(s|dk(r&tjdgtjSt|dk(s't tj |ddddk(r&tj|gtjSt|dk(r/|ddk(r'tjd|gtjSt |||}tj||z|zjtj}tj||z|zjtj}i} g} |D]-} | | vrt|| ||| | <| j| | /t| |S)a Resize an F-order RLE-encoded crop via nearest-neighbour resampling. Manipulates run lengths directly without decoding to a full 2D boolean array. Delegates to :func:`_rle_split_cols`, :func:`_rle_scale_col`, and :func:`_rle_join_cols`. The nearest-neighbour mapping ``src = floor(dst * src_size / dst_size)`` is bit-exact with ``cv2.INTER_NEAREST``. Args: rle: int32 array of F-order run lengths as produced by :func:`~supervision.detection.utils.converters._mask_to_rle_counts`. Starts with a ``False``-run count (may be 0). crop_h: Height of the original crop. crop_w: Width of the original crop. new_crop_h: Height of the resized crop. new_crop_w: Width of the resized crop. Returns: int32 array of F-order run lengths for the resized crop, starting with the ``False``-run count. Examples: Upscale a 3x3 mask with a diagonal True stripe to 6x6: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import _rle_resize >>> from supervision.detection.utils.converters import ( ... _mask_to_rle_counts, _rle_counts_to_mask, ... ) >>> mask = np.array([ ... [True, False, False], ... [False, True, False], ... [False, False, True ], ... ], dtype=bool) >>> rle = _mask_to_rle_counts(mask) >>> resized_rle = _rle_resize(rle, 3, 3, 6, 6) >>> result = _rle_counts_to_mask(resized_rle, 6, 6) >>> result.astype(int) array([[1, 1, 0, 0, 0, 0], [1, 1, 0, 0, 0, 0], [0, 0, 1, 1, 0, 0], [0, 0, 1, 1, 0, 0], [0, 0, 0, 0, 1, 1], [0, 0, 0, 0, 1, 1]]) ``` rr(r Nr ) r rErFrrr r&arangeastyperBrrK) rrrr7 new_crop_wrHrcol_mapr6 col_cacherGsrc_cs r _rle_resizerSscpZ'I !yA~xx288,, 3x1}BFF3qt!t9-.!3xx 28844 3x1}Q1xxIbhh77c662Gyy$v-;CCBHHMGyy$v-;CCBHHMG')IK-  !-genfgNIe 9U+,- +y 11rg?float_L3_DENSITY_THRESHOLD_PARALLEL_THRESHOLDcddl}t|dk(r)tj||zgtjSt |t d||zz tkrt|||||St|||}|j|jtj||f|jjt}t!|S)uResize one RLE crop to ``(new_h, new_w)``, choosing the fastest path. Dispatch order: 1. **All-False fast path** — returns a single False run; no decode. 2. **L3 direct RLE path** — used when run density is below :data:`_L3_DENSITY_THRESHOLD`; manipulates run lengths without allocating a 2D array. 3. **cv2 fallback** — decodes to ``uint8``, calls ``cv2.resize(INTER_NEAREST)``, re-encodes; used for dense masks. Args: rle: int32 run-length array for the source crop. orig_h: Height of the source crop. orig_w: Width of the source crop. new_h: Target height. new_w: Target width. Returns: int32 RLE array for the resized crop. rNr(r ) interpolation)cv2rr rErFrmaxrUrSrresizer,r- INTER_NEARESTrNr2r)rorig_horig_wnew_hnew_wrZcropresizeds r _resize_croprdUs8~xxrxx88 3x#a&)),AA3u== sFF 3Djj "(( '' fTl  w ''rc2eZdZdZdZ ddZe ddZddZddZ ddZ ddZ e dd Z e dd Ze dd Ze dd Ze d d Zd!d"dZ d#dZd!d$dZd%dZed&dZd'dZ d(dZd)dZy)* CompactMasku Memory-efficient crop-RLE mask storage for instance segmentation. Instead of storing N full ``(H, W)`` boolean arrays, :class:`CompactMask` encodes each mask as a run-length sequence of its bounding-box crop. This reduces memory from O(N·H·W) to roughly O(N·bbox_area), which is orders of magnitude smaller for sparse masks on high-resolution images. The class exposes a duck-typed interface compatible with ``np.ndarray`` masks used elsewhere in ``supervision``: * ``mask[int]`` → dense ``(H, W)`` bool array (annotators, converters). * ``mask[slice | list | ndarray]`` → new :class:`CompactMask` (filtering). * ``np.asarray(mask)`` → dense ``(N, H, W)`` bool array (numpy interop). * ``mask.shape``, ``mask.dtype``, ``mask.area`` — match the dense API. :class:`CompactMask` is **not** a drop-in ``np.ndarray`` replacement. When you need to call arbitrary ndarray methods (``astype``, ``reshape``, ``ravel``, ``any``, ``all``, …) call :meth:`to_dense` first: ``cm.to_dense().astype(np.uint8)``. :meth:`to_dense` is the single explicit materialisation boundary. .. note:: **RLE encoding — COCO / pycocotools pixel-scan order** :class:`CompactMask` uses **column-major (Fortran-order, F-order)** run-lengths scoped to each mask's bounding-box crop, matching the pixel-scan order used by the COCO API (pycocotools). The crop scope still differs from the full-image scope used by pycocotools, so a :class:`CompactMask` RLE cannot be passed directly to ``maskUtils.iou()`` or ``maskUtils.decode()`` without re-scoping to the full canvas. Use :meth:`to_dense` to obtain a standard boolean array for pycocotools interop. This scan order is part of CompactMask's internal RLE representation. Switching from row-major (C-order) to column-major (F-order) is a backward-incompatible format change for any persisted or serialized :class:`CompactMask` state, including pickled objects and any external storage of ``._rles``. Older stored RLE arrays will decode incorrectly under the new convention. Migration note: load or decode legacy masks with the older version, materialize them to dense boolean arrays, and then re-encode them with the current version (for example via :meth:`to_dense` followed by :meth:`from_dense`) before persisting them again. Args: rles: List of N int32 run-length arrays. crop_shapes: Array of shape ``(N, 2)`` — ``(crop_h, crop_w)`` per mask. offsets: Array of shape ``(N, 2)`` — ``(x1, y1)`` bounding-box origins. image_shape: ``(H, W)`` of the full image. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import CompactMask >>> masks = np.zeros((2, 100, 100), dtype=bool) >>> masks[0, 10:20, 10:20] = True >>> masks[1, 50:70, 50:80] = True >>> xyxy = np.array([[10, 10, 19, 19], [50, 50, 79, 69]], dtype=np.float32) >>> cm = CompactMask.from_dense(masks, xyxy, image_shape=(100, 100)) >>> len(cm) 2 >>> cm.shape (2, 100, 100) ``` ) _crop_shapes _image_shape_offsets_rlesc<||_||_||_||_yN)rjrgrirh)selfrles crop_shapesoffsets image_shapes r__init__zCompactMask.__init__s"37 3>/6 -8rc ,|\}}t|}|dk(rQ|gtjdtjtjdtj|Sg}g}g} t |D]E} || \} } } }t t dtt | |dz }t t dtt | |dz }t t dtt | |dz }t t dtt ||dz }||ks||kr tjdt}||}}n|| ||dz||dzf}||z dz}||z dz}|jt||j||f| j||fHtj|tj}tj| tj}|||||S)atCreate a :class:`CompactMask` from a dense ``(N, H, W)`` bool array. Bounding boxes are clipped to image bounds and interpreted in the supervision ``xyxy`` convention (inclusive max coordinates). A box with invalid ordering (``x2 < x1`` or ``y2 < y1``) is replaced by a ``1x1`` all-False crop to avoid degenerate RLE. Args: masks: Dense boolean mask array of shape ``(N, H, W)``. xyxy: Bounding boxes of shape ``(N, 4)`` in ``[x1, y1, x2, y2]`` format. image_shape: ``(H, W)`` of the full image. Returns: A new :class:`CompactMask` instance. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import CompactMask >>> masks = np.zeros((1, 100, 100), dtype=bool) >>> masks[0, 10:20, 10:20] = True >>> xyxy = np.array([[10, 10, 19, 19]], dtype=np.float32) >>> cm = CompactMask.from_dense(masks, xyxy, image_shape=(100, 100)) >>> cm.shape (1, 100, 100) ``` rrr r(r r r ) rr r*rFrrr[rzerosr2rrrE)clsmasksxyxyrqimg_himg_w num_masksrncrop_shapes_list offsets_listmask_idxx1y1x2y2x1cy1cx2cy2crbrrrorps r from_densezCompactMask.from_densesH# uJ >rxx0rxx0  -/24.0 i( ,H!(^NBBc!SR%!)456Cc!SR%!)456Cc!SR%!)456Cc!SR%!)456CSyC#Ixxd3SXsS1W}cC!GmCD3Y]F3Y]F KK+D1 2  # #VV$4 5   c +' ,*hh/rxx@ ((>> import numpy as np >>> from supervision.detection.compact_mask import CompactMask >>> masks = np.zeros((1, 50, 50), dtype=bool) >>> masks[0, 10:20, 10:30] = True >>> xyxy = np.array([[10, 10, 29, 19]], dtype=np.float32) >>> cm = CompactMask.from_dense(masks, xyxy, image_shape=(50, 50)) >>> cm.to_dense().shape (1, 50, 50) ``` r(rr ) rrjrhr rvr2rrrgrir) rmr|rzr{resultrrrrrrbs rto_densezCompactMask.to_dense+s& O (( u(*)UE1JRV(Wi( HHD%%hk23D%%hk23Fx{34c$--RS :T6UB&tzz(';VVLDCGF8R"v+-rBK/?? @ H rct|j|df}t|j|df}t|j|||S)u"Decode a single mask crop without allocating the full image array. This is an O(crop_area) operation — ideal for annotators that only need the cropped region. Args: index: Index of the mask to decode. Returns: Boolean array of shape ``(crop_h, crop_w)``. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import CompactMask >>> masks = np.zeros((1, 100, 100), dtype=bool) >>> masks[0, 20:30, 10:40] = True >>> xyxy = np.array([[10, 20, 39, 29]], dtype=np.float32) >>> cm = CompactMask.from_dense(masks, xyxy, image_shape=(100, 100)) >>> cm.crop(0).shape (10, 30) ``` rr )rrgrrj)rmindexrrs rrbzCompactMask.cropKsN2T&&uax01T&&uax01"4::e#4ffEErc,t|jS)aReturn the number of masks. Returns: Number of masks N. Examples: ```pycon >>> from supervision.detection.compact_mask import CompactMask >>> import numpy as np >>> cm = CompactMask( ... [], np.empty((0, 2), dtype=np.int32), ... np.empty((0, 2), dtype=np.int32), (100, 100)) >>> len(cm) 0 ``` )rrjrms r__len__zCompactMask.__len__ls$4::rc#LKtt|D] }|| yw)z6Iterate over masks as dense ``(H, W)`` boolean arrays.N)rr)rmrs r__iter__zCompactMask.__iter__s(c$i( !Hx.  !s"$c<|j\}}t|||fS)aReturn ``(N, H, W)`` matching the dense mask convention. Returns: Tuple ``(N, H, W)``. Examples: ```pycon >>> from supervision.detection.compact_mask import CompactMask >>> import numpy as np >>> cm = CompactMask( ... [], np.empty((0, 2), dtype=np.int32), ... np.empty((0, 2), dtype=np.int32), (480, 640)) >>> cm.shape (0, 480, 640) ``` )rhr)rmrzr{s rshapezCompactMask.shapes$&(( uD 5%((rc|jS)akReturn per-mask crop origins as ``(x1, y1)`` integer offsets. Returns: Array of shape ``(N, 2)`` with ``int32`` offsets. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import CompactMask >>> masks = np.zeros((1, 10, 10), dtype=bool) >>> masks[0, 2:4, 3:5] = True >>> xyxy = np.array([[3, 2, 4, 3]], dtype=np.float32) >>> cm = CompactMask.from_dense(masks, xyxy, image_shape=(10, 10)) >>> cm.offsets.tolist() [[3, 2]] ``` )rirs rrpzCompactMask.offsetss(}}rct|dk(r%tjdtjS|jdddf}|jdddf}||j dddfzdz }||j dddfzdz }tj ||||fjtjdS)aReturn per-mask inclusive bounding boxes in ``xyxy`` format. Boxes are derived from crop metadata: ``x2 = x1 + crop_w - 1``, ``y2 = y1 + crop_h - 1``. Returns: Array of shape ``(N, 4)`` with ``int32`` boxes ``[x1, y1, x2, y2]``. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import CompactMask >>> masks = np.zeros((1, 10, 10), dtype=bool) >>> masks[0, 2:5, 3:7] = True >>> xyxy = np.array([[3, 2, 6, 4]], dtype=np.float32) >>> cm = CompactMask.from_dense(masks, xyxy, image_shape=(10, 10)) >>> cm.bbox_xyxy.tolist() [[3, 2, 6, 4]] ``` r)rr(Nr F)copy)rr r*rFrirg column_stackrN)rmrrrrs r bbox_xyxyzCompactMask.bbox_xyxys0 t9>88F"((3 3$(MM!Q$$7$(MM!Q$$7$&):):1a4)@$@1$D$&):):1a4)@$@1$DBB/077u7MMrc4tjtS)uReturn ``np.dtype(bool)`` — always. Returns: ``np.dtype(bool)``. Examples: ```pycon >>> from supervision.detection.compact_mask import CompactMask >>> import numpy as np >>> cm = CompactMask( ... [], np.empty((0, 2), dtype=np.int32), ... np.empty((0, 2), dtype=np.int32), (100, 100)) >>> cm.dtype dtype('bool') ``` )r r)r2rs rr)zCompactMask.dtypes&xx~rctj|jDcgc] }t|c}tjScc}w)aCompute the area (``True`` pixel count) of each mask. Returns: int64 array of shape ``(N,)`` with per-mask pixel counts. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import CompactMask >>> masks = np.zeros((2, 100, 100), dtype=bool) >>> masks[0, 0:10, 0:10] = True # 100 pixels >>> masks[1, 0:5, 0:5] = True # 25 pixels >>> xyxy = np.array([[0, 0, 9, 9], [0, 0, 4, 4]], dtype=np.float32) >>> cm = CompactMask.from_dense(masks, xyxy, image_shape=(100, 100)) >>> cm.area.tolist() [100, 25] ``` r()r rErjrr0)rmrs rareazCompactMask.areas/*xx4::>C3>bhhOO>sANcd|dk(r |jS|jj|S)a"NumPy-compatible sum with a fast path for per-mask area. When ``axis=(1, 2)``, returns the per-mask True-pixel count via :attr:`area` without materialising the full dense array. Args: axis: Axis or axes to sum over. Returns: Sum result matching NumPy semantics. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import CompactMask >>> masks = np.zeros((1, 10, 10), dtype=bool) >>> masks[0, 0:3, 0:3] = True >>> xyxy = np.array([[0, 0, 2, 2]], dtype=np.float32) >>> cm = CompactMask.from_dense(masks, xyxy, image_shape=(10, 10)) >>> cm.sum(axis=(1, 2)).tolist() [9] ``` )r r axis)rrr )rmrs rr zCompactMask.sums/2 6>99 }}"""--rct|ttjfrt|}|j\}}tj ||ft }t|j|df}t|j|df}t|j|df}t|j|df} t|j|||} | || | |z|||zf<|St|tr?t|j||j||j||jSt|tjr,|jt k(rtj|d} nt|t rAt#d|Dr/tj$tj&|t } n.tj&t!|tj(} | D cgc]} |jt| } } |j| }|j| }t| |||jScc} w)u8Index into the mask collection. * ``int`` → dense ``(H, W)`` bool array (for annotators, iterators). * ``slice | list | ndarray`` → new :class:`CompactMask` (for filtering). Args: index: An integer returns a dense ``(H, W)`` mask. Any other supported index type returns a new :class:`CompactMask`. Returns: Dense ``(H, W)`` ``np.ndarray`` for integer index, or a new :class:`CompactMask` for all other index types. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import CompactMask >>> masks = np.zeros((3, 20, 20), dtype=bool) >>> xyxy = np.array( ... [[0,0,5,5],[5,5,10,10],[10,10,15,15]], dtype=np.float32) >>> cm = CompactMask.from_dense(masks, xyxy, image_shape=(20, 20)) >>> cm[0].shape # int → dense (H, W) (20, 20) >>> len(cm[[0, 2]]) # list → CompactMask 2 ``` r(rr c3\K|]$}t|ttjf&ywrl) isinstancer2r r+).0items r z*CompactMask.__getitem__..Ss%- 37JtdBHH- .- s*,)rrr integerrhrvr2rgrirrjslicerfndarrayr)wherelistallr.asarrayintp)rmridxrzr{rrrrrrbidx_arrrnew_rlesnew_crop_shapes new_offsetss r __getitem__zCompactMask.__getitem__s@ ec2::. /e*C,,LE5,.HHeU^4,PF**3623F**3623FT]]36*+BT]]36*+B&tzz#GD9=F2V #R"v+%55 6M eU # 5!!!%( e$!!   eRZZ (U[[D-@hhuoa(G t $- ;@- * nnRZZT%BCGjjeBGGEF(DJJs8}-FF151B1B71K-1]]7-C 8_k4CTCTUUGsIcL|j}||j|S|S)aNumPy interop: materialise as a dense ``(N, H, W)`` array. Called by ``np.asarray(compact_mask)`` and similar NumPy functions. Args: dtype: Optional dtype to cast the result to. Returns: Dense boolean array of shape ``(N, H, W)``. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import CompactMask >>> masks = np.zeros((1, 10, 10), dtype=bool) >>> xyxy = np.array([[0, 0, 5, 5]], dtype=np.float32) >>> cm = CompactMask.from_dense(masks, xyxy, image_shape=(10, 10)) >>> np.asarray(cm).shape (1, 10, 10) ``` )rrN)rmr)rs r __array__zCompactMask.__array___s).  ==' ' rc2t|tr;ttj|j |j St|tj r-ttj|j |StS)aElement-wise equality with another :class:`CompactMask` or ndarray. Args: other: Another :class:`CompactMask` or ``np.ndarray``. Returns: ``True`` if all masks are pixel-identical. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import CompactMask >>> masks = np.zeros((1, 10, 10), dtype=bool) >>> xyxy = np.array([[0, 0, 5, 5]], dtype=np.float32) >>> cm1 = CompactMask.from_dense(masks, xyxy, image_shape=(10, 10)) >>> cm2 = CompactMask.from_dense(masks, xyxy, image_shape=(10, 10)) >>> cm1 == cm2 True ``` )rrfr2r array_equalrrNotImplemented)rmothers r__eq__zCompactMask.__eq__{sa, e[ )t}}8HIJ J eRZZ (t}}>? ?rc|s td|dj}|ddD],}|j|k7std|d|jg}|D]}|j|jt j |Dcgc]}|j c}d}t j |Dcgc]}|jc}d}t||||Scc}wcc}w)afConcatenate multiple :class:`CompactMask` objects into one. All inputs must have the same ``image_shape``. Args: masks_list: Non-empty list of :class:`CompactMask` objects. Returns: A new :class:`CompactMask` containing every mask from the inputs, in order. Raises: ValueError: If ``masks_list`` is empty or image shapes differ. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import CompactMask >>> masks1 = np.zeros((2, 50, 50), dtype=bool) >>> masks2 = np.zeros((3, 50, 50), dtype=bool) >>> xyxy1 = np.array([[0,0,10,10],[10,10,20,20]], dtype=np.float32) >>> xyxy2 = np.array( ... [[0,0,5,5],[5,5,10,10],[10,10,15,15]], dtype=np.float32) >>> cm1 = CompactMask.from_dense(masks1, xyxy1, image_shape=(50, 50)) >>> cm2 = CompactMask.from_dense(masks2, xyxy2, image_shape=(50, 50)) >>> len(CompactMask.merge([cm1, cm2])) 5 ``` z2Cannot merge an empty list of CompactMask objects.rr Nz>Cannot merge CompactMask objects with different image shapes: z vs r) ValueErrorrhrDrjr concatenatergrirf) masks_listrqcmrrrs rmergezCompactMask.merges@QR R m00 QR. B+- T"m4'8: 13 &B OOBHH % & 24'1 2R__ 22 .0^^#- .RR[[ .Q. 8_k;OO 3 /s C!7C&c *t|j}|dk(r^tgtjdtj tjdtj |j Sg}g}g}t|D]}|j|}t|j|df}t|j|df}tj|d} tj|d} | jsX|jttjdt|jd|j||ftj | d} tj | d} t| dt| d}} t| dt| d}}|| |dz||dzf}|jt||j|| z dz||z dzf|j||z|| zft|tj"|tj tj"|tj |j S)uRe-encode all masks using tight bounding boxes. When the original ``xyxy`` boxes are padded or loose — common with object-detector outputs and full-image boxes used in tests — each RLE crop encodes more background (``False``) pixels than necessary. This method decodes every crop, trims it to the minimal rectangle that contains all ``True`` pixels, and re-encodes. All-``False`` masks are normalised to a ``1x1`` all-``False`` crop. The call is O(sum of crop areas) — suitable as a one-time cleanup after accumulating many merges (e.g. after :class:`~supervision.detection.tools.inference_slicer.InferenceSlicer` tiles are merged). Returns: A new :class:`CompactMask` with minimal-area crops and updated offsets. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import CompactMask >>> masks = np.zeros((1, 10, 10), dtype=bool) >>> masks[0, 3:7, 3:7] = True >>> # Deliberately loose bbox: covers the full image. >>> xyxy = np.array([[0, 0, 9, 9]], dtype=np.float32) >>> cm = CompactMask.from_dense(masks, xyxy, image_shape=(10, 10)) >>> repacked = cm.repack() >>> repacked.offsets.tolist() # tight origin: x1=3, y1=3 [[3, 3]] ``` rrtr(r rrur)rrjrfr r*rFrhrrbrrianyrrrvr2rrE)rmr|rnew_crop_shapes_listnew_offsets_listrrbx1_offy1_offrows_anycols_any y_indices x_indicesy_miny_maxx_minx_maxtights rrepackzCompactMask.repacks5D O >rxx0rxx0!!  136824i( FH99X&Dx{34Fx{34Fvvd+Hvvd+H<<> 3BHHV44P QR$++F3 ''(89*1-I*1-Iy|,c)B-.@5Ey|,c)B-.@5E*EEAI,==>E OO/6 7 ' '):EEMA>> import numpy as np >>> from supervision.detection.compact_mask import CompactMask >>> masks = np.zeros((1, 20, 20), dtype=bool) >>> xyxy = np.array([[5, 5, 15, 15]], dtype=np.float32) >>> cm = CompactMask.from_dense(masks, xyxy, image_shape=(20, 20)) >>> cm2 = cm.with_offset(100, 200, new_image_shape=(400, 400)) >>> cm2.offsets[0].tolist() [105, 205] ``` r0new_image_shape must contain positive dimensionsrtr(Nr ru)rrrfr r*rFrirErgrrrjrrrrr[rrrvr2rb)rmdxdynew_image_shaper`rar|rx1sy1sx2sy2s needs_clipout_rlesout_crop_shapesout_offsets_listrrrrrix1iy1ix2iy2anchor_xanchor_yrbclippeds r with_offsetzCompactMask.with_offset+sF' u A:!OP PI >rxx0rxx0  .2]]RXX HBHH> . !Q$!Q$D%%ad++a/D%%ad++a/1Wq !SE\ 2cUl C ~~TZZ !!&&(  131324i(" 0HS]#BS]#BS]#BS]#Bh' 8 45&&D--hk:;D--hk:; !''R1a*Ca*Ceai$Ceai$CSyC#Is2qz5195s2qz5195 3BHHV44P QR&&v. ''8(<=99X&D38cBhl2C"HsRx!|4KKLG OO/8 9  " "C#IM39q=#A B  # #S#J /E" 0H  HH_BHH 5 HH%RXX 6    rc  ddlm}|\}}|dks|dkr td||f|jk(rQt t |j |jj|jj|St|dk(rTt gtjdtjtjdtj|S|j\}}||z }||z }|jdddfjtj} |jdddfjtj} | |jdddfzdz } | |jdddfzdz } tj tj"| |zd|dz jtj} tj tj"| |zd|dz jtj}tj tj"| |zd|dz jtj}tj tj"| |zd|dz jtj}tj$d|| z dzjtj}tj$d||z dzjtj}|jdddf}|jdddf}t't|Dcgc]F}|j |t)||t)||t)||t)||fH}}t|}|t*k\rO|t-|t/j0xsd 5}t |j3d |}dddn|Dcgc] }t5| }}tj6||fjtj}tj6| |fjtj}t |||Scc}w#1swYxYwcc}w) u4Return a new CompactMask scaled to a different image resolution. Each crop mask is resized with nearest-neighbour interpolation. Sparse masks use direct RLE arithmetic (:func:`_rle_resize`); dense masks fall back to ``cv2.resize(INTER_NEAREST)``. Offsets and crop dimensions are scaled proportionally to the new image size. Performance notes: * Coordinate arithmetic is fully vectorised (no Python loop over N). * All-``False`` crops skip decode/resize entirely. * For N >= 8, resize runs in a thread pool — NumPy and OpenCV release the GIL so crops execute in parallel on multi-core CPUs. Args: new_image_shape: ``(H, W)`` of the target image. Returns: New :class:`CompactMask` with updated ``image_shape``, scaled offsets, scaled crop shapes, and re-encoded RLE crops. Raises: ValueError: If any dimension in *new_image_shape* is ``<= 0``. Examples: ```pycon >>> import numpy as np >>> from supervision.detection.compact_mask import CompactMask >>> masks = np.zeros((1, 100, 100), dtype=bool) >>> masks[0, 20:40, 30:60] = True >>> xyxy = np.array([[30, 20, 59, 39]], dtype=np.float32) >>> cm = CompactMask.from_dense(masks, xyxy, image_shape=(100, 100)) >>> small = cm.resize((50, 50)) >>> small.shape (1, 50, 50) >>> small.offsets[0].tolist() [15, 10] ``` r)ThreadPoolExecutorrrtr(Nr r) max_workersct|Srl)rd)as rz$CompactMask.resize..s |Q'7r)concurrent.futuresrrrhrfrrjrgrrirr r*rFrNfloat64cliproundmaximumrrrWros cpu_countmaprdr)rmrrr`rarzr{sxsyrrrrnew_x1snew_y1snew_x2snew_y2s new_crop_ws new_crop_hs orig_crop_hs orig_crop_wsiargsnpoolrrrrs rr\zCompactMask.resizesR :& u A:!OP P 5>T.. .TZZ !!&&( ""$   t9>rxx0rxx0  (( u U] U]mmAqD!((4mmAqD!((4D%%ad++a/D%%ad++a/''"((38,a;BB288L''"((38,a;BB288L''"((38,a;BB288L''"((38,a;BB288L-/ZZ w 1$. &  .0ZZ w 1$. &   ((A. ((A. 3t9%    1 LO$LO$KN#KN#       I # ##Ar||~7J0KL PT8<HH7>9   377Q a(7H7//; *DELLRXXVoow&89@@J 8_k?SS-     8s2A R-<R2&R>2R;) rnzlist[npt.NDArray[np.int32]]ronpt.NDArray[np.int32]rprrqtuple[int, int]returnNone)rxnpt.NDArray[np.bool_]rynpt.NDArray[Any]rqrrrf)rr)rrrr)rr)rzIterator[npt.NDArray[np.bool_]])rztuple[int, int, int])rr)rz np.dtype[Any])rznpt.NDArray[np.int64]rl)rzint | tuple[int, ...] | Nonerznpt.NDArray[Any] | int)rz*int | slice | list[Any] | npt.NDArray[Any]rz#npt.NDArray[np.bool_] | CompactMask)r)znp.dtype[Any] | Nonerr)robjectrr2)rzlist[CompactMask]rrf)rrf)rrrrrrrrf)rrrrf)__name__ __module__ __qualname____doc__ __slots__rr classmethodrrrbrrpropertyrrprr)rr rrr staticmethodrrrr\rrrfrfsAFFI 9) 9+ 9' 9 % 9  9 I<$I<I<% I<  I<I<^@FB(! ))**NN@(PP,.:BV9BV -BVH8@:P:PxM fw w  w ) w  w zrTrrf)rrrr)rrrrrrrlist[list[int]])r4 list[int]r5rr6rrr)rGrrHrrr) rrrrrrr7rrOrrr) rrr^rr_rr`rrarrr)r  __future__rrcollections.abcrtypingrnumpyr numpy.typingnpt&supervision.detection.utils.convertersrrrr&rBrKrSrU__annotations__rWrdrfrrrrsN # $ ",L L L L L^>> >#> >B5Q 5Q5Q5QpQ2 Q2 Q2 Q2 Q2  Q2  Q2n $u#S-( -( -( -(  -(  -(  -(`UTUTr