bin2path 0.1.0__py3-none-any.whl

bin2path/__init__.py

@@ -0,0 +1,48 @@
+"""
+bin2path - Transform numbers into 3D geometric paths.
+
+A library for converting natural numbers into 3D geometric shapes (spatial
+polyline on an integer lattice). Each bit of the binary representation
+is mapped to a symbolic step sequence (L/R/U/D) using a cellular-automaton rule.
+Symbols are then interpreted as local (orientation-dependent) 3D moves, so the
+resulting path is not constrained to a plane.
+
+Usage:
+    import bin2path
+    
+    path = bin2path.encode(42)
+    number = bin2path.decode(path)
+    bin2path.visualize(path)
+    features = bin2path.features(path)
+"""
+
+from bin2path.path import Path3D, PathMetadata
+from bin2path.encode import encode
+from bin2path.decode import decode
+from bin2path.features import features
+from bin2path.visualize import visualize
+from bin2path.serialize import serialize, deserialize, to_json, from_json
+from bin2path.compare import compare
+from bin2path.validate import validate, is_valid
+from bin2path.batch import batch_encode, batch_decode
+
+__version__ = "0.1.0"
+__author__ = "bin2path"
+
+__all__ = [
+    "Path3D",
+    "PathMetadata",
+    "encode",
+    "decode",
+    "features",
+    "visualize",
+    "serialize",
+    "deserialize",
+    "to_json",
+    "from_json",
+    "compare",
+    "validate",
+    "is_valid",
+    "batch_encode",
+    "batch_decode",
+]

bin2path/animate.py

@@ -0,0 +1,237 @@
+"""Simple animation utility for bin2path paths."""
+
+from bin2path.path import Path3D
+from bin2path.orient import infer_dirs_from_path
+import matplotlib.pyplot as plt
+import matplotlib.patches as mpatches
+from mpl_toolkits.mplot3d import Axes3D  # noqa: F401
+import numpy as np
+from typing import Optional
+
+
+def animate(
+    path: Path3D,
+    interval: int = 150,
+    title: Optional[str] = None,
+) -> None:
+    """Animate building the path step by step, coloring segments by step type (L/R/U/D)."""
+    raw_vertices = np.array(path.vertices, dtype=float)
+    vertices = raw_vertices.copy()
+
+    fig = plt.figure(figsize=(8, 6))
+    ax = fig.add_subplot(111, projection="3d")
+
+    # тёмный фон и более "объёмный" вид
+    fig.patch.set_facecolor("black")
+    ax.set_facecolor("black")
+
+    if title is None:
+        title = f"bin2path animation: {path.metadata.original_number}"
+    ax.set_title(title)
+
+    # limits
+    max_range = np.max(np.abs(vertices).max(axis=0)) * 1.1
+    ax.set_xlim([-max_range, max_range])
+    ax.set_ylim([-max_range, max_range])
+    ax.set_zlim([-max_range, max_range])
+
+    # базовый ракурс
+    ax.view_init(elev=30, azim=45)
+
+    # step colors by L/R/U/D
+    step_colors = {
+        "L": "#FF5733",
+        "R": "#2E86AB",
+        "U": "#28A745",
+        "D": "#FFC300",
+    }
+
+    # precompute per-edge colors и глубину по Z
+    dirs = infer_dirs_from_path(path.vertices, path.edges)
+    edge_colors = []
+    edge_depth = []
+    z_min = float(vertices[:, 2].min()) if len(vertices) > 0 else 0.0
+    z_max = float(vertices[:, 2].max()) if len(vertices) > 0 else 1.0
+    z_span = (z_max - z_min) or 1.0
+    for i, (from_idx, to_idx) in enumerate(path.edges):
+        sym = dirs[i] if i < len(dirs) else None
+        edge_colors.append(step_colors.get(sym or "", "#999999"))
+        # глубина относительно наблюдателя по Z
+        z_mid = 0.5 * (vertices[from_idx][2] + vertices[to_idx][2])
+        depth_factor = 0.45 + 0.55 * ((z_mid - z_min) / z_span)
+        edge_depth.append(depth_factor)
+
+    # line segments drawn progressively
+    lines = []
+
+    def update(i: int):
+        # draw segment i-1 -> i
+        if i > 0:
+            from_v = vertices[i - 1]
+            to_v = vertices[i]
+            color = edge_colors[i - 1]
+            depth_factor = edge_depth[i - 1]
+            # outline first (for better readability)
+            ax.plot(
+                [from_v[0], to_v[0]],
+                [from_v[1], to_v[1]],
+                [from_v[2], to_v[2]],
+                color="#FFFFFF",
+                linewidth=max(3.2, 4.6 * depth_factor),
+                alpha=0.85,
+                solid_capstyle="round",
+                solid_joinstyle="round",
+                antialiased=True,
+            )
+            line, = ax.plot(
+                [from_v[0], to_v[0]],
+                [from_v[1], to_v[1]],
+                [from_v[2], to_v[2]],
+                color=color,
+                linewidth=max(2.2, 3.2 * depth_factor),
+                alpha=0.7 + 0.3 * depth_factor,
+                solid_capstyle="round",
+                solid_joinstyle="round",
+                antialiased=True,
+            )
+            lines.append(line)
+        return lines
+
+    # Legend for step types
+    legend_handles = [
+        mpatches.Patch(color=step_colors["L"], label="L (Left)"),
+        mpatches.Patch(color=step_colors["R"], label="R (Right)"),
+        mpatches.Patch(color=step_colors["U"], label="U (Up)"),
+        mpatches.Patch(color=step_colors["D"], label="D (Down)"),
+    ]
+    ax.legend(handles=legend_handles, loc="upper left")
+
+    from matplotlib.animation import FuncAnimation
+
+    # ВАЖНО: держим ссылку на объект анимации, чтобы его не уничтожил GC до show()
+    ani = FuncAnimation(
+        fig,
+        update,
+        frames=len(vertices),
+        interval=interval,
+        blit=False,
+        repeat=False,
+    )
+    # сохраняем на объекте фигуры, чтобы точно не пропал
+    fig._bin2path_animation = ani  # type: ignore[attr-defined]
+
+    plt.show()
+
+
+def rotate_view(
+    path: Path3D,
+    frames: int = 120,
+    interval: int = 80,
+    title: Optional[str] = None,
+) -> None:
+    """Простая анимация вращения камеры вокруг уже построенного пути."""
+    raw_vertices = np.array(path.vertices, dtype=float)
+    vertices = raw_vertices.copy()
+
+    fig = plt.figure(figsize=(8, 6))
+    ax = fig.add_subplot(111, projection="3d")
+
+    fig.patch.set_facecolor("black")
+    ax.set_facecolor("black")
+
+    if title is None:
+        title = f"bin2path rotate: {path.metadata.original_number}"
+    ax.set_title(title, color="white")
+
+    max_range = np.max(np.abs(vertices).max(axis=0)) * 1.1
+    ax.set_xlim([-max_range, max_range])
+    ax.set_ylim([-max_range, max_range])
+    ax.set_zlim([-max_range, max_range])
+
+    # нарисуем весь путь как в визуализации (L/R/U/D цвета)
+    step_colors = {
+        "L": "#FF5733",
+        "R": "#2E86AB",
+        "U": "#28A745",
+        "D": "#FFC300",
+    }
+    dirs = infer_dirs_from_path(path.vertices, path.edges)
+    for i, (from_idx, to_idx) in enumerate(path.edges):
+        sym = dirs[i] if i < len(dirs) else None
+        color = step_colors.get(sym or "", "#999999")
+        p0 = vertices[from_idx]
+        p1 = vertices[to_idx]
+        # outline (white) underlay for contrast
+        ax.plot(
+            [p0[0], p1[0]],
+            [p0[1], p1[1]],
+            [p0[2], p1[2]],
+            color="#FFFFFF",
+            linewidth=3.6,
+            alpha=0.85,
+            solid_capstyle="round",
+            solid_joinstyle="round",
+            antialiased=True,
+        )
+        ax.plot(
+            [p0[0], p1[0]],
+            [p0[1], p1[1]],
+            [p0[2], p1[2]],
+            color=color,
+            linewidth=2.0,
+            alpha=0.9,
+            solid_capstyle="round",
+            solid_joinstyle="round",
+            antialiased=True,
+        )
+
+    # start/end точки
+    if len(vertices) > 0:
+        s = vertices[0]
+        ax.scatter(
+            [s[0]],
+            [s[1]],
+            [s[2]],
+            c="#FFFFFF",
+            s=80,
+            marker="o",
+        )
+    if len(vertices) > 1:
+        e = vertices[-1]
+        ax.scatter(
+            [e[0]],
+            [e[1]],
+            [e[2]],
+            c="#FF0000",
+            s=80,
+            marker="s",
+        )
+
+    # легенда направлений
+    legend_handles = [
+        mpatches.Patch(color=step_colors["L"], label="L (Left)"),
+        mpatches.Patch(color=step_colors["R"], label="R (Right)"),
+        mpatches.Patch(color=step_colors["U"], label="U (Up)"),
+        mpatches.Patch(color=step_colors["D"], label="D (Down)"),
+    ]
+    ax.legend(handles=legend_handles, loc="upper left")
+
+    from matplotlib.animation import FuncAnimation
+
+    def update_view(i: int):
+        az = 360.0 * (i / frames)
+        ax.view_init(elev=30, azim=az)
+        return []
+
+    ani = FuncAnimation(
+        fig,
+        update_view,
+        frames=frames,
+        interval=interval,
+        blit=False,
+        repeat=True,
+    )
+    fig._bin2path_rotation = ani  # type: ignore[attr-defined]
+
+    plt.show()
+

bin2path/batch.py

@@ -0,0 +1,38 @@
+"""Batch operations for encoding/decoding multiple items."""
+
+from bin2path.path import Path3D
+from bin2path.encode import encode
+from bin2path.decode import decode
+from typing import List
+
+
+def batch_encode(numbers: List[int]) -> List[Path3D]:
+    """
+    Encode multiple numbers into paths.
+    
+    Args:
+        numbers: List of non-negative integers.
+        
+    Returns:
+        List of Path3D objects.
+        
+    Raises:
+        ValueError: If any number is invalid.
+    """
+    return [encode(n) for n in numbers]
+
+
+def batch_decode(paths: List[Path3D]) -> List[int]:
+    """
+    Decode multiple paths back to numbers.
+    
+    Args:
+        paths: List of Path3D objects.
+        
+    Returns:
+        List of original numbers.
+        
+    Raises:
+        ValueError: If any path is invalid.
+    """
+    return [decode(p) for p in paths]

bin2path/compare.py

@@ -0,0 +1,139 @@
+"""Compare two paths for similarity."""
+
+from bin2path.path import Path3D
+from bin2path.features import features
+import numpy as np
+import math
+from typing import Optional
+
+
+def compare(
+    path1: Path3D,
+    path2: Path3D,
+    method: str = "features",
+) -> dict:
+    """
+    Compare two paths and return similarity metrics.
+    
+    Args:
+        path1: First Path3D object.
+        path2: Second Path3D object.
+        method: Comparison method - "features", "hausdorff", or "dtw".
+        
+    Returns:
+        Dictionary with similarity metrics.
+        
+    Raises:
+        ValueError: If method is unknown.
+    """
+    if method == "features":
+        return _compare_features(path1, path2)
+    elif method == "hausdorff":
+        return _compare_hausdorff(path1, path2)
+    elif method == "dtw":
+        return _compare_dtw(path1, path2)
+    else:
+        raise ValueError(f"Unknown comparison method: {method}")
+
+
+def _compare_features(path1: Path3D, path2: Path3D) -> dict:
+    """Compare paths using extracted features."""
+    f1 = features(path1)
+    f2 = features(path2)
+    
+    # Numeric features to compare
+    numeric_keys = [
+        "path_length",
+        "turns",
+        "direct_distance",
+        "straightness",
+        "self_intersections",
+    ]
+    
+    differences = {}
+    for key in numeric_keys:
+        diff = abs(f1.get(key, 0) - f2.get(key, 0))
+        differences[key] = diff
+    
+    # Direction histogram comparison (L1 distance)
+    hist1 = f1.get("direction_histogram", {})
+    hist2 = f2.get("direction_histogram", {})
+    hist_diff = sum(abs(hist1.get(k, 0) - hist2.get(k, 0)) for k in set(hist1) | set(hist2))
+    
+    # Combined similarity score (lower = more similar)
+    total_diff = sum(differences.values()) + hist_diff * 0.1
+    
+    return {
+        "method": "features",
+        "feature_differences": differences,
+        "direction_histogram_diff": hist_diff,
+        "total_difference": total_diff,
+        "similarity_score": 1.0 / (1.0 + total_diff),
+    }
+
+
+def _compare_hausdorff(path1: Path3D, path2: Path3D) -> dict:
+    """Compute Hausdorff distance between path vertex sets."""
+    v1 = np.array(path1.vertices)
+    v2 = np.array(path2.vertices)
+
+    # Guard against empty vertex sets (defensive: Path3D normally enforces vertices exist)
+    if v1.size == 0 and v2.size == 0:
+        forward = 0.0
+        backward = 0.0
+    elif v1.size == 0:
+        forward = math.inf
+        backward = 0.0
+    elif v2.size == 0:
+        forward = 0.0
+        backward = math.inf
+    else:
+        # Forward Hausdorff: max distance from any point in v1 to nearest in v2
+        forward = max(np.linalg.norm(p - v2, axis=1).min() for p in v1)
+
+        # Backward: max distance from any point in v2 to nearest in v1
+        backward = max(np.linalg.norm(p - v1, axis=1).min() for p in v2)
+    
+    hausdorff = max(forward, backward)
+    
+    return {
+        "method": "hausdorff",
+        "forward_hausdorff": float(forward),
+        "backward_hausdorff": float(backward),
+        "hausdorff_distance": float(hausdorff),
+    }
+
+
+def _compare_dtw(path1: Path3D, path2: Path3D, max_cost: Optional[float] = None) -> dict:
+    """Compute Dynamic Time Warping distance between paths."""
+    # For 3D paths, use vertex positions as time series
+    v1 = np.array(path1.vertices)
+    v2 = np.array(path2.vertices)
+    
+    n, m = len(v1), len(v2)
+    
+    # DTW matrix
+    dtw = np.full((n + 1, m + 1), float("inf"))
+    dtw[0, 0] = 0
+    
+    for i in range(1, n + 1):
+        for j in range(1, m + 1):
+            cost = np.linalg.norm(v1[i - 1] - v2[j - 1])
+            dtw[i, j] = cost + min(
+                dtw[i - 1, j],      # insertion
+                dtw[i, j - 1],      # deletion
+                dtw[i - 1, j - 1],  # match
+            )
+    
+    dtw_distance = dtw[n, m]
+    
+    # Normalize by path length
+    normalized = dtw_distance / ((n + m) / 2)
+    
+    return {
+        "method": "dtw",
+        "dtw_distance": float(dtw_distance),
+        "normalized_dtw": float(normalized),
+        "path1_length": n,
+        "path2_length": m,
+    }

bin2path/decode.py

@@ -0,0 +1,33 @@
+"""Decode a 3D path back into a number (L/R/U/D scheme with local orientation)."""
+
+from bin2path.path import Path3D
+from bin2path.encode import _decode_bits_from_dirs  # type: ignore
+from bin2path.orient import infer_dirs_from_path
+
+
+def decode(path: Path3D) -> int:
+    """
+    Decode a 3D path back into the original number.
+
+    Steps:
+    1) edges -> L/R/U/D using local-frame inference
+    2) dirs -> bits via _decode_bits_from_dirs
+    3) bits (MSB->LSB) -> integer
+    """
+    if not path.vertices:
+        raise ValueError("Path must have at least one vertex")
+
+    if len(path.edges) == 0:
+        return 0
+
+    if len(path.edges) != len(path.vertices) - 1:
+        raise ValueError("Invalid path: edges count mismatch")
+
+    dirs = infer_dirs_from_path(path.vertices, path.edges)
+
+    bits = _decode_bits_from_dirs(dirs)
+
+    n = 0
+    for b in bits:
+        n = (n << 1) | b
+    return n

bin2path/encode.py

@@ -0,0 +1,151 @@
+"""Encode a number into a 3D path using the L/R/U/D cellular-automaton scheme."""
+
+from bin2path.path import Path3D, PathMetadata
+from bin2path.orient import apply_step, Vec3
+
+
+def _get_bits_msb(n: int) -> list[int]:
+    """Return bits of n in MSB->LSB order."""
+    if n == 0:
+        return [0]
+    bits: list[int] = []
+    while n > 0:
+        bits.insert(0, n & 1)
+        n >>= 1
+    return bits
+
+
+START_FORWARD: Vec3 = (0, 0, 1)
+START_UP: Vec3 = (0, 1, 0)
+
+
+def _encode_dirs(bits: list[int]) -> list[str]:
+    """
+    Encode bit sequence (MSB first) into sequence of direction symbols L/R/U/D.
+
+    Rules:
+    - first bit:
+        0 -> L
+        1 -> R
+    - subsequent bits:
+        if bit == 0:
+            if previous step == L -> D
+            else -> L
+        if bit == 1:
+            if previous step == R -> U
+            else -> R
+    """
+    if not bits:
+        return []
+
+    dirs: list[str] = []
+
+    # first bit
+    first = bits[0]
+    cur_dir = "L" if first == 0 else "R"
+    dirs.append(cur_dir)
+
+    for b in bits[1:]:
+        if b == 0:
+            if cur_dir == "L":
+                cur_dir = "D"
+            else:
+                cur_dir = "L"
+        else:  # b == 1
+            if cur_dir == "R":
+                cur_dir = "U"
+            else:
+                cur_dir = "R"
+        dirs.append(cur_dir)
+
+    return dirs
+
+
+def _decode_bits_from_dirs(dirs: list[str]) -> list[int]:
+    """
+    Inverse of _encode_dirs with simplified rule:
+    - first step: L->0, R->1
+    - subsequent steps: (L,D)->0, (R,U)->1
+    """
+    if not dirs:
+        return [0]
+
+    bits: list[int] = []
+
+    first = dirs[0]
+    if first == "L":
+        bits.append(0)
+    elif first == "R":
+        bits.append(1)
+    else:
+        raise ValueError(f"Invalid first direction {first}, expected 'L' or 'R'")
+
+    for cur in dirs[1:]:
+        if cur in ("L", "D"):
+            bits.append(0)
+        elif cur in ("R", "U"):
+            bits.append(1)
+        else:
+            raise ValueError(f"Invalid direction symbol {cur}")
+
+    return bits
+
+
+def encode(number: int) -> Path3D:
+    """
+    Encode a natural number into a 3D path.
+
+    The binary representation (MSB first) is mapped to a sequence of symbols
+    L/R/U/D using the rules above. Symbols are then interpreted as *relative*
+    moves using a local orientation frame starting with forward=+Z and up=+Y.
+    """
+    if not isinstance(number, int):
+        raise TypeError(f"Expected integer, got {type(number).__name__}")
+    if number < 0:
+        raise ValueError("Number must be non-negative")
+
+    bits = _get_bits_msb(number)
+    bits_length = len(bits)
+
+    # trivial path for 0: stay at origin
+    if number == 0:
+        metadata = PathMetadata(
+            original_number=0,
+            bits_length=1,
+            first_one_pos=0,
+            step_positions=[],
+            start_direction=START_FORWARD,
+        )
+        return Path3D(vertices=[(0, 0, 0)], edges=[], metadata=metadata)
+
+    dirs = _encode_dirs(bits)
+
+    current_point: Vec3 = (0, 0, 0)
+    vertices: list[tuple[int, int, int]] = [current_point]
+    edges: list[tuple[int, int]] = []
+
+    forward = START_FORWARD
+    up = START_UP
+
+    for d in dirs:
+        vec, forward, up = apply_step(d, forward, up)
+        new_point = (
+            current_point[0] + vec[0],
+            current_point[1] + vec[1],
+            current_point[2] + vec[2],
+        )
+        vertices.append(new_point)
+        edges.append((len(vertices) - 2, len(vertices) - 1))
+        current_point = new_point
+
+    step_positions = [i for i, b in enumerate(bits) if b == 1]
+
+    metadata = PathMetadata(
+        original_number=number,
+        bits_length=bits_length,
+        first_one_pos=step_positions[0] if step_positions else 0,
+        step_positions=step_positions,
+        start_direction=START_FORWARD,
+    )
+
+    return Path3D(vertices=vertices, edges=edges, metadata=metadata)