spacial 0.1.0__py3-none-any.whl

spacial/__init__.py

@@ -0,0 +1,669 @@
+"""
+Spacial — lightweight synthetic dataset image generation library.
+
+Spacial generates images and their annotations (bounding boxes, segmentation)
+using Pillow. It is intentionally minimal: no export formats, no training
+framework, no scene graph. Just pixels and coordinates.
+
+Typical usage
+-------------
+    import spacial
+
+    spacial.init(w=640, h=480)
+    spacial.background("color", fill=(30, 30, 30))
+
+    spacial.shape("badge", w=80, h=80)
+    spacial.shape_add("badge", "circle", fill="#FF4500", cx=40, cy=40, r=38)
+
+    spacial.append("logo_01", "badge", x=50, y=50)
+    spacial.append("logo_02", "badge", x=200, y=50)
+
+    print(spacial.bbox())
+    spacial.save("output.png")
+    spacial.rm()
+"""
+
+from __future__ import annotations
+
+import math
+import random
+from typing import Any
+
+from PIL import Image, ImageDraw
+
+# ---------------------------------------------------------------------------
+# Version
+# ---------------------------------------------------------------------------
+
+__version__ = "0.1.0"
+__all__ = [
+    "init",
+    "background",
+    "shape",
+    "shape_add",
+    "append",
+    "bbox",
+    "seg",
+    "save",
+    "rm",
+]
+
+# ---------------------------------------------------------------------------
+# Internal state
+# A single global state object keeps the public API flat and import-friendly.
+# ---------------------------------------------------------------------------
+
+_SUPPORTED_DEVICES = {"cpu", "cuda", "mps"}
+_SUPPORTED_BG_TYPES = {"color", "gradient", "noise", "perlin", "img"}
+_SUPPORTED_SHAPE_PRIMITIVES = {"circle", "rectangle", "img"}
+
+
+class _State:
+    """Holds all mutable state for the current canvas."""
+
+    def __init__(self) -> None:
+        self.device: str = "cpu"
+        self.width: int = 1024
+        self.height: int = 1024
+        self.image: Image.Image = Image.new("RGB", (1024, 1024), (0, 0, 0))
+        # shape templates: name -> {"w": int, "h": int, "elements": list}
+        self.shapes: dict[str, dict[str, Any]] = {}
+        # placed objects: list of dicts with id, class, bbox, mask
+        self.objects: list[dict[str, Any]] = []
+
+    def reset(self) -> None:
+        self.image = Image.new("RGB", (self.width, self.height), (0, 0, 0))
+        self.objects = []
+
+
+_state = _State()
+
+# ---------------------------------------------------------------------------
+# Colour helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_color(value: Any) -> tuple[int, int, int]:
+    """Normalise a colour value to an (R, G, B) tuple.
+
+    Accepts:
+        - An RGB tuple/list:  (255, 0, 0)  or  [255, 0, 0]
+        - A hex string:       "#FF0000"    or  "FF0000"
+    """
+    if isinstance(value, (tuple, list)) and len(value) == 3:
+        r, g, b = int(value[0]), int(value[1]), int(value[2])
+        if not all(0 <= c <= 255 for c in (r, g, b)):
+            raise ValueError(f"RGB components must be 0–255, got {value!r}")
+        return (r, g, b)
+
+    if isinstance(value, str):
+        hex_str = value.lstrip("#")
+        if len(hex_str) != 6:
+            raise ValueError(f"Expected a 6-digit hex colour, got {value!r}")
+        return (int(hex_str[0:2], 16), int(hex_str[2:4], 16), int(hex_str[4:6], 16))
+
+    raise TypeError(
+        f"Colour must be an RGB tuple or a hex string, got {type(value).__name__!r}"
+    )
+
+
+def _make_fill_image(
+    w: int,
+    h: int,
+    fill: Any,
+    seed: int | None = None,
+) -> Image.Image:
+    """Rasterise a fill specification into an RGBA Pillow image.
+
+    Supported fill values:
+
+    * ``(R, G, B)`` or ``"#RRGGBB"`` – solid colour
+    * ``{"type": "gradient", "start": color, "end": color, "direction": "horizontal"|"vertical"}``
+    * ``{"type": "noise", "base": color, "scale": 0.0-1.0}``
+    * ``{"type": "perlin", "base": color, "scale": 0.0-1.0, "octaves": int}``
+    """
+    rng = random.Random(seed)
+
+    if isinstance(fill, dict):
+        fill_type = fill.get("type", "")
+
+        # ---- gradient -------------------------------------------------------
+        if fill_type == "gradient":
+            start = _parse_color(fill.get("start", (0, 0, 0)))
+            end = _parse_color(fill.get("end", (255, 255, 255)))
+            direction = fill.get("direction", "horizontal")
+            img = Image.new("RGB", (w, h))
+            pixels = img.load()
+            assert pixels is not None
+            steps = w if direction == "horizontal" else h
+            for i in range(steps):
+                t = i / max(steps - 1, 1)
+                r = int(start[0] + (end[0] - start[0]) * t)
+                g = int(start[1] + (end[1] - start[1]) * t)
+                b = int(start[2] + (end[2] - start[2]) * t)
+                for j in range(h if direction == "horizontal" else w):
+                    if direction == "horizontal":
+                        pixels[i, j] = (r, g, b)
+                    else:
+                        pixels[j, i] = (r, g, b)
+            return img.convert("RGBA")
+
+        # ---- noise ----------------------------------------------------------
+        if fill_type == "noise":
+            base = _parse_color(fill.get("base", (128, 128, 128)))
+            scale = float(fill.get("scale", 0.5))
+            img = Image.new("RGB", (w, h))
+            pixels = img.load()
+            assert pixels is not None
+            half = int(255 * scale * 0.5)
+            for y in range(h):
+                for x in range(w):
+                    offset = rng.randint(-half, half)
+                    pixels[x, y] = (
+                        max(0, min(255, base[0] + offset)),
+                        max(0, min(255, base[1] + offset)),
+                        max(0, min(255, base[2] + offset)),
+                    )
+            return img.convert("RGBA")
+
+        # ---- perlin (approximated with layered noise) ------------------------
+        if fill_type == "perlin":
+            base = _parse_color(fill.get("base", (128, 128, 128)))
+            scale = float(fill.get("scale", 0.5))
+            octaves = int(fill.get("octaves", 4))
+            img = Image.new("RGB", (w, h))
+            pixels = img.load()
+            assert pixels is not None
+
+            # Build layered value-noise grid as a simple perlin approximation
+            def _smoothstep(t: float) -> float:
+                return t * t * (3 - 2 * t)
+
+            def _lerp(a: float, b: float, t: float) -> float:
+                return a + (b - a) * t
+
+            noise_map = [[0.0] * h for _ in range(w)]
+            amplitude = 1.0
+            freq = 1
+            max_val = 0.0
+            for _ in range(octaves):
+                gw = max(2, w // freq)
+                gh = max(2, h // freq)
+                grid = [
+                    [rng.uniform(-1, 1) for _ in range(gh)] for _ in range(gw)
+                ]
+                for y in range(h):
+                    for x in range(w):
+                        gx = (x / w) * (gw - 1)
+                        gy = (y / h) * (gh - 1)
+                        ix, iy = int(gx), int(gy)
+                        fx = _smoothstep(gx - ix)
+                        fy = _smoothstep(gy - iy)
+                        ix1 = min(ix + 1, gw - 1)
+                        iy1 = min(iy + 1, gh - 1)
+                        v = _lerp(
+                            _lerp(grid[ix][iy], grid[ix1][iy], fx),
+                            _lerp(grid[ix][iy1], grid[ix1][iy1], fx),
+                            fy,
+                        )
+                        noise_map[x][y] += v * amplitude
+                max_val += amplitude
+                amplitude *= 0.5
+                freq *= 2
+
+            half = int(255 * scale * 0.5)
+            for y in range(h):
+                for x in range(w):
+                    t = (noise_map[x][y] / max_val + 1) * 0.5  # normalise to [0,1]
+                    offset = int((t - 0.5) * 2 * half)
+                    pixels[x, y] = (
+                        max(0, min(255, base[0] + offset)),
+                        max(0, min(255, base[1] + offset)),
+                        max(0, min(255, base[2] + offset)),
+                    )
+            return img.convert("RGBA")
+
+        raise ValueError(f"Unknown fill type {fill_type!r}")
+
+    # Solid colour
+    color = _parse_color(fill)
+    return Image.new("RGBA", (w, h), (*color, 255))
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def init(
+    device: str = "cpu",
+    w: int = 1024,
+    h: int = 1024,
+) -> None:
+    """Initialise Spacial for a new generation session.
+
+    Parameters
+    ----------
+    device:
+        Compute device – ``"cpu"`` (default), ``"cuda"``, or ``"mps"``.
+        ``"cuda"`` and ``"mps"`` are accepted but currently behave identically
+        to ``"cpu"``; GPU acceleration is reserved for a future release.
+    w:
+        Canvas width in pixels (default ``1024``).
+    h:
+        Canvas height in pixels (default ``1024``).
+
+    Example
+    -------
+        >>> spacial.init(device="cpu", w=640, h=480)
+    """
+    if device not in _SUPPORTED_DEVICES:
+        raise ValueError(
+            f"device must be one of {sorted(_SUPPORTED_DEVICES)!r}, got {device!r}"
+        )
+    if w <= 0 or h <= 0:
+        raise ValueError(f"Canvas dimensions must be positive, got w={w}, h={h}")
+
+    _state.device = device
+    _state.width = w
+    _state.height = h
+    _state.image = Image.new("RGB", (w, h), (0, 0, 0))
+    _state.shapes = {}
+    _state.objects = []
+
+
+def background(
+    bg_type: str,
+    /,
+    *,
+    fill: Any = (0, 0, 0),
+    path: str | None = None,
+    seed: int | None = None,
+    **_kwargs: Any,
+) -> None:
+    """Fill the canvas with a background.
+
+    Parameters
+    ----------
+    bg_type:
+        One of ``"color"``, ``"gradient"``, ``"noise"``, ``"perlin"``,
+        or ``"img"``.
+    fill:
+        Colour or fill specification used by ``"color"``, ``"gradient"``,
+        ``"noise"``, and ``"perlin"`` types.
+
+        * Solid colour: ``(R, G, B)`` tuple or ``"#RRGGBB"`` hex string.
+        * Gradient:     ``{"type": "gradient", "start": color, "end": color,
+          "direction": "horizontal"|"vertical"}``
+        * Noise:        ``{"type": "noise", "base": color, "scale": 0.5}``
+        * Perlin:       ``{"type": "perlin", "base": color, "scale": 0.5,
+          "octaves": 4}``
+    path:
+        Path to an image file (required for ``bg_type="img"``).
+    seed:
+        Optional random seed for reproducible noise/perlin backgrounds.
+
+    Example
+    -------
+        >>> spacial.background("color", fill="#1A1A2E")
+        >>> spacial.background("gradient", fill={
+        ...     "type": "gradient",
+        ...     "start": "#FF6B6B",
+        ...     "end": "#4ECDC4",
+        ...     "direction": "vertical",
+        ... })
+        >>> spacial.background("img", path="sky.jpg")
+    """
+    if bg_type not in _SUPPORTED_BG_TYPES:
+        raise ValueError(
+            f"bg_type must be one of {sorted(_SUPPORTED_BG_TYPES)!r}, got {bg_type!r}"
+        )
+
+    w, h = _state.width, _state.height
+
+    if bg_type == "img":
+        if path is None:
+            raise ValueError('path is required for bg_type="img"')
+        src = Image.open(path).convert("RGB").resize((w, h))
+        _state.image.paste(src, (0, 0))
+        return
+
+    # For "color", "gradient", "noise", "perlin" the fill dict may already
+    # carry the correct type, or we normalise a plain colour.
+    if bg_type in {"gradient", "noise", "perlin"} and not isinstance(fill, dict):
+        raise ValueError(
+            f'bg_type="{bg_type}" requires fill to be a dict, '
+            f"e.g. {{'type': '{bg_type}', ...}}"
+        )
+
+    if bg_type == "color":
+        effective_fill: Any = fill
+    else:
+        effective_fill = fill  # already a dict
+
+    bg_img = _make_fill_image(w, h, effective_fill, seed=seed)
+    _state.image.paste(bg_img.convert("RGB"), (0, 0))
+
+
+def shape(name: str, *, w: int, h: int) -> None:
+    """Register a reusable shape template.
+
+    Parameters
+    ----------
+    name:
+        Unique identifier for this shape template.
+    w:
+        Template width in pixels.
+    h:
+        Template height in pixels.
+
+    Example
+    -------
+        >>> spacial.shape("badge", w=80, h=80)
+    """
+    if w <= 0 or h <= 0:
+        raise ValueError(f"Shape dimensions must be positive, got w={w}, h={h}")
+
+    _state.shapes[name] = {"w": w, "h": h, "elements": []}
+
+
+def shape_add(
+    name: str,
+    primitive: str,
+    /,
+    *,
+    fill: Any = (255, 255, 255),
+    path: str | None = None,
+    # Circle params
+    cx: int | None = None,
+    cy: int | None = None,
+    r: int | None = None,
+    # Rectangle params
+    x0: int | None = None,
+    y0: int | None = None,
+    x1: int | None = None,
+    y1: int | None = None,
+    # Image params
+    x: int = 0,
+    y: int = 0,
+    **_kwargs: Any,
+) -> None:
+    """Add a primitive element to an existing shape template.
+
+    Parameters
+    ----------
+    name:
+        Name of the shape template to modify.
+    primitive:
+        One of ``"circle"``, ``"rectangle"``, ``"img"``.
+    fill:
+        Colour or fill specification (ignored for ``primitive="img"``).
+    path:
+        Path to an image file (required for ``primitive="img"``).
+    cx, cy, r:
+        Centre x, centre y, and radius for circles.
+    x0, y0, x1, y1:
+        Bounding-box corners for rectangles.
+    x, y:
+        Top-left position for pasted images.
+
+    Example
+    -------
+        >>> spacial.shape("badge", w=80, h=80)
+        >>> spacial.shape_add("badge", "circle", fill="#FF4500", cx=40, cy=40, r=38)
+        >>> spacial.shape_add("badge", "rectangle", fill=(0, 0, 0),
+        ...                  x0=20, y0=60, x1=60, y1=68)
+    """
+    if name not in _state.shapes:
+        raise KeyError(f"Shape {name!r} is not defined. Call spacial.shape() first.")
+    if primitive not in _SUPPORTED_SHAPE_PRIMITIVES:
+        raise ValueError(
+            f"primitive must be one of {sorted(_SUPPORTED_SHAPE_PRIMITIVES)!r}, "
+            f"got {primitive!r}"
+        )
+
+    element: dict[str, Any] = {"primitive": primitive, "fill": fill}
+
+    if primitive == "circle":
+        if any(v is None for v in (cx, cy, r)):
+            raise ValueError("circle requires cx, cy, and r")
+        element.update({"cx": cx, "cy": cy, "r": r})
+
+    elif primitive == "rectangle":
+        if any(v is None for v in (x0, y0, x1, y1)):
+            raise ValueError("rectangle requires x0, y0, x1, y1")
+        element.update({"x0": x0, "y0": y0, "x1": x1, "y1": y1})
+
+    elif primitive == "img":
+        if path is None:
+            raise ValueError('img primitive requires path')
+        element.update({"path": path, "x": x, "y": y})
+
+    _state.shapes[name]["element_type"] = primitive
+    _state.shapes[name]["elements"].append(element)
+
+
+def _render_shape(shape_name: str) -> Image.Image:
+    """Rasterise a shape template into an RGBA Pillow image."""
+    tmpl = _state.shapes[shape_name]
+    w, h = tmpl["w"], tmpl["h"]
+    canvas = Image.new("RGBA", (w, h), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(canvas)
+
+    for elem in tmpl["elements"]:
+        prim = elem["primitive"]
+
+        if prim == "circle":
+            color = _parse_color(elem["fill"])
+            cx_v: int = elem["cx"]
+            cy_v: int = elem["cy"]
+            r_v: int = elem["r"]
+            bbox_coords = [cx_v - r_v, cy_v - r_v, cx_v + r_v, cy_v + r_v]
+            draw.ellipse(bbox_coords, fill=(*color, 255))
+
+        elif prim == "rectangle":
+            color = _parse_color(elem["fill"])
+            draw.rectangle(
+                [elem["x0"], elem["y0"], elem["x1"], elem["y1"]],
+                fill=(*color, 255),
+            )
+
+        elif prim == "img":
+            src = Image.open(elem["path"]).convert("RGBA")
+            canvas.paste(src, (elem["x"], elem["y"]), src)
+
+    return canvas
+
+
+def _render_object(
+    obj_class: str,
+    obj_id: str,
+    x: int,
+    y: int,
+    **kwargs: Any,
+) -> tuple[Image.Image, tuple[int, int, int, int]]:
+    """Render one object and return (RGBA image, (x1, y1, x2, y2) bbox)."""
+    w, h = _state.width, _state.height
+
+    # ---- Named shape template -------------------------------------------
+    if obj_class in _state.shapes:
+        rendered = _render_shape(obj_class)
+        sw, sh = rendered.size
+        x2 = min(w, x + sw)
+        y2 = min(h, y + sh)
+        return rendered, (x, y, x2, y2)
+
+    # ---- Inline image ---------------------------------------------------
+    if obj_class == "img":
+        path = kwargs.get("path")
+        if path is None:
+            raise ValueError('append with class="img" requires path=...')
+        img_w = int(kwargs.get("w", 0))
+        img_h = int(kwargs.get("h", 0))
+        src = Image.open(path).convert("RGBA")
+        if img_w > 0 and img_h > 0:
+            src = src.resize((img_w, img_h))
+        sw, sh = src.size
+        x2 = min(w, x + sw)
+        y2 = min(h, y + sh)
+        return src, (x, y, x2, y2)
+
+    # ---- Fallback: coloured rectangle -----------------------------------
+    fill = kwargs.get("fill", (200, 200, 200))
+    obj_w = int(kwargs.get("w", 64))
+    obj_h = int(kwargs.get("h", 64))
+    color = _parse_color(fill)
+    rect = Image.new("RGBA", (obj_w, obj_h), (*color, 255))
+    x2 = min(w, x + obj_w)
+    y2 = min(h, y + obj_h)
+    return rect, (x, y, x2, y2)
+
+
+def append(
+    obj_id: str,
+    obj_class: str,
+    /,
+    *,
+    x: int = 0,
+    y: int = 0,
+    **kwargs: Any,
+) -> None:
+    """Place an object on the current canvas and record its annotation.
+
+    Parameters
+    ----------
+    obj_id:
+        Unique identifier for this instance (used in annotation output).
+    obj_class:
+        Either a registered shape name, ``"img"``, or any label used as a
+        fallback placeholder rectangle.
+    x:
+        Left edge of the object in canvas pixels.
+    y:
+        Top edge of the object in canvas pixels.
+    **kwargs:
+        Extra arguments forwarded to the renderer (e.g. ``path=``, ``w=``,
+        ``h=``, ``fill=``).
+
+    Example
+    -------
+        >>> spacial.append("car_001", "car", x=100, y=200, fill="#E63946", w=120, h=60)
+        >>> spacial.append("logo", "img", path="logo.png", x=10, y=10)
+    """
+    rendered, (x1, y1, x2, y2) = _render_object(obj_class, obj_id, x, y, **kwargs)
+    _state.image.paste(rendered.convert("RGB"), (x1, y1), rendered)
+
+    # Build a simple binary mask for segmentation
+    mask_img = Image.new("L", (_state.width, _state.height), 0)
+    # Paste the alpha channel of the rendered object as a mask patch
+    alpha = rendered.split()[-1] if rendered.mode == "RGBA" else Image.new("L", rendered.size, 255)
+    mask_img.paste(alpha, (x1, y1))
+    mask_data = list(mask_img.getdata())
+
+    _state.objects.append(
+        {
+            "id": obj_id,
+            "class": obj_class,
+            "bbox": [x1, y1, x2, y2],
+            "mask": mask_data,          # flat list, row-major, 0/255
+            "mask_size": (_state.width, _state.height),
+        }
+    )
+
+
+def bbox(obj_id: str | None = None) -> list[dict[str, Any]]:
+    """Return bounding-box annotations for all (or one) object(s).
+
+    Parameters
+    ----------
+    obj_id:
+        When provided, returns annotations for that object only.
+        When ``None`` (default), returns annotations for every object.
+
+    Returns
+    -------
+    list[dict]:
+        Each entry has keys ``"id"``, ``"class"``, and
+        ``"bbox"`` ``[x1, y1, x2, y2]``.
+
+    Example
+    -------
+        >>> spacial.bbox()
+        [{'id': 'car_001', 'class': 'car', 'bbox': [100, 200, 220, 260]}]
+    """
+    objects = _state.objects if obj_id is None else [
+        o for o in _state.objects if o["id"] == obj_id
+    ]
+    return [
+        {"id": o["id"], "class": o["class"], "bbox": o["bbox"]}
+        for o in objects
+    ]
+
+
+def seg(obj_id: str | None = None) -> list[dict[str, Any]]:
+    """Return segmentation annotations for all (or one) object(s).
+
+    The mask is returned as a flat list of values (0 or 255) in row-major
+    order, matching the full canvas size. Convert to a numpy array with
+    ``np.array(entry["mask"]).reshape(h, w)`` if needed.
+
+    Parameters
+    ----------
+    obj_id:
+        When provided, returns annotations for that object only.
+
+    Returns
+    -------
+    list[dict]:
+        Each entry has keys ``"id"``, ``"class"``, ``"bbox"``,
+        ``"mask"`` (flat list), and ``"mask_size"`` ``(w, h)``.
+
+    Example
+    -------
+        >>> entries = spacial.seg()
+        >>> entries[0]["mask_size"]
+        (1024, 1024)
+    """
+    objects = _state.objects if obj_id is None else [
+        o for o in _state.objects if o["id"] == obj_id
+    ]
+    return [
+        {
+            "id": o["id"],
+            "class": o["class"],
+            "bbox": o["bbox"],
+            "mask": o["mask"],
+            "mask_size": o["mask_size"],
+        }
+        for o in objects
+    ]
+
+
+def save(path: str) -> None:
+    """Save the current canvas to disk.
+
+    Parameters
+    ----------
+    path:
+        Output file path. The format is inferred from the extension
+        (``".png"``, ``".jpg"``, ``".jpeg"``, ``".bmp"``, ``".webp"`` etc.)
+        via Pillow.
+
+    Example
+    -------
+        >>> spacial.save("dataset/frame_001.png")
+    """
+    _state.image.save(path)
+
+
+def rm() -> None:
+    """Clear the current canvas and all annotations.
+
+    Resets the image to a black canvas of the current dimensions and
+    removes all placed objects. Shape templates are preserved.
+
+    Example
+    -------
+        >>> spacial.rm()
+    """
+    _state.reset()

spacial-0.1.0.dist-info/METADATA

@@ -0,0 +1,545 @@
+Metadata-Version: 2.4
+Name: spacial
+Version: 0.1.0
+Summary: A lightweight synthetic dataset image generation library built on top of Pillow.
+Author: Spacial Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/your-org/spacial
+Project-URL: Documentation, https://github.com/your-org/spacial/blob/main/docs.md
+Project-URL: Issues, https://github.com/your-org/spacial/issues
+Keywords: synthetic data,image generation,dataset,bounding box,segmentation,pillow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+
+# Spacial
+
+> Lightweight synthetic dataset image generation — powered by Pillow.
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-0.1.0-orange.svg)]()
+
+Spacial is a small, focused library for generating synthetic training images and their annotations. You describe what to put on a canvas — backgrounds, shapes, images — and Spacial gives you back pixel-perfect bounding boxes and segmentation masks in plain Python data structures. No frameworks. No hidden config files. No magic.
+
+---
+
+## Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Design Philosophy](#design-philosophy)
+- [API Reference](#api-reference)
+  - [init](#init)
+  - [background](#background)
+  - [shape / shape_add](#shape--shape_add)
+  - [append](#append)
+  - [bbox](#bbox)
+  - [seg](#seg)
+  - [save](#save)
+  - [rm](#rm)
+- [Fill System](#fill-system)
+- [Examples](#examples)
+- [Exporting Annotations](#exporting-annotations)
+- [Future Roadmap](#future-roadmap)
+
+---
+
+## Installation
+
+```bash
+pip install spacial
+```
+
+Spacial requires **Python 3.9+** and **Pillow ≥ 10.0**.
+
+---
+
+## Quick Start
+
+```python
+import spacial
+
+# 1. Set up a 640×480 canvas
+spacial.init(w=640, h=480)
+
+# 2. Dark gradient background
+spacial.background("gradient", fill={
+    "type": "gradient",
+    "start": "#1A1A2E",
+    "end": "#16213E",
+    "direction": "vertical",
+})
+
+# 3. Define a reusable shape template
+spacial.shape("car", w=120, h=60)
+spacial.shape_add("car", "rectangle", fill="#E63946", x0=0, y0=10, x1=120, y1=60)
+spacial.shape_add("car", "rectangle", fill="#222222", x0=20, y0=0, x1=100, y1=20)
+
+# 4. Place two cars on the canvas
+spacial.append("car_001", "car", x=50, y=200)
+spacial.append("car_002", "car", x=350, y=300)
+
+# 5. Get annotations
+print(spacial.bbox())
+# [
+#   {"id": "car_001", "class": "car", "bbox": [50, 200, 170, 260]},
+#   {"id": "car_002", "class": "car", "bbox": [350, 300, 470, 360]},
+# ]
+
+# 6. Save and reset
+spacial.save("frame_001.png")
+spacial.rm()
+```
+
+---
+
+## Design Philosophy
+
+Spacial is deliberately narrow. It does exactly three things:
+
+1. **Generate images** — backgrounds, shapes, composited objects.
+2. **Generate bounding box annotations** — pixel-aligned `[x1, y1, x2, y2]`.
+3. **Generate segmentation annotations** — per-pixel binary masks.
+
+Everything else — writing COCO JSON, YOLO `.txt` files, Pascal VOC XML, training loops, data augmentation — is intentionally left to you. Spacial integrates cleanly with whatever export or training pipeline you already have, because it only returns standard Python lists and dicts.
+
+**Guiding principles:**
+
+- **Flat API.** Everything is a module-level function. No classes to instantiate, no context managers to juggle.
+- **Minimal dependencies.** Only Pillow. No NumPy required (though masks are trivial to convert).
+- **Beginner friendly.** If you can write `spacial.append(...)` and `spacial.save(...)`, you have a dataset.
+- **Standard types.** Returns `list`, `dict`, and `tuple` — no custom objects to unwrap.
+- **Both colour notations.** RGB tuples `(255, 0, 0)` and hex strings `"#FF0000"` work everywhere a colour is expected.
+
+---
+
+## API Reference
+
+### `init`
+
+```python
+spacial.init(device="cpu", w=1024, h=1024)
+```
+
+Initialise Spacial and create a blank canvas.
+
+| Parameter | Type  | Default | Description                                          |
+|-----------|-------|---------|------------------------------------------------------|
+| `device`  | `str` | `"cpu"` | Compute device: `"cpu"`, `"cuda"`, or `"mps"`. `cuda` and `mps` are reserved for future GPU acceleration and currently behave identically to `cpu`. |
+| `w`       | `int` | `1024`  | Canvas width in pixels.                              |
+| `h`       | `int` | `1024`  | Canvas height in pixels.                             |
+
+---
+
+### `background`
+
+```python
+spacial.background(bg_type, *, fill=..., path=None, seed=None)
+```
+
+Fill the entire canvas with a background.
+
+| Parameter | Type             | Description                                              |
+|-----------|------------------|----------------------------------------------------------|
+| `bg_type` | `str`            | `"color"`, `"gradient"`, `"noise"`, `"perlin"`, `"img"` |
+| `fill`    | colour or `dict` | Colour value or fill spec (see [Fill System](#fill-system)) |
+| `path`    | `str \| None`    | Path to source image — required for `bg_type="img"`.    |
+| `seed`    | `int \| None`    | Random seed for reproducible noise/perlin backgrounds.  |
+
+**Examples:**
+
+```python
+# Solid colour
+spacial.background("color", fill=(30, 30, 30))
+spacial.background("color", fill="#1A1A2E")
+
+# Horizontal gradient
+spacial.background("gradient", fill={
+    "type": "gradient",
+    "start": "#FF6B6B",
+    "end":   "#4ECDC4",
+    "direction": "horizontal",
+})
+
+# Seeded noise
+spacial.background("noise", fill={
+    "type": "noise",
+    "base": (100, 100, 100),
+    "scale": 0.4,
+}, seed=42)
+
+# Perlin-like noise
+spacial.background("perlin", fill={
+    "type": "perlin",
+    "base": "#2C3E50",
+    "scale": 0.6,
+    "octaves": 5,
+}, seed=7)
+
+# From an existing image file
+spacial.background("img", path="sky.jpg")
+```
+
+---
+
+### `shape` / `shape_add`
+
+```python
+spacial.shape(name, *, w, h)
+spacial.shape_add(name, primitive, *, fill=..., **params)
+```
+
+Define a reusable shape template by stacking primitives.
+
+**`shape`**
+
+| Parameter | Type  | Description                    |
+|-----------|-------|--------------------------------|
+| `name`    | `str` | Unique template name.          |
+| `w`       | `int` | Template width in pixels.      |
+| `h`       | `int` | Template height in pixels.     |
+
+**`shape_add` — primitives**
+
+| Primitive     | Required params                         | Description                         |
+|---------------|-----------------------------------------|-------------------------------------|
+| `"circle"`    | `cx`, `cy`, `r`                         | Circle with centre and radius.       |
+| `"rectangle"` | `x0`, `y0`, `x1`, `y1`                 | Axis-aligned rectangle.              |
+| `"img"`       | `path`, optionally `x`, `y`            | Paste an image at an offset.         |
+
+All primitives accept a `fill` parameter (colour or fill spec).
+
+**Example:**
+
+```python
+spacial.shape("traffic_light", w=40, h=100)
+spacial.shape_add("traffic_light", "rectangle", fill="#222222", x0=0, y0=0, x1=40, y1=100)
+spacial.shape_add("traffic_light", "circle",    fill="#FF0000", cx=20, cy=20, r=14)
+spacial.shape_add("traffic_light", "circle",    fill="#FFA500", cx=20, cy=50, r=14)
+spacial.shape_add("traffic_light", "circle",    fill="#00CC00", cx=20, cy=80, r=14)
+```
+
+---
+
+### `append`
+
+```python
+spacial.append(obj_id, obj_class, *, x=0, y=0, **kwargs)
+```
+
+Place an object on the canvas and record its annotation.
+
+| Parameter   | Type  | Description                                                                 |
+|-------------|-------|-----------------------------------------------------------------------------|
+| `obj_id`    | `str` | Unique instance ID used in annotation output.                               |
+| `obj_class` | `str` | A registered shape name, `"img"`, or any free-form label.                  |
+| `x`         | `int` | Left edge of the object in canvas pixels.                                   |
+| `y`         | `int` | Top edge of the object in canvas pixels.                                    |
+| `**kwargs`  |       | Forwarded to the renderer: `path`, `w`, `h`, `fill`, etc.                 |
+
+**Class resolution order:**
+
+1. If `obj_class` matches a registered shape name → render that template.
+2. If `obj_class == "img"` → load the image at `path=`.
+3. Otherwise → render a placeholder rectangle using `fill=`, `w=`, `h=`.
+
+**Examples:**
+
+```python
+# Named shape
+spacial.append("tl_north", "traffic_light", x=100, y=50)
+
+# Inline image
+spacial.append("sponsor_logo", "img", path="logo.png", x=20, y=20)
+
+# Placeholder (useful for layout testing)
+spacial.append("unknown_001", "unknown", x=300, y=150, fill="#AAAAAA", w=80, h=80)
+```
+
+---
+
+### `bbox`
+
+```python
+spacial.bbox(obj_id=None) -> list[dict]
+```
+
+Return bounding-box annotations.
+
+```python
+[
+    {
+        "id":    "car_001",
+        "class": "car",
+        "bbox":  [x1, y1, x2, y2]   # pixel coordinates, inclusive corners
+    },
+    ...
+]
+```
+
+Pass `obj_id="car_001"` to retrieve a single object's annotation.
+
+---
+
+### `seg`
+
+```python
+spacial.seg(obj_id=None) -> list[dict]
+```
+
+Return segmentation annotations.
+
+```python
+[
+    {
+        "id":        "car_001",
+        "class":     "car",
+        "bbox":      [x1, y1, x2, y2],
+        "mask":      [...],         # flat list, len == w * h, values 0 or 255
+        "mask_size": (w, h)
+    },
+    ...
+]
+```
+
+**Converting the mask to a NumPy array** (NumPy is not a Spacial dependency, but it is easy to integrate):
+
+```python
+import numpy as np
+
+entries = spacial.seg()
+w, h = entries[0]["mask_size"]
+mask = np.array(entries[0]["mask"], dtype=np.uint8).reshape(h, w)
+```
+
+---
+
+### `save`
+
+```python
+spacial.save(path)
+```
+
+Save the current canvas to disk. The file format is inferred from the extension by Pillow (`.png`, `.jpg`, `.bmp`, `.webp`, etc.).
+
+```python
+spacial.save("output/frame_042.png")
+```
+
+---
+
+### `rm`
+
+```python
+spacial.rm()
+```
+
+Clear the canvas to black and remove all placed objects. Shape templates are kept so you can reuse them in the next frame.
+
+---
+
+## Fill System
+
+Wherever a `fill` parameter is accepted, Spacial understands two notations:
+
+**Solid colour**
+
+```python
+fill=(255, 99, 71)      # RGB tuple
+fill="#FF6347"          # hex string (with or without #)
+```
+
+**Gradient**
+
+```python
+fill={
+    "type":      "gradient",
+    "start":     "#FF6B6B",     # any colour value
+    "end":       "#4ECDC4",
+    "direction": "horizontal",  # or "vertical"
+}
+```
+
+**Noise** (uniform random per-pixel offsets from a base colour)
+
+```python
+fill={
+    "type":  "noise",
+    "base":  (128, 128, 128),
+    "scale": 0.5,               # 0.0 → no noise, 1.0 → maximum noise
+}
+```
+
+**Perlin** (layered smooth noise — good for terrain-like backgrounds)
+
+```python
+fill={
+    "type":    "perlin",
+    "base":    "#2C3E50",
+    "scale":   0.6,
+    "octaves": 4,               # more octaves → more detail
+}
+```
+
+---
+
+## Examples
+
+### Minimal YOLO-style loop
+
+```python
+import json
+import spacial
+
+spacial.init(w=416, h=416)
+
+dataset = []
+for i in range(100):
+    spacial.rm()
+    spacial.background("noise", fill={"type": "noise", "base": (80, 80, 80), "scale": 0.3}, seed=i)
+
+    spacial.shape("ball", w=32, h=32)
+    spacial.shape_add("ball", "circle", fill="#F72585", cx=16, cy=16, r=15)
+
+    x, y = i * 3 % 380, i * 7 % 380
+    spacial.append(f"ball_{i:04d}", "ball", x=x, y=y)
+
+    boxes = spacial.bbox()
+    spacial.save(f"images/frame_{i:04d}.png")
+    dataset.append({"frame": i, "annotations": boxes})
+
+with open("annotations.json", "w") as f:
+    json.dump(dataset, f, indent=2)
+```
+
+### Multi-class scene
+
+```python
+import spacial
+
+spacial.init(w=800, h=600)
+spacial.background("perlin", fill={
+    "type":    "perlin",
+    "base":    (34, 85, 34),
+    "scale":   0.5,
+    "octaves": 5,
+}, seed=99)
+
+# Define classes
+spacial.shape("vehicle", w=100, h=50)
+spacial.shape_add("vehicle", "rectangle", fill="#264653", x0=0,  y0=10, x1=100, y1=50)
+spacial.shape_add("vehicle", "rectangle", fill="#2A9D8F", x0=15, y0=0,  x1=85,  y1=20)
+
+spacial.shape("pedestrian", w=20, h=50)
+spacial.shape_add("pedestrian", "rectangle", fill="#E9C46A", x0=6, y0=0,  x1=14, y1=12)  # head
+spacial.shape_add("pedestrian", "rectangle", fill="#F4A261", x0=4, y0=12, x1=16, y1=50)  # body
+
+# Populate scene
+spacial.append("v_001", "vehicle",    x=50,  y=280)
+spacial.append("v_002", "vehicle",    x=400, y=320)
+spacial.append("p_001", "pedestrian", x=250, y=260)
+spacial.append("p_002", "pedestrian", x=310, y=270)
+spacial.append("p_003", "pedestrian", x=600, y=290)
+
+print(spacial.bbox())
+spacial.save("scene.png")
+```
+
+### Pasting real images with segmentation
+
+```python
+import spacial
+
+spacial.init(w=512, h=512)
+spacial.background("color", fill="#F0F0F0")
+
+spacial.append("product_01", "img", path="product.png", x=128, y=128)
+
+for entry in spacial.seg():
+    w, h  = entry["mask_size"]
+    total = w * h
+    hit   = sum(1 for v in entry["mask"] if v > 0)
+    print(f'{entry["id"]} covers {hit/total:.1%} of the canvas')
+
+spacial.save("product_scene.png")
+```
+
+---
+
+## Exporting Annotations
+
+Spacial returns plain Python dicts so you can convert to any format you need:
+
+**YOLO `.txt`**
+
+```python
+boxes = spacial.bbox()
+W, H  = 640, 480
+
+with open("labels/frame_001.txt", "w") as f:
+    class_map = {"car": 0, "pedestrian": 1}
+    for obj in boxes:
+        x1, y1, x2, y2 = obj["bbox"]
+        cx = ((x1 + x2) / 2) / W
+        cy = ((y1 + y2) / 2) / H
+        bw = (x2 - x1) / W
+        bh = (y2 - y1) / H
+        cls = class_map.get(obj["class"], 0)
+        f.write(f"{cls} {cx:.6f} {cy:.6f} {bw:.6f} {bh:.6f}\n")
+```
+
+**COCO-style JSON snippet**
+
+```python
+boxes = spacial.bbox()
+coco_annotations = [
+    {
+        "id":          i,
+        "image_id":    42,
+        "category_id": 1,
+        "bbox":        [b["bbox"][0], b["bbox"][1],
+                        b["bbox"][2] - b["bbox"][0],
+                        b["bbox"][3] - b["bbox"][1]],
+        "area":        (b["bbox"][2] - b["bbox"][0]) * (b["bbox"][3] - b["bbox"][1]),
+        "iscrowd":     0,
+    }
+    for i, b in enumerate(boxes)
+]
+```
+
+---
+
+## Future Roadmap
+
+Spacial is intentionally minimal today. Planned additions in future releases:
+
+- **Shape nesting** — embed one named shape inside another to build hierarchical objects.
+- **Transforms** — per-object rotation, scaling, and opacity.
+- **GPU acceleration** — real CUDA/MPS paths for faster noise generation at high resolutions.
+- **Z-ordering** — explicit depth control for overlapping objects.
+- **Polygon segmentation** — return polygon contours in addition to binary masks.
+- **Single-object annotation queries** — `spacial.bbox("car_001")` already supported; will expand.
+- **Text primitive** — render text labels directly onto shapes.
+- **Physics-based placement** — non-overlapping random placement helpers.
+- **Built-in augmentations** — optional blur, brightness jitter, and crop directly in Spacial.
+
+Spacial will never grow into a training framework or annotation exporter. Those concerns belong in your pipeline, not ours.
+
+---
+
+## License
+
+MIT © Spacial Contributors

spacial-0.1.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+spacial/__init__.py,sha256=JxCa5VGqmoZJMCzMliuJNIJ1N9_WqlielfmTlwuf4us,21539
+spacial-0.1.0.dist-info/METADATA,sha256=7UuV1clizdMmkC5J_MXpPBiu0I2jf1GBB8nVg8rzAkg,15848
+spacial-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+spacial-0.1.0.dist-info/top_level.txt,sha256=eD6G_kDarPdiV4xK5YBgHlZQu6WnEx1bvQvSt-ohfrc,8
+spacial-0.1.0.dist-info/RECORD,,

spacial-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

spacial-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+spacial