supervision-js
    Preparing search index...

    Oriented Box

    The oriented-box annotation renderer draws one explicit quadrilateral per detection from Detection.orientedBox. BaseOrientedBoxStyle controls its fill, stroke, and visibility independently from boxes, masks, or polygons on the same detection.

    session.setPresentation({
    renderers: [
    annotationRenderers.orientedBox({
    style: new BaseOrientedBoxStyle({
    fill: { alpha: 0.16 },
    stroke: { width: 3 },
    }),
    }),
    ],
    });

    Detection.orientedBox carries four explicit media-pixel vertices, ordered clockwise starting from the box's own top-left corner (its top-left before any rotation was applied):

    detection.orientedBox = {
    points: [
    { x: topLeftX, y: topLeftY },
    { x: topRightX, y: topRightY },
    { x: bottomRightX, y: bottomRightY },
    { x: bottomLeftX, y: bottomLeftY },
    ],
    };

    This is a separate field from rect. Rect stays axis-aligned and center-based; it never gains a rotation field, and this renderer never reinterprets an axis-aligned rect as rotatable. A detection may carry both a rect (or mask/polygon) and an orientedBox at the same time, for example when a host wants an axis-aligned box and a separately computed rotated minimum-area box for the same object.

    createOrientedBoxGeometry() from supervision/editing constructs ordered rectangle corners from a center-based Rect and a clockwise angle in radians. It does not fit a rectangle to a mask, polygon or arbitrary quadrilateral. Detectors that emit corners can supply detection.orientedBox directly. Frame validation requires exactly four points with finite coordinates. Producers must supply a convex quadrilateral in clockwise perimeter order. BaseOrientedBoxStyle also skips zero-area geometry; it does not repair invalid vertex ordering.

    The renderer reuses the existing closed-path fill and stroke drawing that polygons use; it does not introduce a second rasterization path. The renderer only controls presentation. An editable session can select and move the whole detection, translating its OBB vertices along with its other geometry. OBB creation, rotation and local-axis resizing are available through the editing entrypoint for OBB-only rectangles, including rounding noise within the recognition precision described below. Quadrilaterals outside that precision retain whole-shape movement without rectangle handles. If the detection also has an editable rect, its existing resize handles change only that independent rectangle. Both geometries remain visible in the editing preview.

    getOrientedRectangleGeometry() recovers a rectangle from convex, clockwise corners, including coordinates rounded to 0.1 media pixels. It uses the closest rectangle with the supplied corner correspondence, preserving local width, height, and front direction without sorting the axes. The total squared corner error must stay within 0.02 media pixels squared, the error budget for rounding eight coordinates to 0.1 pixels, plus floating-point roundoff. More distorted quadrilaterals return null and retain whole-shape movement.

    Recognition leaves the input untouched. Rendering, picking, and whole-shape movement use the original corners; an actual resize or rotation replaces the subpixel rounding noise with exact rectangle corners. Selecting or clicking a handle alone does not change the geometry.

    import {
    AnnotationGeometryKind,
    createAnnotationEditingEngine,
    createOrientedBoxGeometry,
    getOrientedRectangleGeometry,
    } from "supervision/editing";

    const box = createOrientedBoxGeometry(
    { x: 200, y: 120, width: 80, height: 40 }, // x/y are the center
    Math.PI / 4, // clockwise radians in image coordinates
    );
    const rectangle = getOrientedRectangleGeometry(box);
    // { x, y, width, height, rotation }, or null outside rectangle precision.

    const engine = createAnnotationEditingEngine({
    onCommit(detection, previous) {
    // Persist one previous/next pair in the host undo history.
    },
    });
    engine.setCreationTool({
    geometry: AnnotationGeometryKind.OrientedBox,
    createDetection(points) {
    return { orientedBox: { points: points as typeof box.points } };
    },
    });

    Pass the caller-owned engine as renderer.editingEngine to a media session. Drag creation supplies four clockwise local corners to createDetection and shouldCommit. The footprint is axis-aligned, with local +x following the dominant drag direction: right, left, down or up. Vertical drags exchange the footprint's width and height in the ordered local geometry; square drags use the horizontal direction. It needs no accompanying rect. The selected rectangle has eight local-axis resize controls and a compact rotation control on a short stem. Handle rendering and hit testing share engine.getHandles(): the rotation glyph has a 4 CSS-pixel radius and a separate circular 20 CSS-pixel hit diameter; by default, its center sits 24 CSS pixels outside the first edge. Sizes stay constant while zooming.

    Rotation uses the center and the initial press angle, preserving pointer grab offset. Resizing fixes the opposite edge or corner and continues through it when the pointer crosses, retaining a positive one-pixel minimum extent. Rotation and resizing preserve the ordered local axes, including squares and half/full turns. Crossing changes which corner or edge follows the pointer without turning the rectangle or swapping its local width and height. The returned angle may wrap at pi.

    Creation is bounded by supplied media dimensions. Rotation and local-axis resize may extend beyond the image and never clip or refit a rectangle; hosts choose their own admission policy. Escape, tool changes and pointer interruption discard continuous edits. A completed edit emits one onCommit, with its original detection for host-owned undo. Rotation reports AnnotationGestureStateKind.Rotating.

    Rotation is free by default. Hosts can constrain the candidate angle with resolveRotation, for example to snap to 15-degree increments while Shift is held:

    const step = Math.PI / 12;
    const engine = createAnnotationEditingEngine({
    resolveRotation(radians, { detection, initialRotation, input }) {
    return input.shiftKey ? Math.round(radians / step) * step : radians;
    },
    // Ordered edges: 0 top, 1 right, 2 bottom, 3 left.
    rotationHandle: { edgeIndex: 1, offset: 32, stemOffset: 20 },
    onCommit(detection, previous) {
    // Persist the result and record the previous detection for undo.
    },
    });

    The resolver receives an absolute clockwise angle in radians, the original detection, its initial rotation, and the latest pointer input with modifiers. Each preview and commit is resolved once from the original geometry and raw pointer position; previous constrained previews never accumulate into the next candidate. Return finite radians. The engine normalizes the result to the geometry helper's [-PI, PI] convention and preserves the original center, ordered width/height, corner identities, id and metadata. The resolver applies only to rotation; it does not constrain movement, resizing or creation.

    rotationHandle can also be (detection) => ({ edgeIndex, offset, stemOffset }) for annotation-specific placement. The default is edge 0 with a 24 CSS-pixel outward offset; offset must be finite and nonnegative. Placement changes only the control and its stem. It does not change corner ordering or infer a heading. stemOffset starts the visible stem that many CSS pixels outward from the edge, leaving space for a host's marker without moving the control or its hit area. It defaults to 0 and must be finite, nonnegative, and no greater than offset.

    The browser renderer routes modifier press and release events during rotation, so Shift snapping updates immediately while the pointer is stationary. Hosts routing input directly can call engine.setModifiers({ shiftKey: true }) and engine.setModifiers({}) on release. Omitted modifier keys are released. This updates only an active rotation that has already crossed the drag threshold; it neither starts movement nor commits. The final pointerUp(input) modifier snapshot is authoritative. Window blur interrupts the active contact.

    Use engine.getHandles(detection, viewportScale) when drawing or picking controls yourself. The scale is CSS pixels per media pixel; omit it to use the engine's viewportScale callback (or 1). The pure helper remains backward compatible and accepts the same placement configuration as a third argument: getAnnotationHandles(detection, viewportScale, { rotationHandle }). getHandles and setModifiers remain optional on the published AnnotationEditingEngine and BuiltInAnnotationEditingEngine interfaces. The factory returns the narrower ConfiguredAnnotationEditingEngine, which guarantees both methods. Adapters fall back to the default pure helper for older engines.

    Run the self-contained vanilla editing example with npm run example:vanilla:dev and open /examples/vanilla/oriented-box.html. It demonstrates creation, rotation, resize, zoom, cancellation and undo/redo using the public package.

    The playground's basketball fixture pairs its real SAM3-derived basketball detections with a hand-authored oriented box: a fixed rotation of the already-committed ball rectangle, applied once when the fixture was prepared, not produced by any oriented-box model. See Detections And Rendering for the complete detection geometry contract.