rainbow-tensor 0.2.1__py3-none-any.whl

rainbow_tensor/__init__.py

@@ -0,0 +1,18 @@
+"""rainbow-tensor.
+
+A small package for IPython and Jupyter notebooks that visualises tensor
+shape, indexing, and slicing as SVG. It is meant for people learning how a
+tensor is structured and how an indexing expression selects elements.
+
+Public API:
+
+    from rainbow_tensor import show_shape, show_index
+
+    show_shape((2, 2, 2))
+    show_index((2, 2, 2), (0, slice(None), 1))
+"""
+
+from .notebook import show_index, show_shape
+
+__version__ = "0.2.1"
+__all__ = ["show_shape", "show_index", "__version__"]

rainbow_tensor/indexing.py

@@ -0,0 +1,124 @@
+"""Index validation, slice expansion, and selection computation.
+
+This module validates indexing expressions, expands slices into integer
+positions, computes the selected coordinates, and computes the result shape
+after indexing.
+"""
+
+import itertools
+
+from .shape import format_shape
+
+
+def validate_index(index, shape):
+    """Validate an index tuple against a tensor shape.
+
+    The index must be a tuple whose length matches the tensor rank. Each
+    entry must be a non-negative in-range integer or a slice. Negative
+    integers and other entry types are rejected in this version.
+    """
+    if not isinstance(index, tuple):
+        raise TypeError(
+            f"index must be a tuple, got {type(index).__name__}. "
+            f"For a single axis use a one element tuple such as (0,)"
+        )
+
+    if len(index) != len(shape):
+        raise ValueError(
+            f"index length {len(index)} does not match tensor rank {len(shape)}"
+        )
+
+    for axis, (entry, size) in enumerate(zip(index, shape)):
+        if isinstance(entry, bool):
+            raise TypeError(f"axis {axis}: boolean indices are not supported")
+        if isinstance(entry, int):
+            if entry < 0:
+                raise IndexError(
+                    f"axis {axis}: negative indices are not supported, got {entry}"
+                )
+            if entry >= size:
+                raise IndexError(
+                    f"axis {axis}: integer index {entry} is out of range for size {size}"
+                )
+        elif isinstance(entry, slice):
+            continue
+        else:
+            raise TypeError(
+                f"axis {axis}: unsupported index entry {entry!r}. "
+                f"Only integers and slices are supported"
+            )
+
+    return index
+
+
+def expand_slice(sl, size):
+    """Expand a slice into the list of integer positions it selects."""
+    return list(range(*sl.indices(size)))
+
+
+def selected_coordinates(shape, index):
+    """Compute every coordinate selected by ``index`` in row-major order."""
+    validate_index(index, shape)
+    axes = []
+    for entry, size in zip(index, shape):
+        if isinstance(entry, int):
+            axes.append([entry])
+        else:
+            axes.append(expand_slice(entry, size))
+    return list(itertools.product(*axes))
+
+
+def result_shape(shape, index):
+    """Compute the result shape after indexing.
+
+    Integer entries remove their axis. Slice entries keep their axis with a
+    size equal to the number of selected positions.
+    """
+    validate_index(index, shape)
+    out = []
+    for entry, size in zip(index, shape):
+        if isinstance(entry, slice):
+            out.append(len(expand_slice(entry, size)))
+    return tuple(out)
+
+
+def format_slice(sl):
+    """Format a slice the way it would appear in indexing notation."""
+    if sl.start is None and sl.stop is None and sl.step is None:
+        return ":"
+    start = "" if sl.start is None else str(sl.start)
+    stop = "" if sl.stop is None else str(sl.stop)
+    if sl.step is None:
+        return f"{start}:{stop}"
+    return f"{start}:{stop}:{sl.step}"
+
+
+def format_index(index):
+    """Format an index tuple as a readable string such as ``0, :, 1``."""
+    parts = []
+    for entry in index:
+        if isinstance(entry, slice):
+            parts.append(format_slice(entry))
+        else:
+            parts.append(str(entry))
+    return ", ".join(parts)
+
+
+def explain_index(shape, index):
+    """Build the lines explaining how an index transforms a shape."""
+    validate_index(index, shape)
+    lines = [
+        f"Original shape: {format_shape(shape)}",
+        f"Index: {format_index(index)}",
+        f"Result shape: {format_shape(result_shape(shape, index))}",
+    ]
+    for axis, entry in enumerate(index):
+        if isinstance(entry, int):
+            lines.append(
+                f"Axis {axis} is removed because integer index {entry} is used."
+            )
+        else:
+            lines.append(
+                f"Axis {axis} is kept because slice {format_slice(entry)} is used."
+            )
+    return lines

rainbow_tensor/layout.py

@@ -0,0 +1,126 @@
+"""Layout calculation.
+
+This module converts a tensor shape into 2D drawing coordinates. It knows
+nothing about SVG, so the same layout could be rendered by any backend.
+
+The tensor is drawn as nested per-axis frames. Axis 0 is the outer frame,
+each following non-leaf axis is an inner frame, and the leaf axis elements
+are placed as plain text cells inside the innermost frame.
+"""
+
+from dataclasses import dataclass, field
+
+from .shape import flat_index
+
+CELL_W = 48
+CELL_H = 34
+CELL_GAP = 8
+ROW_PAD = 9
+ROW_GAP = 12
+BLOCK_PAD = 12
+BLOCK_GAP = 30
+PADDING = 20
+
+
+@dataclass
+class Cell:
+    """A single tensor element placed on the canvas."""
+
+    x: float
+    y: float
+    width: float
+    height: float
+    value: object
+    coord: tuple
+    selected: bool = False
+
+
+@dataclass
+class Frame:
+    """A grouping rectangle for one axis.
+
+    ``axis`` is the axis this frame represents, or ``None`` for a neutral
+    container that is not tied to a specific axis (used for 1D tensors).
+    ``selected`` is true when the region contains at least one selected cell.
+    """
+
+    x: float
+    y: float
+    width: float
+    height: float
+    axis: object
+    selected: bool = False
+
+
+@dataclass
+class Layout:
+    """All drawing data for one tensor."""
+
+    cells: list = field(default_factory=list)
+    frames: list = field(default_factory=list)
+    width: float = 0.0
+    height: float = 0.0
+
+
+def build_layout(shape, selected=None, value_fn=None):
+    """Compute the layout for a tensor.
+
+    ``selected`` is an iterable of coordinates to mark as selected.
+    ``value_fn`` maps a coordinate to its display value. When it is ``None``
+    sequential row-major values starting at 0 are used.
+    """
+    sel = {tuple(coord) for coord in (selected or [])}
+    ndim = len(shape)
+    cols = shape[-1]
+
+    row_w = cols * CELL_W + (cols - 1) * CELL_GAP + 2 * ROW_PAD
+    row_h = CELL_H + 2 * ROW_PAD
+
+    layout = Layout()
+
+    def place_cells(rx, ry, prefix):
+        for c in range(cols):
+            x = rx + ROW_PAD + c * (CELL_W + CELL_GAP)
+            coord = prefix + (c,)
+            value = value_fn(coord) if value_fn is not None else flat_index(coord, shape)
+            layout.cells.append(
+                Cell(x, ry + ROW_PAD, CELL_W, CELL_H, value, coord, coord in sel)
+            )
+
+    if ndim == 1:
+        rx, ry = PADDING, PADDING
+        layout.frames.append(Frame(rx, ry, row_w, row_h, axis=None, selected=bool(sel)))
+        place_cells(rx, ry, ())
+        layout.width = PADDING * 2 + row_w
+        layout.height = PADDING * 2 + row_h
+        return layout
+
+    if ndim == 2:
+        rows = shape[0]
+        for r in range(rows):
+            rx = PADDING
+            ry = PADDING + r * (row_h + ROW_GAP)
+            row_sel = any(co[0] == r for co in sel)
+            layout.frames.append(Frame(rx, ry, row_w, row_h, axis=0, selected=row_sel))
+            place_cells(rx, ry, (r,))
+        layout.width = PADDING * 2 + row_w
+        layout.height = PADDING * 2 + rows * row_h + (rows - 1) * ROW_GAP
+        return layout
+
+    blocks, rows, _ = shape
+    block_w = row_w + 2 * BLOCK_PAD
+    block_h = rows * row_h + (rows - 1) * ROW_GAP + 2 * BLOCK_PAD
+    for b in range(blocks):
+        bx = PADDING + b * (block_w + BLOCK_GAP)
+        by = PADDING
+        block_sel = any(co[0] == b for co in sel)
+        layout.frames.append(Frame(bx, by, block_w, block_h, axis=0, selected=block_sel))
+        for r in range(rows):
+            rx = bx + BLOCK_PAD
+            ry = by + BLOCK_PAD + r * (row_h + ROW_GAP)
+            row_sel = any(co[0] == b and co[1] == r for co in sel)
+            layout.frames.append(Frame(rx, ry, row_w, row_h, axis=1, selected=row_sel))
+            place_cells(rx, ry, (b, r))
+    layout.width = PADDING * 2 + blocks * block_w + (blocks - 1) * BLOCK_GAP
+    layout.height = PADDING * 2 + block_h
+    return layout

rainbow_tensor/notebook.py

@@ -0,0 +1,152 @@
+"""Notebook display layer.
+
+This module exposes the public functions ``show_shape`` and ``show_index``.
+Each returns a small object that renders as SVG in a notebook and stays
+inspectable in plain Python, so the package is testable outside a notebook.
+"""
+
+from .indexing import (
+    explain_index,
+    format_slice,
+    result_shape,
+    selected_coordinates,
+    validate_index,
+)
+from .render_svg import (
+    AXIS_FRAME_COLORS,
+    NEUTRAL_COLOR,
+    SELECT_VALUE_COLOR,
+    render_svg,
+)
+from .shape import extract_shape
+
+
+class TensorVisual:
+    """A rendered tensor visualisation.
+
+    The ``svg`` attribute holds the SVG string. In a notebook the object is
+    shown as an image through ``_repr_svg_``. Outside a notebook the same
+    string is available for inspection and testing.
+    """
+
+    def __init__(self, svg, shape, selected=None, result=None, explanation=None):
+        self.svg = svg
+        self.shape = shape
+        self.selected = selected
+        self.result_shape = result
+        self.explanation = explanation or []
+
+    def _repr_svg_(self):
+        return self.svg
+
+    def __str__(self):
+        return self.svg
+
+
+def _value_fn_for(obj):
+    """Build a coordinate to value function for array-like input.
+
+    A tuple carries no values, so generated values are used. Any object with
+    a ``.shape`` attribute is read by coordinate, which covers NumPy arrays
+    and any compatible array-like without importing a tensor library.
+    """
+    if isinstance(obj, tuple):
+        return None
+    if not hasattr(obj, "shape"):
+        return None
+
+    def value_fn(coord):
+        value = obj[coord]
+        item = getattr(value, "item", None)
+        if callable(item):
+            return item()
+        return value
+
+    return value_fn
+
+
+def _shape_label_parts(shape):
+    """Build coloured label parts for a shape.
+
+    Each dimension is coloured to match its frame. Frame axes use their axis
+    colour and the leaf axis stays neutral, since it has no frame.
+    """
+    ndim = len(shape)
+    parts = [("Shape (", NEUTRAL_COLOR)]
+    for axis, dim in enumerate(shape):
+        if axis < ndim - 1:
+            color = AXIS_FRAME_COLORS.get(axis, NEUTRAL_COLOR)
+        else:
+            color = NEUTRAL_COLOR
+        parts.append((str(dim), color))
+        if axis < ndim - 1:
+            parts.append((", ", NEUTRAL_COLOR))
+    parts.append((")", NEUTRAL_COLOR))
+    return parts
+
+
+def _index_label_parts(index):
+    """Build coloured label parts for an index.
+
+    Each token is coloured to match its axis. Frame axes use their axis
+    colour and the leaf axis uses the selected value colour, so the label
+    mirrors the colours drawn on the tensor.
+    """
+    ndim = len(index)
+    parts = [("Index (", NEUTRAL_COLOR)]
+    for axis, entry in enumerate(index):
+        token = format_slice(entry) if isinstance(entry, slice) else str(entry)
+        if axis < ndim - 1:
+            color = AXIS_FRAME_COLORS.get(axis, NEUTRAL_COLOR)
+        else:
+            color = SELECT_VALUE_COLOR
+        parts.append((token, color))
+        if axis < ndim - 1:
+            parts.append((", ", NEUTRAL_COLOR))
+    parts.append((")", NEUTRAL_COLOR))
+    return parts
+
+
+def show_shape(shape):
+    """Visualise the structure of a tensor shape.
+
+    ``shape`` may be a tuple such as ``(2, 2, 2)`` or an array-like object
+    with a ``.shape`` attribute such as a NumPy array. The returned
+    :class:`TensorVisual` renders as SVG in a notebook through ``_repr_svg_``
+    and also exposes the SVG string for inspection and testing.
+    """
+    normalized = extract_shape(shape)
+    value_fn = _value_fn_for(shape)
+    label_parts = _shape_label_parts(normalized)
+    svg = render_svg(normalized, value_fn=value_fn, label_parts=label_parts)
+    return TensorVisual(svg, normalized)
+
+
+def show_index(tensor_or_shape, index):
+    """Visualise how an index selects elements from a tensor.
+
+    ``tensor_or_shape`` may be a shape tuple or an array-like object with a
+    ``.shape`` attribute. ``index`` must be a tuple of integers and slices
+    whose length matches the tensor rank. Selected elements are highlighted,
+    unselected elements stay visible but de-emphasised, and an explanation of
+    the result shape is drawn below the tensor. The returned
+    :class:`TensorVisual` renders as SVG in a notebook through ``_repr_svg_``
+    and also exposes the SVG string for inspection and testing.
+    """
+    normalized = extract_shape(tensor_or_shape)
+    validate_index(index, normalized)
+    selected = selected_coordinates(normalized, index)
+    result = result_shape(normalized, index)
+    explanation = explain_index(normalized, index)
+    value_fn = _value_fn_for(tensor_or_shape)
+    label_parts = _index_label_parts(index)
+    svg = render_svg(
+        normalized,
+        selected=selected,
+        value_fn=value_fn,
+        label_parts=label_parts,
+        explanation=explanation,
+    )
+    return TensorVisual(
+        svg, normalized, selected=selected, result=result, explanation=explanation
+    )

rainbow_tensor/render_svg.py

@@ -0,0 +1,156 @@
+"""SVG rendering.
+
+This module turns a :class:`~rainbow_tensor.layout.Layout` into an SVG
+string. Each axis has its own colour. Axis 0 frames are red and axis 1
+frames are orange. The leaf axis elements are plain text. Selected elements
+are drawn green and, in an index view, only the selected frames keep their
+axis colour while the rest are drawn in a neutral dark tone.
+"""
+
+from .layout import build_layout
+
+AXIS_FRAME_COLORS = {0: "#dc2626", 1: "#f97316"}
+SELECT_VALUE_COLOR = "#16a34a"
+NEUTRAL_COLOR = "#111827"
+TEXT_COLOR = "#111827"
+LABEL_COLOR = "#334155"
+
+LABEL_HEIGHT = 30
+LINE_HEIGHT = 20
+FRAME_WIDTH = 3
+TEXT_MARGIN = 20
+LABEL_FONT_SIZE = 16
+EXPLANATION_FONT_SIZE = 13
+# Approximate width of one monospace character relative to the font size.
+CHAR_WIDTH_RATIO = 0.62
+FONT_FAMILY = "ui-monospace, Menlo, Consolas, monospace"
+
+
+def escape(text):
+    """Escape a value so it is safe inside SVG text and attributes."""
+    return (
+        str(text)
+        .replace("&", "&")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+    )
+
+
+def svg_document(content, width, height):
+    """Wrap rendered elements in a complete SVG document."""
+    return (
+        f'<svg xmlns="http://www.w3.org/2000/svg" '
+        f'width="{width:.0f}" height="{height:.0f}" '
+        f'viewBox="0 0 {width:.0f} {height:.0f}" '
+        f'font-family="{FONT_FAMILY}">'
+        f"{content}"
+        f"</svg>"
+    )
+
+
+def _frame_color(frame, has_selection):
+    """Pick the stroke colour for a frame.
+
+    In a shape view every frame uses its axis colour. In an index view only
+    selected frames keep their axis colour, the rest are neutral.
+    """
+    axis_color = AXIS_FRAME_COLORS.get(frame.axis, NEUTRAL_COLOR)
+    if not has_selection:
+        return axis_color
+    return axis_color if frame.selected else NEUTRAL_COLOR
+
+
+def _cell_color(cell, has_selection):
+    """Pick the text colour for a cell value."""
+    if has_selection and cell.selected:
+        return SELECT_VALUE_COLOR
+    return TEXT_COLOR
+
+
+def _text_width(char_count, font_size):
+    """Estimate the rendered width of a monospace string."""
+    return char_count * font_size * CHAR_WIDTH_RATIO
+
+
+def _text_block_width(label_len, explanation):
+    """Estimate the width needed so the label and explanation are not clipped."""
+    widest = _text_width(label_len, LABEL_FONT_SIZE)
+    for line in explanation:
+        widest = max(widest, _text_width(len(line), EXPLANATION_FONT_SIZE))
+    return 2 * TEXT_MARGIN + widest
+
+
+def _label_element(x, y, parts):
+    """Build a label text element from coloured parts."""
+    spans = "".join(
+        f'<tspan fill="{escape(color)}">{escape(text)}</tspan>' for text, color in parts
+    )
+    return (
+        f'<text x="{x:.0f}" y="{y:.0f}" font-size="16" font-weight="600">{spans}</text>'
+    )
+
+
+def render_svg(
+    shape, selected=None, value_fn=None, label="", label_parts=None, explanation=None
+):
+    """Render a tensor as an SVG string.
+
+    ``selected`` is an iterable of selected coordinates. ``value_fn`` maps a
+    coordinate to its display value. ``label`` is a plain label string while
+    ``label_parts`` is an optional list of ``(text, colour)`` pairs for a
+    coloured label. ``explanation`` is an optional list of lines drawn below.
+    """
+    explanation = explanation or []
+    selected_list = list(selected or [])
+    has_selection = len(selected_list) > 0
+    layout = build_layout(shape, selected=selected_list, value_fn=value_fn)
+
+    parts = []
+
+    for frame in layout.frames:
+        color = _frame_color(frame, has_selection)
+        parts.append(
+            f'<rect x="{frame.x:.0f}" y="{frame.y:.0f}" '
+            f'width="{frame.width:.0f}" height="{frame.height:.0f}" '
+            f'rx="6" fill="none" stroke="{color}" stroke-width="{FRAME_WIDTH}"/>'
+        )
+
+    for cell in layout.cells:
+        color = _cell_color(cell, has_selection)
+        weight = "700" if (has_selection and cell.selected) else "400"
+        cx = cell.x + cell.width / 2
+        cy = cell.y + cell.height / 2
+        parts.append(
+            f'<text x="{cx:.0f}" y="{cy:.0f}" text-anchor="middle" '
+            f'dominant-baseline="central" font-size="15" font-weight="{weight}" '
+            f'fill="{color}">{escape(cell.value)}</text>'
+        )
+
+    if label_parts:
+        label_len = sum(len(text) for text, _ in label_parts)
+    else:
+        label_len = len(label)
+    text_width = _text_block_width(label_len, explanation)
+    width = max(layout.width, text_width)
+    y = layout.height + LABEL_HEIGHT
+
+    if label_parts:
+        parts.append(_label_element(20, y, label_parts))
+        y += LINE_HEIGHT
+    elif label:
+        parts.append(
+            f'<text x="20" y="{y:.0f}" font-size="16" font-weight="600" '
+            f'fill="{LABEL_COLOR}">{escape(label)}</text>'
+        )
+        y += LINE_HEIGHT
+
+    for line in explanation:
+        y += LINE_HEIGHT - 4
+        parts.append(
+            f'<text x="20" y="{y:.0f}" font-size="13" fill="{LABEL_COLOR}">'
+            f"{escape(line)}</text>"
+        )
+
+    height = y + 16
+    return svg_document("".join(parts), width, height)

rainbow_tensor/shape.py

@@ -0,0 +1,92 @@
+"""Shape extraction and validation.
+
+This module turns user input into a validated ``tuple[int, ...]`` shape and
+generates the display values used when only a shape is provided.
+"""
+
+import itertools
+
+SUPPORTED_NDIM = (1, 2, 3)
+
+
+def extract_shape(obj):
+    """Extract a validated shape from a tuple or an array-like object.
+
+    A tuple is treated as a literal shape. Any other object is expected to
+    expose a ``.shape`` attribute (for example a NumPy array). No tensor
+    library is imported, so this works for any object with ``.shape``.
+    """
+    if isinstance(obj, tuple):
+        raw = obj
+    elif hasattr(obj, "shape"):
+        raw = obj.shape
+    else:
+        raw = obj
+    return validate_shape(raw)
+
+
+def validate_shape(shape):
+    """Validate a shape and return it as a ``tuple[int, ...]``.
+
+    The shape must be a non-empty sequence of positive integers with a
+    supported number of dimensions (1D, 2D, or 3D in this version).
+    """
+    if not isinstance(shape, tuple):
+        try:
+            shape = tuple(shape)
+        except TypeError as exc:
+            raise TypeError(
+                "shape must be a tuple of integers or an object with a .shape attribute"
+            ) from exc
+
+    if len(shape) == 0:
+        raise ValueError("shape must have at least one dimension, got an empty shape")
+
+    for dim in shape:
+        if isinstance(dim, bool) or not isinstance(dim, int):
+            raise TypeError(f"shape dimensions must be integers, got {dim!r}")
+        if dim <= 0:
+            raise ValueError(f"shape dimensions must be positive, got {dim!r}")
+
+    if len(shape) not in SUPPORTED_NDIM:
+        raise ValueError(
+            f"only 1D, 2D, and 3D tensors are supported in this version, "
+            f"got {len(shape)} dimensions"
+        )
+
+    return shape
+
+
+def coordinates(shape):
+    """Yield every coordinate in row-major order for the given shape."""
+    return itertools.product(*[range(dim) for dim in shape])
+
+
+def flat_index(coord, shape):
+    """Return the row-major flat index of ``coord`` inside ``shape``."""
+    index = 0
+    for value, dim in zip(coord, shape):
+        index = index * dim + value
+    return index
+
+
+def generate_values(shape):
+    """Map every coordinate of ``shape`` to a sequential value from 0.
+
+    For shape ``(2, 2, 2)`` this produces the values 0 through 7 in
+    row-major order.
+    """
+    return {coord: flat_index(coord, shape) for coord in coordinates(shape)}
+
+
+def format_shape(shape):
+    """Format a shape the way Python prints a tuple, for example ``(2,)``."""
+    return str(tuple(shape))
+
+
+def format_shape_label(shape):
+    """Format a shape for an on-screen label without a trailing comma.
+
+    For shape ``(3,)`` this returns ``(3)`` rather than ``(3,)``.
+    """
+    return "(" + ", ".join(str(dim) for dim in shape) + ")"

rainbow_tensor-0.2.1.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: rainbow-tensor
+Version: 0.2.1
+Summary: Visualise tensor shape, indexing, and slicing as SVG in Jupyter notebooks
+Author-email: Zhixiang Feng <contact@zhixiangfeng.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Niox1337/rainbow-tensor
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: IPython
+Classifier: Framework :: Jupyter
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.19.0
+Requires-Dist: ipython>=7.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+
+# rainbow-tensor
+
+Visualise tensor shape, indexing, and slicing as SVG inside IPython and Jupyter notebooks.
+
+rainbow-tensor is made for people who are learning how a tensor is structured and how an indexing expression selects elements. It draws the tensor as nested blocks, rows, and cells, then highlights exactly which elements an index picks out.
+
+## Features
+
+- Static SVG output that stays sharp at any zoom level in a notebook
+- Shape visualisation for 1D, 2D, and 3D tensors
+- Index visualisation with highlighted selections and a plain text explanation
+- Works with shape tuples and with array-like objects that expose a `.shape` attribute, such as NumPy arrays
+- No tensor library is imported by the core, so the package stays lightweight
+
+## Colour scheme
+
+Each axis has its own colour so the structure and a selection are easy to read.
+
+- Axis 0 is the outer frame, drawn red
+- Axis 1 is the inner row frame, drawn orange
+- The leaf axis elements are plain text, and a selected element is drawn green
+- The numbers in the shape label and the tokens in the index label are coloured to match
+
+In an index view only the selected frames keep their axis colour. The rest of the tensor is drawn in a neutral dark tone so the selected path stands out.
+
+## Installation
+
+Install from source for development.
+
+```bash
+git clone https://github.com/Niox1337/rainbow-tensor.git
+cd rainbow-tensor
+pip install -e .
+```
+
+Install with the development tools (pytest, ruff, build).
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Usage
+
+Run the examples in a Jupyter notebook or an IPython shell so the SVG is displayed.
+
+Visualise a shape.
+
+```python
+from rainbow_tensor import show_shape
+
+show_shape((2, 2, 2))
+```
+
+Visualise how an index selects elements.
+
+```python
+from rainbow_tensor import show_index
+
+show_index((2, 2, 2), (0, slice(None), 1))
+```
+
+For the shape `(2, 2, 2)` the index `(0, slice(None), 1)` selects the values `1` and `3`, the selected coordinates are `(0, 0, 1)` and `(0, 1, 1)`, and the result shape is `(2,)`.
+
+Use a real NumPy array to display its actual values.
+
+```python
+import numpy as np
+from rainbow_tensor import show_shape, show_index
+
+x = np.arange(8).reshape(2, 2, 2)
+show_shape(x)
+show_index(x, (0, slice(None), 1))
+```
+
+Each function returns a small result object. Its `svg` attribute holds the SVG string, so the package can be inspected and tested outside a notebook.
+
+## Supported
+
+- 1D, 2D, and 3D tensors
+- Shape tuples and array-like objects with a `.shape` attribute
+- Integer indexing
+- Basic slicing with `slice(None)`, `slice(start, stop)`, and `slice(start, stop, step)`
+
+## Unsupported in the first version
+
+- Advanced NumPy indexing
+- Boolean masks
+- `None` and `newaxis`
+- Ellipsis
+- 4D or higher tensors
+- Interactive controls and animation
+
+## Development
+
+```bash
+pytest
+ruff check .
+python -m build
+```
+
+## License
+
+MIT

rainbow_tensor-0.2.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+rainbow_tensor/__init__.py,sha256=NqgwPMsJP1om_TOSe4cAwikbY2fnW-I0WXW5TXjZJ1g,507
+rainbow_tensor/indexing.py,sha256=Fe3gS2gEMzEGer6SxuTfMBILLT3JERZtulac2pmunrc,4061
+rainbow_tensor/layout.py,sha256=YxqsV7ie2cnXBoxVjcN41B_Cegw0bHZwzmMShrl81yc,3854
+rainbow_tensor/notebook.py,sha256=DdX_XWvl6SleWz985kIJgRzI4U6-qe3oEUro17YjJys,5031
+rainbow_tensor/render_svg.py,sha256=bQxZq8LNKIYdWvlWLZIBWXDvbonSvzpuLN-Z8RJItHc,5164
+rainbow_tensor/shape.py,sha256=0fsuvkxhf_6LwgvjBKzsmwAx1FFsFa-TJsJ2sEGM7y0,2828
+rainbow_tensor-0.2.1.dist-info/METADATA,sha256=VUO6PZ6lv-SGLh-TF3Ifwsr3BxrGZMsrBHOI8mx5CxM,3745
+rainbow_tensor-0.2.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+rainbow_tensor-0.2.1.dist-info/top_level.txt,sha256=86NVkchsTdikpDRTvZFN2aapL_CSfvwIlB4Xj3oeitM,15
+rainbow_tensor-0.2.1.dist-info/RECORD,,

rainbow_tensor-0.2.1.dist-info/WHEEL

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

rainbow_tensor-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+rainbow_tensor