bin2path 0.1.0__py3-none-any.whl

bin2path/features.py

@@ -0,0 +1,155 @@
+"""Extract features from a path for clustering."""
+
+from bin2path.path import Path3D
+import numpy as np
+
+
+def features(path: Path3D) -> dict:
+    """
+    Extract features from a 3D path for clustering.
+    
+    Args:
+        path: A Path3D object.
+        
+    Returns:
+        Dictionary with feature values.
+    """
+    vertices = np.array(path.vertices)
+    edges = path.edges
+    
+    # Basic metrics
+    num_vertices = len(vertices)
+    num_edges = len(edges)
+    
+    # Path length (number of steps)
+    path_length = num_edges
+    
+    # Calculate turn count from edges
+    turns = _count_turns(path)
+    
+    # Center of mass
+    center = vertices.mean(axis=0)
+    
+    # Bounding box
+    min_coords = vertices.min(axis=0)
+    max_coords = vertices.max(axis=0)
+    bbox_size = max_coords - min_coords
+    
+    # Start and end points
+    start = path.vertices[0]
+    end = path.vertices[-1]
+    displacement = (
+        end[0] - start[0],
+        end[1] - start[1],
+        end[2] - start[2],
+    )
+    direct_distance = np.linalg.norm(displacement)
+    
+    # Direction histogram
+    dir_histogram = _direction_histogram(path)
+    
+    # Self-intersections (simplified check)
+    self_intersections = _count_self_intersections(path)
+    
+    # Straight segment lengths histogram
+    straight_segments = _straight_segment_lengths(path)
+    
+    return {
+        "path_length": path_length,
+        "turns": turns,
+        "vertices_count": num_vertices,
+        "center_x": float(center[0]),
+        "center_y": float(center[1]),
+        "center_z": float(center[2]),
+        "bbox_x": float(bbox_size[0]),
+        "bbox_y": float(bbox_size[1]),
+        "bbox_z": float(bbox_size[2]),
+        "displacement_x": displacement[0],
+        "displacement_y": displacement[1],
+        "displacement_z": displacement[2],
+        "direct_distance": direct_distance,
+        "straightness": direct_distance / num_edges if num_edges > 0 else 0,
+        "direction_histogram": dir_histogram,
+        "self_intersections": self_intersections,
+        "straight_segments": straight_segments,
+        "original_number": path.metadata.original_number,
+        "bits_length": path.metadata.bits_length,
+    }
+
+
+def _count_turns(path: Path3D) -> int:
+    """Count the number of direction changes (bits = 0)."""
+    # Turns = total bits - number of steps (edges) = bits_length - num_edges
+    # Это количество битов которые были 0
+    return path.metadata.bits_length - len(path.edges)
+
+
+def _direction_histogram(path: Path3D) -> dict:
+    """Count steps in each of 6 directions."""
+    histogram = {"+X": 0, "-X": 0, "+Y": 0, "-Y": 0, "+Z": 0, "-Z": 0}
+    
+    for from_idx, to_idx in path.edges:
+        from_v = path.vertices[from_idx]
+        to_v = path.vertices[to_idx]
+        dx = to_v[0] - from_v[0]
+        dy = to_v[1] - from_v[1]
+        dz = to_v[2] - from_v[2]
+        
+        if dx == 1:
+            histogram["+X"] += 1
+        elif dx == -1:
+            histogram["-X"] += 1
+        elif dy == 1:
+            histogram["+Y"] += 1
+        elif dy == -1:
+            histogram["-Y"] += 1
+        elif dz == 1:
+            histogram["+Z"] += 1
+        elif dz == -1:
+            histogram["-Z"] += 1
+    
+    return histogram
+
+
+def _count_self_intersections(path: Path3D) -> int:
+    """Count vertex revisits (simple intersection check)."""
+    seen = {}
+    intersections = 0
+    
+    for i, v in enumerate(path.vertices):
+        if v in seen:
+            intersections += 1
+        else:
+            seen[v] = i
+    
+    return intersections
+
+
+def _straight_segment_lengths(path: Path3D) -> dict:
+    """Histogram of straight segment lengths along any single axis."""
+    lengths: list[int] = []
+    current_length = 0
+    current_dir: tuple[int, int, int] | None = None
+
+    for from_idx, to_idx in path.edges:
+        from_v = path.vertices[from_idx]
+        to_v = path.vertices[to_idx]
+        edge_dir = (to_v[0] - from_v[0], to_v[1] - from_v[1], to_v[2] - from_v[2])
+
+        if current_dir is None or edge_dir == current_dir:
+            current_length += 1
+            current_dir = edge_dir
+        else:
+            if current_length > 0:
+                lengths.append(current_length)
+            current_length = 1
+            current_dir = edge_dir
+
+    if current_length > 0:
+        lengths.append(current_length)
+
+    hist: dict[int, int] = {}
+    for l in lengths:
+        hist[l] = hist.get(l, 0) + 1
+
+    return hist

bin2path/orient.py

@@ -0,0 +1,107 @@
+"""Orientation (local frame) utilities for bin2path.
+
+We interpret symbolic steps L/R/U/D as *relative* moves based on a current
+orientation defined by two orthonormal axis-aligned vectors:
+- forward: where "R" moves (go forward)
+- up: local up direction (used as yaw axis)
+
+Right vector is computed as cross(forward, up) (right-hand rule).
+
+Step semantics (each step includes the move):
+- R: move forward
+- L: yaw left  (rotate forward 90° around up), then move forward
+- U: pitch up  (rotate forward 90° around right), then move forward
+- D: pitch down(rotate forward 90° around right), then move forward
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Iterable, List, Tuple
+
+Vec3 = Tuple[int, int, int]
+
+
+def _cross(a: Vec3, b: Vec3) -> Vec3:
+    ax, ay, az = a
+    bx, by, bz = b
+    return (ay * bz - az * by, az * bx - ax * bz, ax * by - ay * bx)
+
+
+def _neg(v: Vec3) -> Vec3:
+    return (-v[0], -v[1], -v[2])
+
+
+def apply_step(sym: str, forward: Vec3, up: Vec3) -> tuple[Vec3, Vec3, Vec3]:
+    """Apply a symbolic step and return (delta, new_forward, new_up)."""
+    if sym not in ("L", "R", "U", "D"):
+        raise ValueError(f"Invalid direction symbol {sym}")
+
+    right = _cross(forward, up)
+
+    if sym == "R":
+        new_forward = forward
+        new_up = up
+        delta = new_forward
+        return delta, new_forward, new_up
+
+    if sym == "L":
+        # yaw left around up: forward -> -right
+        new_forward = _neg(right)
+        new_up = up
+        delta = new_forward
+        return delta, new_forward, new_up
+
+    if sym == "U":
+        # pitch up around right: forward -> up, up -> -forward
+        new_forward = up
+        new_up = _neg(forward)
+        delta = new_forward
+        return delta, new_forward, new_up
+
+    # sym == "D"
+    # pitch down around right: forward -> -up, up -> forward
+    new_forward = _neg(up)
+    new_up = forward
+    delta = new_forward
+    return delta, new_forward, new_up
+
+
+def infer_dirs_from_path(vertices: Iterable[Vec3], edges: Iterable[tuple[int, int]]) -> List[str]:
+    """Infer L/R/U/D symbols from a path using the local-frame rules."""
+    verts = list(vertices)
+    eds = list(edges)
+    if not verts:
+        return []
+    if not eds:
+        return []
+
+    forward: Vec3 = (0, 0, 1)
+    up: Vec3 = (0, 1, 0)
+
+    dirs: List[str] = []
+    for from_idx, to_idx in eds:
+        fv = verts[from_idx]
+        tv = verts[to_idx]
+        vec: Vec3 = (tv[0] - fv[0], tv[1] - fv[1], tv[2] - fv[2])
+
+        right = _cross(forward, up)
+        candidates: Dict[str, Vec3] = {
+            "R": forward,
+            "L": _neg(right),
+            "U": up,
+            "D": _neg(up),
+        }
+
+        sym = None
+        for k, v in candidates.items():
+            if vec == v:
+                sym = k
+                break
+        if sym is None:
+            raise ValueError(f"Unknown step vector {vec}, cannot infer direction symbol")
+
+        dirs.append(sym)
+        _, forward, up = apply_step(sym, forward, up)
+
+    return dirs
+

bin2path/path.py

@@ -0,0 +1,70 @@
+"""Core data structures for bin2path."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class PathMetadata:
+    """Metadata for a 3D path."""
+    original_number: int
+    bits_length: int
+    first_one_pos: int = 0  # position of first 1-bit (number of leading zeros)
+    step_positions: list[int] = None  # positions of all 1-bits
+    # Start forward direction used by the encoding/decoding scheme (defaults to +Z)
+    start_direction: tuple[int, int, int] = (0, 0, 1)
+    
+    def __post_init__(self):
+        if self.step_positions is None:
+            self.step_positions = []
+
+
+@dataclass
+class Path3D:
+    """
+    3D path representation.
+    
+    Attributes:
+        vertices: List of (x, y, z) tuples representing path vertices.
+        edges: List of (from_idx, to_idx) tuples representing directed edges.
+        metadata: Additional metadata about the path.
+    """
+    vertices: list[tuple[int, int, int]]
+    edges: list[tuple[int, int]]
+    metadata: PathMetadata
+    
+    def __post_init__(self):
+        if not self.vertices:
+            raise ValueError("Path must have at least one vertex")
+        if len(self.edges) != len(self.vertices) - 1:
+            raise ValueError("Number of edges must be equal to vertices count minus 1")
+        if self.metadata.bits_length < len(self.edges):
+            raise ValueError(
+                "Invalid metadata: bits_length must be >= number of edges "
+                f"(bits_length={self.metadata.bits_length}, edges={len(self.edges)})"
+            )
+    
+    @property
+    def start(self) -> tuple[int, int, int]:
+        """Return the starting vertex."""
+        return self.vertices[0] if self.vertices else (0, 0, 0)
+    
+    @property
+    def end(self) -> tuple[int, int, int]:
+        """Return the ending vertex."""
+        return self.vertices[-1] if self.vertices else (0, 0, 0)
+    
+    @property
+    def num_steps(self) -> int:
+        """Return the number of steps (edges) in the path."""
+        return len(self.edges)
+    
+    @property
+    def num_turns(self) -> int:
+        """
+        Return the number of turn bits (0-bits) in the encoding.
+
+        In this scheme, 1-bits produce forward steps (edges), and 0-bits produce turns.
+        Since each bit corresponds to one symbolic action, the turn count is:
+        turns = bits_length - edges_count
+        """
+        return self.metadata.bits_length - len(self.edges)

bin2path/serialize.py

@@ -0,0 +1,97 @@
+"""Serialize and deserialize Path3D objects."""
+
+import json
+from bin2path.path import Path3D, PathMetadata
+
+
+def serialize(path: Path3D) -> dict:
+    """
+    Serialize a Path3D object to a dictionary (JSON-compatible).
+    
+    Args:
+        path: Path3D object.
+        
+    Returns:
+        Dictionary representation.
+    """
+    return {
+        "vertices": path.vertices,
+        "edges": path.edges,
+        "metadata": {
+            "original_number": path.metadata.original_number,
+            "bits_length": path.metadata.bits_length,
+            "first_one_pos": path.metadata.first_one_pos,
+            "step_positions": path.metadata.step_positions,
+            "start_direction": path.metadata.start_direction,
+        },
+    }
+
+
+def deserialize(data: dict) -> Path3D:
+    """
+    Deserialize a dictionary to a Path3D object.
+    
+    Args:
+        data: Dictionary with 'vertices', 'edges', 'metadata' keys.
+        
+    Returns:
+        Path3D object.
+        
+    Raises:
+        ValueError: If data is invalid.
+    """
+    if not isinstance(data, dict):
+        raise TypeError("Data must be a dictionary")
+    
+    if "vertices" not in data or "edges" not in data or "metadata" not in data:
+        raise ValueError("Data must contain 'vertices', 'edges', and 'metadata'")
+    
+    vertices = data["vertices"]
+    edges = data["edges"]
+    metadata = data["metadata"]
+    
+    # Validate structure
+    if not isinstance(vertices, list) or not isinstance(edges, list):
+        raise ValueError("Vertices and edges must be lists")
+    
+    # Convert to tuples
+    vertices = [tuple(v) for v in vertices]
+    edges = [tuple(e) for e in edges]
+    
+    path_metadata = PathMetadata(
+        original_number=metadata.get("original_number", 0),
+        bits_length=metadata.get("bits_length", 0),
+        first_one_pos=metadata.get("first_one_pos", 0),
+        step_positions=metadata.get("step_positions", []),
+        start_direction=tuple(metadata.get("start_direction", (1, 0, 0))),
+    )
+    
+    return Path3D(vertices=vertices, edges=edges, metadata=path_metadata)
+
+
+def to_json(path: Path3D, indent: int = 2) -> str:
+    """
+    Convert Path3D to JSON string.
+    
+    Args:
+        path: Path3D object.
+        indent: JSON indentation level.
+        
+    Returns:
+        JSON string.
+    """
+    return json.dumps(serialize(path), indent=indent)
+
+
+def from_json(json_str: str) -> Path3D:
+    """
+    Parse JSON string to Path3D.
+    
+    Args:
+        json_str: JSON string.
+        
+    Returns:
+        Path3D object.
+    """
+    data = json.loads(json_str)
+    return deserialize(data)

bin2path/validate.py

@@ -0,0 +1,101 @@
+"""Validate Path3D objects."""
+
+from bin2path.path import Path3D
+
+
+def validate(path: Path3D) -> tuple[bool, list[str]]:
+    """
+    Validate a Path3D object.
+    
+    Args:
+        path: Path3D object to validate.
+        
+    Returns:
+        Tuple of (is_valid, list_of_errors).
+    """
+    errors = []
+    
+    # Check vertices exist
+    if not path.vertices:
+        errors.append("Path must have at least one vertex")
+        return False, errors
+    
+    # Check vertices are valid tuples
+    for i, v in enumerate(path.vertices):
+        if not isinstance(v, (tuple, list)) or len(v) != 3:
+            errors.append(f"Vertex {i} must be a 3D coordinate tuple")
+        elif not all(isinstance(c, int) for c in v):
+            errors.append(f"Vertex {i} coordinates must be integers")
+    
+    # Check edges exist
+    # Special-case: allow the trivial path for 0 (single vertex, no edges)
+    if not path.edges:
+        if len(path.vertices) == 1 and path.metadata and path.metadata.bits_length == 1:
+            if errors:
+                return False, errors
+            return True, []
+        errors.append("Path must have at least one edge (two vertices), unless it is the trivial 0-path")
+        return False, errors
+    
+    # Check edges are valid
+    for i, e in enumerate(path.edges):
+        if not isinstance(e, (tuple, list)) or len(e) != 2:
+            errors.append(f"Edge {i} must be a tuple of two indices")
+            continue
+        
+        from_idx, to_idx = e
+        
+        if from_idx < 0 or from_idx >= len(path.vertices):
+            errors.append(f"Edge {i}: from_index {from_idx} out of range")
+        if to_idx < 0 or to_idx >= len(path.vertices):
+            errors.append(f"Edge {i}: to_index {to_idx} out of range")
+        
+        # Check edge direction is valid (must be one of 6 axis-aligned unit directions)
+        if from_idx < len(path.vertices) and to_idx < len(path.vertices):
+            from_v = path.vertices[from_idx]
+            to_v = path.vertices[to_idx]
+            edge_dir = (
+                to_v[0] - from_v[0],
+                to_v[1] - from_v[1],
+                to_v[2] - from_v[2],
+            )
+            if edge_dir not in {
+                (-1, 0, 0),
+                (1, 0, 0),
+                (0, 1, 0),
+                (0, -1, 0),
+                (0, 0, 1),
+                (0, 0, -1),
+            }:
+                errors.append(f"Edge {i}: invalid direction {edge_dir}")
+    
+    # Check edge count matches vertices - 1
+    if len(path.edges) != len(path.vertices) - 1:
+        errors.append(f"Edges count ({len(path.edges)}) must equal vertices count ({len(path.vertices)}) - 1")
+    
+    # Check metadata
+    if not path.metadata:
+        errors.append("Path must have metadata")
+    elif path.metadata.bits_length <= 0:
+        errors.append("bits_length must be positive")
+    
+    # Check path is connected (simple check)
+    for i in range(len(path.edges) - 1):
+        if path.edges[i][1] != path.edges[i + 1][0]:
+            errors.append(f"Path is not continuous at edge {i}")
+    
+    is_valid = len(errors) == 0
+    return is_valid, errors
+
+
+def is_valid(path: Path3D) -> bool:
+    """
+    Quick validation check.
+    
+    Args:
+        path: Path3D object.
+        
+    Returns:
+        True if valid, False otherwise.
+    """
+    return validate(path)[0]