`pipelogic.cv`

Domain wrappers for the typed values that flow between Pipelogic components.

from pipelogic.cv import (
    Image, ColorSpace,
    Tensor, AudioFrame,
    Point, Rectangle, Ellipse, Polygon, Mask,
    DetectedClass, BoundingBox, Landmark,
    rect_iou,
)

Every wrapper has the same dual-init pattern:

From numpy / values when you're producing output: Image(arr, ColorSpace.BGR), BoundingBox.from_xyxy(...).
From a backend value when you receive input: pass the worker's argument directly to the constructor.

Returning a wrapper from run(worker_function) serializes it for you. You never assemble objects by hand.

`Image`

Pipelang shape Image := {width: UInt64, height: UInt64, format: ..., data: Bytes}.

Constructor

Image(source, color_space=None)

Name
source
Type
np.ndarray | Image input
Description
A (H, W), (H, W, 3), or (H, W, 4) ndarray, or an incoming Image value from a backend input.
Name
color_space
Type
ColorSpace
Description
Required when source is an ndarray. One of ColorSpace.BGR, BGRA, GRAY, RGB, RGBA. Inferred automatically when source is a backend value.

Properties

width, height, color_space, channels, shape, empty.

Methods

Name
numpy()
Type
np.ndarray
Description
Raw pixel data in the current color space. Zero-copy from the backend buffer on first call.
Name
to_bgr()
Type
np.ndarray (H, W, 3) uint8
Description
Convert to BGR. Returns a new array; does not mutate the wrapper.
Name
to_rgb()
Type
np.ndarray (H, W, 3) uint8
Description
Convert to RGB.
Name
to_gray()
Type
np.ndarray (H, W) uint8
Description
Convert to grayscale.
Name
convert(color_space)
Type
None
Description
In-place color-space conversion.
Name
resize((h, w), interpolation=cv2.INTER_LINEAR)
Type
None
Description
In-place resize. Note the order — height first, then width.
Name
resize_max_side(max_side, interpolation=cv2.INTER_AREA)
Type
None
Description
Scale so the longest side is at most max_side. No-op when already small enough.
Name
crop(x1, y1, x2, y2)
Type
None
Description
In-place crop to the rectangle [y1:y2, x1:x2].
Name
clone()
Type
Image
Description
Deep copy.

Constants

from pipelogic.cv import (
    IMAGE_BGR, IMAGE_BGRA, IMAGE_GRAY, IMAGE_RGB, IMAGE_RGBA,   # variant tags
    IMAGE_TYPE,                                                  # Image named type
    IMAGE_UNION,                                                 # union of variants
    BGR_FORMAT, BGRA_FORMAT, GRAY_FORMAT, RGB_FORMAT, RGBA_FORMAT,
)

These are the type handles you reference when declaring component I/O in component.yml. The runtime resolves Image automatically — these are mostly for introspection.

`Tensor`

Pipelang shape Tensor := {shape: [Int64], data: [Float]}. The Python wrapper is float32-only.

Constructor

Tensor(source)

source is either a numpy array (any shape, any dtype — coerced to float32) or an incoming Tensor value from a backend input.

Properties

shape (tuple of int), ndim (int).

Methods

Name
numpy()
Type
np.ndarray (shape) float32
Description
Shaped view; zero-copy from the backend buffer on first call.
Name
flat_numpy()
Type
np.ndarray (N,) float32
Description
Flat view of the data buffer.

from pipelogic.cv import TENSOR_TYPE

TENSOR_TYPE is the named-type handle.

`AudioFrame`

Pipelang shape AudioFrame := {sample_rate: UInt64, data: Tensor}. Audio is stored as (samples, channels) float32.

Constructor

AudioFrame(source, sample_rate=None)

Name
source
Type
np.ndarray | AudioFrame input
Description
A (samples,) or (samples, channels) ndarray (any dtype, coerced to float32) — or an incoming AudioFrame value from a backend input.
Name
sample_rate
Type
int
Description
Required when source is an ndarray.

Properties

sample_rate (int), num_samples (int), num_channels (int), shape, empty (bool).

Methods

Name
numpy()
Type
np.ndarray (samples, channels) float32
Description
Name
mono()
Type
np.ndarray (samples,) float32
Description
Multi-channel input is averaged across channels.
Name
flat_numpy()
Type
np.ndarray (N,) float32
Description

from pipelogic.cv import AUDIO_FRAME_TYPE

Geometry

`Point`

Point(x, y)             # from values
Point(input_point)      # from a backend input

Properties: x, y (mutable). Methods: to_tuple(), to_int_tuple(), __iter__.

`Rectangle`

Rectangle(top_left, bottom_right)            # two Points or coordinate pairs
Rectangle(pipe_rect)
Rectangle.from_xyxy(x1, y1, x2, y2)          # convenience

Properties: top_left, bottom_right, width, height, area. Methods: to_xyxy(), to_int_xyxy(), to_tlbr().

`DetectedClass`

DetectedClass(class_id, confidence)
DetectedClass(pipe_cls)

Properties: id, confidence (mutable).

`BoundingBox`

BoundingBox(rectangle, detected_class)
BoundingBox(pipe_bbox)
BoundingBox.from_xyxy(x1, y1, x2, y2, class_id, confidence)

Properties: rectangle, detected_class. Methods: to_xyxy(), to_int_xyxy().

`Landmark`

Landmark(point, confidence)
Landmark(pipe_landmark)
Landmark.from_xy(x, y, confidence)

Properties: point, confidence. Methods: to_xy().

`Ellipse`

Ellipse(center, rx, ry)
Ellipse(pipe_ellipse)

Properties: center, rx, ry.

`Polygon`

Polygon([(x, y), (x, y), ...])
Polygon([Point, Point, ...])
Polygon(np_array_N_2)
Polygon(pipe_polygon)

Properties: points, num_points. Methods: numpy() (returns (N, 2) float64). Iterable and indexable.

`Mask`

A boolean tensor used for segmentation masks.

Mask(np.zeros((480, 640), dtype=bool))
Mask(pipe_mask)

Properties: shape, height, width. Methods: numpy() returns a shaped bool ndarray.

Free functions

Name
rect_iou(a, b)
Type
float
Description
Intersection over union of two Rectangle instances. Returns 0.0 when the union is empty.

Named-type constants

For declaring custom types or for component.yml-side type expressions:

from pipelogic.cv import (
    POINT_TYPE, RECTANGLE_TYPE, ELLIPSE_TYPE, DETECTED_CLASS_TYPE,
    BOUNDING_BOX_TYPE, LANDMARK_TYPE, POLYGON_TYPE, MASK_TYPE,
    TENSOR_TYPE, AUDIO_FRAME_TYPE, IMAGE_TYPE,
)

What's next

Recipes — bbox drawer, mono mix, batched inference, segmentation overlay.
API: infer — load models from HuggingFace and pick the right device.
Footguns — color-space gotchas, sample-rate mismatches, mask boolean conventions.