Types¶

from boxlab.dataset.types import BBox

# Create in XYXY (internal format)
bbox = BBox(x_min=10, y_min=20, x_max=100, y_max=150)

# Convert to other formats
xyxy = bbox.xyxy  # (10, 20, 100, 150)
xywh = bbox.xywh  # (10, 20, 90, 130)
cxcywh = bbox.cxcywh  # (55.0, 85.0, 90, 130)

# Create from other formats
bbox1 = BBox.from_xywh(x=10, y=20, w=90, h=130)
bbox2 = BBox.from_cxcywh(cx=55, cy=85, w=90, h=130)

# All represent the same box
assert bbox == bbox1 == bbox2

from boxlab.dataset.types import BBox, Annotation

# Complete annotation
annotation = Annotation(
    bbox=BBox(10, 20, 100, 150),
    category_id=1,
    category_name="person",
    image_id="img_001",
    annotation_id="ann_001",
    area=11700.0,
    iscrowd=0
)

# Minimal annotation (area computed automatically)
annotation = Annotation(
    bbox=BBox(10, 20, 100, 150),
    category_id=1,
    category_name="person",
    image_id="img_001"
)

from pathlib import Path
from boxlab.dataset.types import ImageInfo

# With file path
img_info = ImageInfo(
    image_id="001",
    file_name="photo.jpg",
    width=1920,
    height=1080,
    path=Path("/data/images/photo.jpg")
)

# Without path (for annotations-only export)
img_info = ImageInfo(
    image_id="001",
    file_name="photo.jpg",
    width=1920,
    height=1080
)

from boxlab.dataset.types import SplitRatio

# Standard split
split = SplitRatio(train=0.7, val=0.2, test=0.1)
split.validate()

# No test set
split = SplitRatio(train=0.8, val=0.2, test=0.0)
split.validate()

# Use with dataset
splits = dataset.split(split, seed=42)

from boxlab.dataset import Dataset

dataset = Dataset(name="my_dataset")
# ... populate dataset ...

stats = dataset.get_statistics()

# Access statistics
print(f"Total images: {stats['num_images']}")
print(f"Total annotations: {stats['num_annotations']}")

# Category analysis
dist = stats['category_distribution']
most_common = max(dist.items(), key=lambda x: x[1])
print(f"Most common: {most_common[0]} ({most_common[1]} instances)")

# Annotation density
avg = stats['avg_annotations_per_image']
std = stats['std_annotations_per_image']
print(f"Objects per image: {avg:.2f} ± {std:.2f}")

# Box size analysis
print(f"Average box area: {stats['avg_bbox_area']:.2f}")
print(f"Median box area: {stats['median_bbox_area']:.2f}")

# For a 1920x1080 image
bbox = BBox(x_min=100, y_min=200, x_max=300, y_max=400)

# Width and height in pixels
width = bbox.x_max - bbox.x_min  # 200 pixels
height = bbox.y_max - bbox.y_min  # 200 pixels

# Image dimensions
img_width, img_height = 1920, 1080

# Absolute bbox
bbox = BBox(100, 200, 300, 400)

# Normalize
cx, cy, w, h = bbox.cxcywh
cx_norm = cx / img_width  # 0.104
cy_norm = cy / img_height  # 0.278
w_norm = w / img_width  # 0.104
h_norm = h / img_height  # 0.185

bbox = BBox(10, 20, 100, 150)

# This raises an error
# bbox.x_min = 15  # AttributeError

# Create a new bbox instead
new_bbox = BBox(15, 20, 100, 150)

from boxlab.dataset.types import BBox, Annotation, ImageInfo


def process_bbox(bbox: BBox) -> float:
    return bbox.area


def create_annotation(
    bbox: BBox,
    category_id: int,
    category_name: str,
    image_id: str
) -> Annotation:
    return Annotation(
        bbox=bbox,
        category_id=category_id,
        category_name=category_name,
        image_id=image_id
    )

from boxlab.dataset.types import SplitRatio
from boxlab.exceptions import ValidationError

# Valid split
split = SplitRatio(0.7, 0.2, 0.1)
split.validate()  # OK

# Invalid split
try:
    split = SplitRatio(0.5, 0.3, 0.1)  # Sums to 0.9
    split.validate()
except ValidationError as e:
    print(f"Error: {e}")

def validate_bbox(bbox: BBox, img_width: int, img_height: int) -> bool:
    """Check if bbox is within image bounds."""
    return (
        0 <= bbox.x_min < bbox.x_max <= img_width and
        0 <= bbox.y_min < bbox.y_max <= img_height
    )


bbox = BBox(10, 20, 100, 150)
is_valid = validate_bbox(bbox, 1920, 1080)  # True