bin2path 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- bin2path/__init__.py +48 -0
- bin2path/animate.py +237 -0
- bin2path/batch.py +38 -0
- bin2path/compare.py +139 -0
- bin2path/decode.py +33 -0
- bin2path/encode.py +151 -0
- bin2path/features.py +155 -0
- bin2path/orient.py +107 -0
- bin2path/path.py +70 -0
- bin2path/serialize.py +97 -0
- bin2path/validate.py +101 -0
- bin2path/visualize.py +380 -0
- bin2path-0.1.0.dist-info/METADATA +234 -0
- bin2path-0.1.0.dist-info/RECORD +17 -0
- bin2path-0.1.0.dist-info/WHEEL +5 -0
- bin2path-0.1.0.dist-info/licenses/LICENSE +21 -0
- bin2path-0.1.0.dist-info/top_level.txt +1 -0
bin2path/visualize.py
ADDED
|
@@ -0,0 +1,380 @@
|
|
|
1
|
+
"""Visualize a 3D path."""
|
|
2
|
+
|
|
3
|
+
from bin2path.path import Path3D
|
|
4
|
+
from bin2path.orient import infer_dirs_from_path
|
|
5
|
+
import matplotlib.pyplot as plt
|
|
6
|
+
import matplotlib.patches as mpatches
|
|
7
|
+
from mpl_toolkits.mplot3d import Axes3D # noqa: F401 # needed for 3d projection
|
|
8
|
+
import numpy as np
|
|
9
|
+
from typing import Optional, Dict
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
def visualize(
|
|
13
|
+
path: Path3D,
|
|
14
|
+
figsize: tuple[float, float] = (12, 10),
|
|
15
|
+
show_vertices: bool = True,
|
|
16
|
+
vertex_size: float = 30,
|
|
17
|
+
vertex_color: str = "#FF5733",
|
|
18
|
+
show_edges: bool = True,
|
|
19
|
+
edge_color: str = "#2E86AB",
|
|
20
|
+
edge_linewidth: float = 2.8,
|
|
21
|
+
min_edge_linewidth: float = 1.8,
|
|
22
|
+
edge_outline: bool = True,
|
|
23
|
+
edge_outline_color: Optional[str] = None,
|
|
24
|
+
edge_outline_width: float = 1.6,
|
|
25
|
+
show_start: bool = True,
|
|
26
|
+
start_color: str = "#28A745",
|
|
27
|
+
start_size: float = 100,
|
|
28
|
+
show_end: bool = True,
|
|
29
|
+
end_color: str = "#DC3545",
|
|
30
|
+
end_size: float = 100,
|
|
31
|
+
axis_equal: bool = True,
|
|
32
|
+
hide_axes: bool = False,
|
|
33
|
+
center: bool = False,
|
|
34
|
+
normalize: bool = False,
|
|
35
|
+
color_by_z: bool = True,
|
|
36
|
+
color_by_step: bool = True,
|
|
37
|
+
show_cube: bool = False,
|
|
38
|
+
auto_view: bool = False,
|
|
39
|
+
dark_theme: bool = False,
|
|
40
|
+
highlight_nodes: bool = True,
|
|
41
|
+
title: Optional[str] = None,
|
|
42
|
+
azim: float = -60,
|
|
43
|
+
elev: float = 30,
|
|
44
|
+
save_path: Optional[str] = None,
|
|
45
|
+
) -> None:
|
|
46
|
+
"""
|
|
47
|
+
Visualize a 3D path.
|
|
48
|
+
|
|
49
|
+
Args:
|
|
50
|
+
path: Path3D object to visualize.
|
|
51
|
+
figsize: Figure size (width, height).
|
|
52
|
+
show_vertices: Whether to show vertex markers.
|
|
53
|
+
vertex_size: Size of vertex markers.
|
|
54
|
+
vertex_color: Color of vertices.
|
|
55
|
+
show_edges: Whether to show edge lines.
|
|
56
|
+
edge_color: Color of edges.
|
|
57
|
+
edge_linewidth: Width of edge lines.
|
|
58
|
+
show_start: Whether to highlight start point.
|
|
59
|
+
start_color: Color of start point.
|
|
60
|
+
start_size: Size of start point marker.
|
|
61
|
+
show_end: Whether to highlight end point.
|
|
62
|
+
end_color: Color of end point.
|
|
63
|
+
end_size: Size of end point marker.
|
|
64
|
+
axis_equal: Whether to set equal axis scaling (before centering/normalizing).
|
|
65
|
+
hide_axes: If True, hide axes, ticks and grid (show pure figure).
|
|
66
|
+
center: If True, center vertices around origin before plotting.
|
|
67
|
+
normalize: If True, scale vertices to fit into [-1,1] cube.
|
|
68
|
+
color_by_z: If True, color vertices by their Z coordinate (depth cue).
|
|
69
|
+
color_by_step: If True, color edges by step type (L/R/U/D).
|
|
70
|
+
show_cube: If True, draw a wireframe cube around normalized figure.
|
|
71
|
+
title: Optional title for the plot.
|
|
72
|
+
azim: Azimuth angle for 3D view.
|
|
73
|
+
elev: Elevation angle for 3D view.
|
|
74
|
+
save_path: Optional path to save the figure.
|
|
75
|
+
"""
|
|
76
|
+
fig = plt.figure(figsize=figsize)
|
|
77
|
+
ax = fig.add_subplot(111, projection="3d")
|
|
78
|
+
|
|
79
|
+
# optional dark background for лучшего 3D-эффекта
|
|
80
|
+
if dark_theme:
|
|
81
|
+
fig.patch.set_facecolor("black")
|
|
82
|
+
ax.set_facecolor("black")
|
|
83
|
+
# на тёмном фоне тонкие линии хуже читаются
|
|
84
|
+
edge_linewidth *= 1.25
|
|
85
|
+
min_edge_linewidth *= 1.25
|
|
86
|
+
|
|
87
|
+
# outline settings (auto-contrast if color not provided)
|
|
88
|
+
if edge_outline_color is None:
|
|
89
|
+
edge_outline_color = "#FFFFFF" if dark_theme else "#000000"
|
|
90
|
+
|
|
91
|
+
# raw integer vertices for direction classification (L/R/U/D)
|
|
92
|
+
raw_vertices = np.array(path.vertices, dtype=float)
|
|
93
|
+
# working copy (may be centered/normalized for plotting)
|
|
94
|
+
vertices = raw_vertices.copy()
|
|
95
|
+
|
|
96
|
+
# Optional centering / normalization (to view figure "out of axes")
|
|
97
|
+
if center or normalize:
|
|
98
|
+
cx, cy, cz = vertices.mean(axis=0)
|
|
99
|
+
vertices[:, 0] -= cx
|
|
100
|
+
vertices[:, 1] -= cy
|
|
101
|
+
vertices[:, 2] -= cz
|
|
102
|
+
|
|
103
|
+
if normalize:
|
|
104
|
+
span = np.max(np.ptp(vertices, axis=0)) # max range among axes
|
|
105
|
+
if span > 0:
|
|
106
|
+
vertices /= span
|
|
107
|
+
|
|
108
|
+
# подготовка диапазона Z для глубинных эффектов
|
|
109
|
+
z_min = z_max = None
|
|
110
|
+
z_span = None
|
|
111
|
+
if len(vertices) > 0:
|
|
112
|
+
zs_all = vertices[:, 2]
|
|
113
|
+
z_min = float(zs_all.min())
|
|
114
|
+
z_max = float(zs_all.max())
|
|
115
|
+
z_span = z_max - z_min or 1.0
|
|
116
|
+
|
|
117
|
+
if show_edges and len(path.edges) > 0:
|
|
118
|
+
# Draw edges as lines, optionally colored by step type (L/R/U/D)
|
|
119
|
+
if color_by_step:
|
|
120
|
+
step_colors: Dict[str, str] = {
|
|
121
|
+
"L": "#FF5733", # orange/red
|
|
122
|
+
"R": "#2E86AB", # blue
|
|
123
|
+
"U": "#28A745", # green
|
|
124
|
+
"D": "#FFC300", # yellow
|
|
125
|
+
}
|
|
126
|
+
dirs = infer_dirs_from_path(path.vertices, path.edges)
|
|
127
|
+
for i, (from_idx, to_idx) in enumerate(path.edges):
|
|
128
|
+
sym = dirs[i] if i < len(dirs) else None
|
|
129
|
+
c = step_colors.get(sym or "", edge_color)
|
|
130
|
+
# draw using transformed vertices for correct placement
|
|
131
|
+
from_plot = vertices[from_idx]
|
|
132
|
+
to_plot = vertices[to_idx]
|
|
133
|
+
# простая глубинная подсветка по Z: ближе — толще и ярче
|
|
134
|
+
if z_span is not None:
|
|
135
|
+
z_mid = 0.5 * (from_plot[2] + to_plot[2])
|
|
136
|
+
depth_factor = 0.45 + 0.55 * ((z_mid - z_min) / z_span)
|
|
137
|
+
else:
|
|
138
|
+
depth_factor = 1.0
|
|
139
|
+
ax.plot(
|
|
140
|
+
[from_plot[0], to_plot[0]],
|
|
141
|
+
[from_plot[1], to_plot[1]],
|
|
142
|
+
[from_plot[2], to_plot[2]],
|
|
143
|
+
color=edge_outline_color if edge_outline else c,
|
|
144
|
+
linewidth=(
|
|
145
|
+
max(min_edge_linewidth, edge_linewidth * depth_factor)
|
|
146
|
+
+ (edge_outline_width if edge_outline else 0.0)
|
|
147
|
+
),
|
|
148
|
+
alpha=(0.75 + 0.25 * depth_factor) if edge_outline else (0.65 + 0.35 * depth_factor),
|
|
149
|
+
solid_capstyle="round",
|
|
150
|
+
solid_joinstyle="round",
|
|
151
|
+
antialiased=True,
|
|
152
|
+
)
|
|
153
|
+
if edge_outline:
|
|
154
|
+
ax.plot(
|
|
155
|
+
[from_plot[0], to_plot[0]],
|
|
156
|
+
[from_plot[1], to_plot[1]],
|
|
157
|
+
[from_plot[2], to_plot[2]],
|
|
158
|
+
color=c,
|
|
159
|
+
linewidth=max(min_edge_linewidth, edge_linewidth * depth_factor),
|
|
160
|
+
alpha=0.65 + 0.35 * depth_factor,
|
|
161
|
+
solid_capstyle="round",
|
|
162
|
+
solid_joinstyle="round",
|
|
163
|
+
antialiased=True,
|
|
164
|
+
)
|
|
165
|
+
else:
|
|
166
|
+
for from_idx, to_idx in path.edges:
|
|
167
|
+
from_v = vertices[from_idx]
|
|
168
|
+
to_v = vertices[to_idx]
|
|
169
|
+
if z_span is not None:
|
|
170
|
+
z_mid = 0.5 * (from_v[2] + to_v[2])
|
|
171
|
+
depth_factor = 0.45 + 0.55 * ((z_mid - z_min) / z_span)
|
|
172
|
+
else:
|
|
173
|
+
depth_factor = 1.0
|
|
174
|
+
ax.plot(
|
|
175
|
+
[from_v[0], to_v[0]],
|
|
176
|
+
[from_v[1], to_v[1]],
|
|
177
|
+
[from_v[2], to_v[2]],
|
|
178
|
+
color=edge_outline_color if edge_outline else edge_color,
|
|
179
|
+
linewidth=(
|
|
180
|
+
max(min_edge_linewidth, edge_linewidth * depth_factor)
|
|
181
|
+
+ (edge_outline_width if edge_outline else 0.0)
|
|
182
|
+
),
|
|
183
|
+
alpha=(0.75 + 0.25 * depth_factor) if edge_outline else (0.65 + 0.35 * depth_factor),
|
|
184
|
+
solid_capstyle="round",
|
|
185
|
+
solid_joinstyle="round",
|
|
186
|
+
antialiased=True,
|
|
187
|
+
)
|
|
188
|
+
if edge_outline:
|
|
189
|
+
ax.plot(
|
|
190
|
+
[from_v[0], to_v[0]],
|
|
191
|
+
[from_v[1], to_v[1]],
|
|
192
|
+
[from_v[2], to_v[2]],
|
|
193
|
+
color=edge_color,
|
|
194
|
+
linewidth=max(min_edge_linewidth, edge_linewidth * depth_factor),
|
|
195
|
+
alpha=0.65 + 0.35 * depth_factor,
|
|
196
|
+
solid_capstyle="round",
|
|
197
|
+
solid_joinstyle="round",
|
|
198
|
+
antialiased=True,
|
|
199
|
+
)
|
|
200
|
+
|
|
201
|
+
if show_vertices:
|
|
202
|
+
xs, ys, zs = vertices[:, 0], vertices[:, 1], vertices[:, 2]
|
|
203
|
+
if color_by_z:
|
|
204
|
+
# Нормализуем Z для цветовой карты, чтобы глубина была видна визуально
|
|
205
|
+
z_min_s, z_max_s = zs.min(), zs.max()
|
|
206
|
+
span = z_max_s - z_min_s or 1.0
|
|
207
|
+
colors = (zs - z_min_s) / span
|
|
208
|
+
sc = ax.scatter(
|
|
209
|
+
xs,
|
|
210
|
+
ys,
|
|
211
|
+
zs,
|
|
212
|
+
c=colors,
|
|
213
|
+
cmap="viridis",
|
|
214
|
+
s=vertex_size,
|
|
215
|
+
alpha=0.8,
|
|
216
|
+
depthshade=True,
|
|
217
|
+
)
|
|
218
|
+
else:
|
|
219
|
+
ax.scatter(
|
|
220
|
+
xs,
|
|
221
|
+
ys,
|
|
222
|
+
zs,
|
|
223
|
+
c=vertex_color,
|
|
224
|
+
s=vertex_size,
|
|
225
|
+
alpha=0.6,
|
|
226
|
+
depthshade=True,
|
|
227
|
+
)
|
|
228
|
+
|
|
229
|
+
# подсветка "узлов" — вершин, в которые путь входит несколько раз
|
|
230
|
+
if highlight_nodes and len(vertices) > 0:
|
|
231
|
+
coords_map: Dict[tuple[float, float, float], int] = {}
|
|
232
|
+
for vx, vy, vz in vertices:
|
|
233
|
+
key = (float(vx), float(vy), float(vz))
|
|
234
|
+
coords_map[key] = coords_map.get(key, 0) + 1
|
|
235
|
+
node_x, node_y, node_z = [], [], []
|
|
236
|
+
for (vx, vy, vz), cnt in coords_map.items():
|
|
237
|
+
if cnt > 1:
|
|
238
|
+
node_x.append(vx)
|
|
239
|
+
node_y.append(vy)
|
|
240
|
+
node_z.append(vz)
|
|
241
|
+
if node_x:
|
|
242
|
+
ax.scatter(
|
|
243
|
+
node_x,
|
|
244
|
+
node_y,
|
|
245
|
+
node_z,
|
|
246
|
+
c="#FFFFFF" if dark_theme else "#8E44AD",
|
|
247
|
+
s=vertex_size * 1.5,
|
|
248
|
+
alpha=0.9,
|
|
249
|
+
marker="o",
|
|
250
|
+
label="Nodes",
|
|
251
|
+
depthshade=False,
|
|
252
|
+
)
|
|
253
|
+
|
|
254
|
+
if show_start and len(vertices) > 0:
|
|
255
|
+
start = vertices[0]
|
|
256
|
+
ax.scatter(
|
|
257
|
+
[start[0]], [start[1]], [start[2]],
|
|
258
|
+
c=start_color,
|
|
259
|
+
s=start_size,
|
|
260
|
+
marker="o",
|
|
261
|
+
label="Start",
|
|
262
|
+
depthshade=False,
|
|
263
|
+
)
|
|
264
|
+
|
|
265
|
+
if show_end and len(vertices) > 1:
|
|
266
|
+
end = vertices[-1]
|
|
267
|
+
ax.scatter(
|
|
268
|
+
[end[0]], [end[1]], [end[2]],
|
|
269
|
+
c=end_color,
|
|
270
|
+
s=end_size,
|
|
271
|
+
marker="s",
|
|
272
|
+
label="End",
|
|
273
|
+
depthshade=False,
|
|
274
|
+
)
|
|
275
|
+
|
|
276
|
+
# Labels and title
|
|
277
|
+
if not hide_axes:
|
|
278
|
+
ax.set_xlabel("X")
|
|
279
|
+
ax.set_ylabel("Y")
|
|
280
|
+
ax.set_zlabel("Z")
|
|
281
|
+
|
|
282
|
+
if title is None:
|
|
283
|
+
title = f"bin2path: {path.metadata.original_number} (bits: {path.metadata.bits_length})"
|
|
284
|
+
ax.set_title(title, fontsize=14, fontweight="bold")
|
|
285
|
+
|
|
286
|
+
# Set viewing angle (with optional авто-подбором)
|
|
287
|
+
if auto_view and len(vertices) > 1:
|
|
288
|
+
# грубая эвристика: смотрим так, чтобы был виден и Z, и самые вытянутые оси
|
|
289
|
+
ranges = np.ptp(vertices, axis=0)
|
|
290
|
+
# если Z почти плоский, чуть больше сверху
|
|
291
|
+
if ranges[2] < 0.2 * max(ranges[0], ranges[1]):
|
|
292
|
+
use_elev, use_azim = 70, 45
|
|
293
|
+
else:
|
|
294
|
+
use_elev, use_azim = 30, 45
|
|
295
|
+
ax.view_init(elev=use_elev, azim=use_azim)
|
|
296
|
+
else:
|
|
297
|
+
ax.view_init(elev=elev, azim=azim)
|
|
298
|
+
|
|
299
|
+
# Equal aspect ratio
|
|
300
|
+
if axis_equal:
|
|
301
|
+
# Get the max range to set limits
|
|
302
|
+
max_range = np.max(np.abs(vertices).max(axis=0)) * 1.1
|
|
303
|
+
ax.set_xlim([-max_range, max_range])
|
|
304
|
+
ax.set_ylim([-max_range, max_range])
|
|
305
|
+
ax.set_zlim([-max_range, max_range])
|
|
306
|
+
|
|
307
|
+
# Optional wireframe cube to emphasize 3D space
|
|
308
|
+
if show_cube:
|
|
309
|
+
r = max_range if axis_equal else np.max(np.abs(vertices).max(axis=0)) * 1.1
|
|
310
|
+
# 8 cube vertices
|
|
311
|
+
corners = np.array(
|
|
312
|
+
[
|
|
313
|
+
[-r, -r, -r],
|
|
314
|
+
[r, -r, -r],
|
|
315
|
+
[r, r, -r],
|
|
316
|
+
[-r, r, -r],
|
|
317
|
+
[-r, -r, r],
|
|
318
|
+
[r, -r, r],
|
|
319
|
+
[r, r, r],
|
|
320
|
+
[-r, r, r],
|
|
321
|
+
]
|
|
322
|
+
)
|
|
323
|
+
# 12 edges of the cube
|
|
324
|
+
cube_edges = [
|
|
325
|
+
(0, 1),
|
|
326
|
+
(1, 2),
|
|
327
|
+
(2, 3),
|
|
328
|
+
(3, 0),
|
|
329
|
+
(4, 5),
|
|
330
|
+
(5, 6),
|
|
331
|
+
(6, 7),
|
|
332
|
+
(7, 4),
|
|
333
|
+
(0, 4),
|
|
334
|
+
(1, 5),
|
|
335
|
+
(2, 6),
|
|
336
|
+
(3, 7),
|
|
337
|
+
]
|
|
338
|
+
for i0, i1 in cube_edges:
|
|
339
|
+
p0, p1 = corners[i0], corners[i1]
|
|
340
|
+
ax.plot(
|
|
341
|
+
[p0[0], p1[0]],
|
|
342
|
+
[p0[1], p1[1]],
|
|
343
|
+
[p0[2], p1[2]],
|
|
344
|
+
color="#CCCCCC",
|
|
345
|
+
linewidth=0.5,
|
|
346
|
+
alpha=0.5,
|
|
347
|
+
)
|
|
348
|
+
|
|
349
|
+
# Add legend: Start/End + step type colors
|
|
350
|
+
handles = []
|
|
351
|
+
if show_start:
|
|
352
|
+
handles.append(mpatches.Patch(color=start_color, label="Start"))
|
|
353
|
+
if show_end:
|
|
354
|
+
handles.append(mpatches.Patch(color=end_color, label="End"))
|
|
355
|
+
|
|
356
|
+
if color_by_step:
|
|
357
|
+
# Same colors as in edge rendering
|
|
358
|
+
handles.extend(
|
|
359
|
+
[
|
|
360
|
+
mpatches.Patch(color="#FF5733", label="L (Left)"),
|
|
361
|
+
mpatches.Patch(color="#2E86AB", label="R (Right)"),
|
|
362
|
+
mpatches.Patch(color="#28A745", label="U (Up)"),
|
|
363
|
+
mpatches.Patch(color="#FFC300", label="D (Down)"),
|
|
364
|
+
]
|
|
365
|
+
)
|
|
366
|
+
|
|
367
|
+
if handles:
|
|
368
|
+
ax.legend(handles=handles, loc="upper left")
|
|
369
|
+
|
|
370
|
+
# Optionally hide axes / ticks / grid
|
|
371
|
+
if hide_axes:
|
|
372
|
+
ax.set_axis_off()
|
|
373
|
+
|
|
374
|
+
plt.tight_layout()
|
|
375
|
+
|
|
376
|
+
if save_path:
|
|
377
|
+
plt.savefig(save_path, dpi=150, bbox_inches="tight", facecolor="white")
|
|
378
|
+
print(f"Figure saved to {save_path}")
|
|
379
|
+
|
|
380
|
+
plt.show()
|
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: bin2path
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Transform numbers into 3D geometric paths - binary visualization
|
|
5
|
+
Author: bin2path
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Sett11/bin2path
|
|
8
|
+
Project-URL: Repository, https://github.com/Sett11/bin2path
|
|
9
|
+
Keywords: binary,3d,visualization,geometry,hashing
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Topic :: Scientific/Engineering :: Visualization
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Requires-Dist: matplotlib>=3.7.0
|
|
21
|
+
Requires-Dist: numpy>=1.24.0
|
|
22
|
+
Provides-Extra: dev
|
|
23
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
24
|
+
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
|
|
25
|
+
Requires-Dist: build>=1.2.0; extra == "dev"
|
|
26
|
+
Dynamic: license-file
|
|
27
|
+
|
|
28
|
+
# bin2path
|
|
29
|
+
|
|
30
|
+
Transform numbers into 3D geometric paths.
|
|
31
|
+
|
|
32
|
+
A Python library for converting natural numbers into 3D geometric shapes (spatial polylines on an integer lattice).
|
|
33
|
+
We use a **cellular-automaton scheme** that produces a sequence of symbolic steps `L/R/U/D`, and then interpret these steps as **local** (orientation-dependent) moves in 3D.
|
|
34
|
+
|
|
35
|
+
## Concept
|
|
36
|
+
|
|
37
|
+
Each number is represented as a 3D path on an integer lattice via a **discrete step rule**:
|
|
38
|
+
|
|
39
|
+
- We work with the binary representation **MSB → LSB** (left-to-right bits).
|
|
40
|
+
- Each bit is mapped to one of 4 **symbols**: `L/R/U/D`.
|
|
41
|
+
- Each symbol is then interpreted as a **relative 3D move** based on the current orientation (`forward/up/right`), so the path is not constrained to a plane.
|
|
42
|
+
|
|
43
|
+
### Bits → symbols (cellular automaton)
|
|
44
|
+
|
|
45
|
+
- **First bit**:
|
|
46
|
+
- `0` → first step `L`
|
|
47
|
+
- `1` → first step `R`
|
|
48
|
+
- **Each next bit** (only previous step matters):
|
|
49
|
+
- if bit = `0`:
|
|
50
|
+
- if previous step was `L` → current step `D`
|
|
51
|
+
- otherwise → `L`
|
|
52
|
+
- if bit = `1`:
|
|
53
|
+
- if previous step was `R` → current step `U`
|
|
54
|
+
- otherwise → `R`
|
|
55
|
+
|
|
56
|
+
### Symbols → 3D steps (local orientation)
|
|
57
|
+
|
|
58
|
+
We maintain a local frame:
|
|
59
|
+
|
|
60
|
+
- `forward` (where “go forward” points)
|
|
61
|
+
- `up` (local up)
|
|
62
|
+
- `right = cross(forward, up)`
|
|
63
|
+
|
|
64
|
+
Initial frame:
|
|
65
|
+
|
|
66
|
+
- `forward = (0, 0, 1)` (along +Z)
|
|
67
|
+
- `up = (0, 1, 0)` (along +Y)
|
|
68
|
+
|
|
69
|
+
Step semantics (rotate if needed, then move 1 unit along the new `forward`):
|
|
70
|
+
|
|
71
|
+
- `R`: move forward
|
|
72
|
+
- `L`: yaw left around `up`, then move forward
|
|
73
|
+
- `U`: pitch up around `right`, then move forward
|
|
74
|
+
- `D`: pitch down around `right`, then move forward
|
|
75
|
+
|
|
76
|
+
So the path is built from `(0,0,0)` by applying these steps.
|
|
77
|
+
|
|
78
|
+
The representation is:
|
|
79
|
+
- **Unique**: Different numbers produce different paths
|
|
80
|
+
- **Reversible**: You can decode the path back to the original number
|
|
81
|
+
- **Deterministic**: Same number always produces same path
|
|
82
|
+
|
|
83
|
+
## Installation
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
pip install bin2path
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Or from source:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
git clone https://github.com/Sett11/bin2path.git
|
|
93
|
+
cd bin2path
|
|
94
|
+
pip install -e .
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## Quick Start
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
import bin2path
|
|
101
|
+
|
|
102
|
+
# Encode a number to 3D path
|
|
103
|
+
path = bin2path.encode(42)
|
|
104
|
+
|
|
105
|
+
# Get path data
|
|
106
|
+
print(path.vertices) # list of (x,y,z)
|
|
107
|
+
print(path.edges) # list of (from_idx, to_idx)
|
|
108
|
+
|
|
109
|
+
# Decode back to number
|
|
110
|
+
number = bin2path.decode(path) # 42
|
|
111
|
+
|
|
112
|
+
# Visualize
|
|
113
|
+
bin2path.visualize(path)
|
|
114
|
+
|
|
115
|
+
# Extract features for clustering / analysis
|
|
116
|
+
f = bin2path.features(path)
|
|
117
|
+
print(f['path_length']) # number of steps
|
|
118
|
+
print(f['turns']) # number of direction changes (zeros)
|
|
119
|
+
print(f['straightness']) # ratio of direct to path distance
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Example: 8 = 1000
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
import bin2path
|
|
126
|
+
|
|
127
|
+
print(bin2path.encode(8).vertices)
|
|
128
|
+
# [(0, 0, 0), (0, 0, 1), (1, 0, 1), (1, -1, 1), (1, -1, 0)]
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## API Reference
|
|
132
|
+
|
|
133
|
+
### Core Functions
|
|
134
|
+
|
|
135
|
+
- `encode(number: int) -> Path3D` — Convert number to 3D path
|
|
136
|
+
- `decode(path: Path3D) -> int` — Convert path back to number
|
|
137
|
+
- `features(path: Path3D) -> dict` — Extract features for clustering
|
|
138
|
+
- `visualize(path: Path3D, **kwargs)` — Render 3D visualization
|
|
139
|
+
- `serialize(path) -> dict` — Convert to JSON-serializable dict
|
|
140
|
+
- `deserialize(data) -> Path3D` — Restore from dict
|
|
141
|
+
- `to_json(path) -> str` — Convert to JSON string
|
|
142
|
+
- `from_json(json_str) -> Path3D` — Parse JSON string
|
|
143
|
+
- `compare(path1, path2) -> dict` — Compare similarity between paths
|
|
144
|
+
- `validate(path) -> (bool, list[str])` — Validate path correctness
|
|
145
|
+
- `is_valid(path) -> bool` — Quick validity check
|
|
146
|
+
- `batch_encode(numbers) -> list[Path3D]` — Encode multiple numbers
|
|
147
|
+
- `batch_decode(paths) -> list[int]` — Decode multiple paths
|
|
148
|
+
|
|
149
|
+
### Path3D Structure
|
|
150
|
+
|
|
151
|
+
```python
|
|
152
|
+
@dataclass
|
|
153
|
+
class Path3D:
|
|
154
|
+
vertices: list[tuple[int, int, int]] # [(x,y,z), ...]
|
|
155
|
+
edges: list[tuple[int, int]] # [(from_idx, to_idx), ...]
|
|
156
|
+
metadata: PathMetadata # additional info
|
|
157
|
+
|
|
158
|
+
@dataclass
|
|
159
|
+
class PathMetadata:
|
|
160
|
+
original_number: int # original input number
|
|
161
|
+
bits_length: int # length of binary representation
|
|
162
|
+
first_one_pos: int # position of first 1-bit (MSB index)
|
|
163
|
+
step_positions: list[int] # positions of all 1-bits (MSB indices)
|
|
164
|
+
start_direction: tuple # starting forward direction (defaults to +Z)
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Features
|
|
168
|
+
|
|
169
|
+
The `features()` function returns a dictionary with:
|
|
170
|
+
|
|
171
|
+
- `path_length`: Number of edges/steps
|
|
172
|
+
- `turns`: Approximate number of bit-0 transitions (`bits_length - len(edges)`)
|
|
173
|
+
- `direct_distance`: Straight-line distance from start to end
|
|
174
|
+
- `straightness`: Ratio of direct distance to path length
|
|
175
|
+
- `center_x`, `center_y`, `center_z`: Center of mass coordinates
|
|
176
|
+
- `bbox_x`, `bbox_y`, `bbox_z`: Bounding box dimensions
|
|
177
|
+
- `displacement_x`, `displacement_y`, `displacement_z`: Total displacement
|
|
178
|
+
- `direction_histogram`: Count of steps in ±X/±Y/±Z directions
|
|
179
|
+
- `self_intersections`: Number of vertex revisits
|
|
180
|
+
|
|
181
|
+
## Examples
|
|
182
|
+
|
|
183
|
+
### Roundtrip Test
|
|
184
|
+
|
|
185
|
+
```python
|
|
186
|
+
import bin2path
|
|
187
|
+
|
|
188
|
+
test_numbers = [0, 1, 2, 42, 100, 12345, 2**10, 999999]
|
|
189
|
+
for n in test_numbers:
|
|
190
|
+
path = bin2path.encode(n)
|
|
191
|
+
decoded = bin2path.decode(path)
|
|
192
|
+
assert decoded == n # Always True!
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### Visualization Options
|
|
196
|
+
|
|
197
|
+
```python
|
|
198
|
+
import bin2path
|
|
199
|
+
|
|
200
|
+
path = bin2path.encode(42)
|
|
201
|
+
|
|
202
|
+
# Basic visualization
|
|
203
|
+
bin2path.visualize(path)
|
|
204
|
+
|
|
205
|
+
# Custom appearance
|
|
206
|
+
bin2path.visualize(
|
|
207
|
+
path,
|
|
208
|
+
figsize=(10, 8),
|
|
209
|
+
vertex_color="red",
|
|
210
|
+
edge_color="blue",
|
|
211
|
+
edge_linewidth=3,
|
|
212
|
+
vertex_size=50,
|
|
213
|
+
)
|
|
214
|
+
|
|
215
|
+
# Save to file
|
|
216
|
+
bin2path.visualize(path, save_path="my_path.png")
|
|
217
|
+
|
|
218
|
+
# Different viewing angle
|
|
219
|
+
bin2path.visualize(path, azim=45, elev=30)
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## Requirements
|
|
223
|
+
|
|
224
|
+
- Python >= 3.10
|
|
225
|
+
- matplotlib >= 3.7.0
|
|
226
|
+
- numpy >= 1.24.0
|
|
227
|
+
|
|
228
|
+
## License
|
|
229
|
+
|
|
230
|
+
MIT License
|
|
231
|
+
|
|
232
|
+
## See Also
|
|
233
|
+
|
|
234
|
+
See [`plan.md`](plan.md) for the detailed specification of the scheme (including the local-orientation rules).
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
bin2path/__init__.py,sha256=627z-Mtlgu21o7m2XkTxZJSzTSv-Tx9QmfrJh1LdR5M,1305
|
|
2
|
+
bin2path/animate.py,sha256=MYQP6CHCkHG5-qJCCH_uWrgNJZfiP8snE2yudvzlRaY,7371
|
|
3
|
+
bin2path/batch.py,sha256=yZkKeIDHDTb4vyM3WAn9PQHXR9w-K2gS9bIk9MXBCWI,850
|
|
4
|
+
bin2path/compare.py,sha256=Aa_kYRrO4V_kjkFssaoesxg_w2S5NJLGnLiSGl2nvgg,4097
|
|
5
|
+
bin2path/decode.py,sha256=Gh9MdUvsHQYTytK85edYlBwm5eoZk4xdvjyOONNIl-Q,899
|
|
6
|
+
bin2path/encode.py,sha256=4ldZzRzw7ZBVtqS2oyWMl4ateRdF3pEGzViueNmCNlU,3909
|
|
7
|
+
bin2path/features.py,sha256=Lpiu_YWjTc8ip77na8hhO0qcuNtUr_IwCAb2PrNAiDM,4472
|
|
8
|
+
bin2path/orient.py,sha256=bYh6XuF_hrg2GKhDrPkwzYB-QdddAVd3_3lA6qxyN0E,3016
|
|
9
|
+
bin2path/path.py,sha256=g6MYUm1pPT6qlRyq9D_4IoJ1W440K1kh8BnmeH2Kzp0,2401
|
|
10
|
+
bin2path/serialize.py,sha256=x4nVXFWp0mIyCzAv7chygJq5xCfCmuLm6trfx5t5qLQ,2611
|
|
11
|
+
bin2path/validate.py,sha256=3SXE8j8q_IIkfcaRQisl1tIObqo0eLRAtrTmjhahzRE,3350
|
|
12
|
+
bin2path/visualize.py,sha256=WVmyKwQo3S3C0IZTnDac40cU2TZXr1DGPaMh78IwRcI,13911
|
|
13
|
+
bin2path-0.1.0.dist-info/licenses/LICENSE,sha256=fhQbkSI0Ns-8wXuiGbFGIHWgr4YvtU8tf7oafdrNI_s,1078
|
|
14
|
+
bin2path-0.1.0.dist-info/METADATA,sha256=VuJwrYYRN7WmINXggk8LaHIVKd9QCD6H_-wv9yyXCv4,7007
|
|
15
|
+
bin2path-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
|
|
16
|
+
bin2path-0.1.0.dist-info/top_level.txt,sha256=6UZrteOSkVzQO-noNNRUnsn7fEZmaH8IubrI0LTgAwc,9
|
|
17
|
+
bin2path-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 bin2path contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
bin2path
|