vixar 1.0.0__tar.gz

vixar-1.0.0/.gitignore

@@ -0,0 +1,38 @@
+# Node
+node_modules/
+dist/
+*.tsbuildinfo
+.pnpm-store/
+
+# Vite
+.vite/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+.pytest_cache/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+
+# Built viewer bundle (produced by CI from packages/engine + apps/viewer)
+python/src/vixar/static/viewer.js
+python/src/vixar/static/viewer.js.map
+
+# Notebooks
+.ipynb_checkpoints/
+
+# OS / editor
+.DS_Store
+Thumbs.db
+.idea/
+*.log
+
+# Test artifacts
+coverage/
+playwright-report/
+test-results/

vixar-1.0.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: vixar
+Version: 1.0.0
+Summary: Proprietary geoscientific 3D/2D visualization engine, distributed as a Python library.
+Author: Vixar
+License: Proprietary
+Keywords: geoscience,mining,point-cloud,visualization,webgl
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: anywidget>=0.9
+Requires-Dist: fastapi>=0.110
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyproj>=3.5
+Requires-Dist: uvicorn>=0.27
+Provides-Extra: all
+Requires-Dist: laspy>=2.5; extra == 'all'
+Requires-Dist: lazrs>=0.5; extra == 'all'
+Requires-Dist: meshio>=5.3; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Provides-Extra: las
+Requires-Dist: laspy>=2.5; extra == 'las'
+Requires-Dist: lazrs>=0.5; extra == 'las'
+Provides-Extra: mesh
+Requires-Dist: meshio>=5.3; extra == 'mesh'
+Description-Content-Type: text/markdown
+
+# Vixar
+
+Proprietary geoscientific 3D/2D visualization engine, distributed as a Python library.
+
+```python
+import vixar as vx
+
+viewer = vx.Viewer(width=1200, height=800, theme="dark")
+viewer.add_point_cloud("survey.csv", color_by="elevation", cmap="terrain")
+viewer.add_boreholes(
+    "drillholes.csv",
+    id_col="HOLE_ID", x_col="X", y_col="Y", z_col="Z", from_col="FROM",
+    color_by="au_ppm", cmap="hot",
+)
+viewer.show()            # inline Jupyter widget
+viewer.serve(port=8050)  # local web server (iframe-embeddable)
+viewer.to_html("scene.html")  # standalone HTML
+```
+
+`pip install vixar` — no Node.js required for end users. The WebGL2 engine ships
+as a bundled `viewer.js` static asset.
+
+## Development
+
+The JS engine lives in the monorepo at the repo root. Build the bundle before
+running the Python package from source:
+
+```bash
+pnpm install
+pnpm build:viewer          # -> python/src/vixar/static/viewer.js
+cd python && pip install -e ".[dev]"
+pytest
+```
+
+This is a Phase 1 build (CSV point clouds + boreholes, colour legend, UTM
+origin, Jupyter/serve/HTML output). See `../plan_v2.md` for the full roadmap.

vixar-1.0.0/README.md

@@ -0,0 +1,36 @@
+# Vixar
+
+Proprietary geoscientific 3D/2D visualization engine, distributed as a Python library.
+
+```python
+import vixar as vx
+
+viewer = vx.Viewer(width=1200, height=800, theme="dark")
+viewer.add_point_cloud("survey.csv", color_by="elevation", cmap="terrain")
+viewer.add_boreholes(
+    "drillholes.csv",
+    id_col="HOLE_ID", x_col="X", y_col="Y", z_col="Z", from_col="FROM",
+    color_by="au_ppm", cmap="hot",
+)
+viewer.show()            # inline Jupyter widget
+viewer.serve(port=8050)  # local web server (iframe-embeddable)
+viewer.to_html("scene.html")  # standalone HTML
+```
+
+`pip install vixar` — no Node.js required for end users. The WebGL2 engine ships
+as a bundled `viewer.js` static asset.
+
+## Development
+
+The JS engine lives in the monorepo at the repo root. Build the bundle before
+running the Python package from source:
+
+```bash
+pnpm install
+pnpm build:viewer          # -> python/src/vixar/static/viewer.js
+cd python && pip install -e ".[dev]"
+pytest
+```
+
+This is a Phase 1 build (CSV point clouds + boreholes, colour legend, UTM
+origin, Jupyter/serve/HTML output). See `../plan_v2.md` for the full roadmap.

vixar-1.0.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vixar"
+version = "1.0.0"
+description = "Proprietary geoscientific 3D/2D visualization engine, distributed as a Python library."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [{ name = "Vixar" }]
+keywords = ["geoscience", "visualization", "webgl", "point-cloud", "mining"]
+classifiers = [
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Intended Audience :: Science/Research",
+  "Topic :: Scientific/Engineering :: Visualization",
+]
+
+dependencies = [
+  "numpy>=1.24",
+  "pandas>=2.0",
+  "pydantic>=2.5",
+  "pyproj>=3.5",
+  "anywidget>=0.9",
+  "fastapi>=0.110",
+  "uvicorn>=0.27",
+]
+
+[project.optional-dependencies]
+# 'lazrs' is a pure-Rust LAZ backend with prebuilt wheels for all platforms
+# (no system LASzip needed), so `vixar[las]` reads both .las and .laz.
+las = ["laspy>=2.5", "lazrs>=0.5"]
+mesh = ["meshio>=5.3"]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "httpx>=0.27",
+  "ruff>=0.6",
+]
+docs = [
+  "mkdocs-material>=9.5",
+  "mkdocstrings[python]>=0.26",
+]
+all = ["vixar[las,mesh]"]
+
+[project.scripts]
+vixar = "vixar.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/vixar"]
+artifacts = ["src/vixar/static/viewer.js", "src/vixar/static/viewer.js.map"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/vixar", "README.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

vixar-1.0.0/src/vixar/__init__.py

@@ -0,0 +1,17 @@
+"""Vixar — proprietary geoscientific 3D/2D visualization engine (Python library).
+
+    import vixar as vx
+    viewer = vx.Viewer()
+    viewer.add_point_cloud("survey.csv", color_by="elevation")
+    viewer.show()
+"""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+
+from vixar.layers import LayerRef
+from vixar.schema import SCHEMA_VERSION, SceneConfig
+from vixar.viewer import Viewer
+
+__all__ = ["Viewer", "LayerRef", "SceneConfig", "SCHEMA_VERSION", "__version__"]

vixar-1.0.0/src/vixar/cli.py

@@ -0,0 +1,76 @@
+"""Vixar command-line interface (plan §6).
+
+Provides ``vixar tile`` for spatial pre-tiling (Phase 3) and
+``vixar --version``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from vixar import __version__
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="vixar", description="Vixar geoscientific viewer.")
+    parser.add_argument("--version", action="version", version=f"vixar {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    tile_p = sub.add_parser(
+        "tile",
+        help="Split a LAS file into spatial tiles for streaming (Phase 3).",
+    )
+    tile_p.add_argument("input", help="Path to the source LAS file.")
+    tile_p.add_argument(
+        "--output", "-o", default="./tiles/",
+        help="Output directory for tile files and meta.json (default: ./tiles/).",
+    )
+    tile_p.add_argument(
+        "--tile-size", type=float, default=100.0,
+        help="Spatial cell size in metres (default: 100).",
+    )
+    tile_p.add_argument(
+        "--color-by",
+        help="Point attribute to encode as per-point values (e.g. elevation, intensity).",
+    )
+    tile_p.add_argument(
+        "--lod-factor", type=int, default=4,
+        help="Every N-th point is written to the coarse LOD tile (default: 4).",
+    )
+    tile_p.add_argument(
+        "--quiet", "-q", action="store_true",
+        help="Suppress progress output.",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "tile":
+        try:
+            from vixar.tiler import tile_point_cloud
+            tile_point_cloud(
+                args.input,
+                output_dir=args.output,
+                tile_size=args.tile_size,
+                color_by=args.color_by,
+                lod_factor=args.lod_factor,
+                verbose=not args.quiet,
+            )
+            return 0
+        except ImportError as exc:
+            print(
+                f"Error: {exc}\n"
+                "Install the LAS dependency with: pip install 'vixar[las]'",
+                file=sys.stderr,
+            )
+            return 1
+        except Exception as exc:  # noqa: BLE001
+            print(f"Error: {exc}", file=sys.stderr)
+            return 1
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

vixar-1.0.0/src/vixar/errors.py

@@ -0,0 +1,32 @@
+"""Vixar exception hierarchy with clear, user-facing messages (plan Phase 1/2)."""
+
+from __future__ import annotations
+
+
+class VixarError(Exception):
+    """Base class for all Vixar errors."""
+
+
+class InputValidationError(VixarError):
+    """Raised for bad user input: missing columns, wrong shapes, bad files."""
+
+
+class LAZBackendError(VixarError):
+    """Raised when a ``.laz`` file is read but no decompression backend is installed.
+
+    LAZ (LASzip-compressed LAS) is decompressed by ``laspy`` using a pluggable
+    backend. ``vixar[las]`` ships the pure-Python-installable ``lazrs`` backend;
+    this error means none is importable at read time.
+    """
+
+    def __init__(self, path: str | None = None) -> None:
+        where = f" ({path})" if path else ""
+        super().__init__(
+            f"Reading LAZ files{where} requires a LAZ decompression backend. "
+            "Install one with: pip install 'vixar[las]'  (bundles 'lazrs'), "
+            "or pip install lazrs  (or laszip)."
+        )
+
+
+class UnsupportedEPSGError(VixarError):
+    """Raised when a CRS/EPSG code cannot be resolved by pyproj."""

vixar-1.0.0/src/vixar/html.py

@@ -0,0 +1,50 @@
+"""Standalone HTML generation (plan Phase 1: ``viewer.to_html``).
+
+Produces a self-contained page: the bundled viewer.js inlined as a <script>,
+and the scene config injected as ``window.__VIXAR_SCENE__`` so the engine
+renders immediately with no server. Also reused as the anywidget iframe srcdoc.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from vixar.schema import SceneConfig
+from vixar.static import CSP_META, read_viewer_js
+
+
+def render_html(config: SceneConfig, width: int = 1200, height: int = 800) -> str:
+    """Return a complete standalone HTML document string for ``config``."""
+    viewer_js = read_viewer_js()
+    scene_json = config.to_json()
+    # Guard against an accidental </script> inside JSON breaking the inline tag.
+    scene_json = scene_json.replace("</", "<\\/")
+    return f"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta http-equiv="Content-Security-Policy" content="{CSP_META}" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Vixar</title>
+<style>
+  html, body {{ margin: 0; height: 100%; background: #12141c; }}
+  #vixar-root {{
+    position: absolute; inset: 0;
+    width: {width}px; height: {height}px; max-width: 100%;
+  }}
+</style>
+</head>
+<body>
+<div id="vixar-root"></div>
+<script>window.__VIXAR_SCENE__ = {scene_json};</script>
+<script>{viewer_js}</script>
+</body>
+</html>
+"""
+
+
+def write_html(config: SceneConfig, path: str, width: int = 1200, height: int = 800) -> str:
+    """Write the standalone HTML to ``path`` and return the absolute path."""
+    out = Path(path)
+    out.write_text(render_html(config, width=width, height=height), encoding="utf-8")
+    return str(out.resolve())

vixar-1.0.0/src/vixar/io/__init__.py

@@ -0,0 +1,21 @@
+"""Data ingestion and coordinate handling for Vixar (plan Phase 1)."""
+
+from vixar.io.coords import Origin, compute_origin, reproject_to_utm, subtract_origin
+from vixar.io.csv_reader import read_borehole_csv, read_point_csv
+from vixar.io.encode import encode_f32, encode_u32
+from vixar.io.las_reader import read_las
+from vixar.io.stats import AttributeStats, compute_stats
+
+__all__ = [
+    "Origin",
+    "compute_origin",
+    "reproject_to_utm",
+    "subtract_origin",
+    "read_point_csv",
+    "read_borehole_csv",
+    "read_las",
+    "encode_f32",
+    "encode_u32",
+    "AttributeStats",
+    "compute_stats",
+]

vixar-1.0.0/src/vixar/io/block_model_reader.py

@@ -0,0 +1,78 @@
+"""Block model reader for regular-grid CSV block models (plan Phase 3).
+
+Reads a CSV with block-centre coordinates (X, Y, Z) and attribute columns,
+detects the regular grid dimensions from the unique coordinate values, and
+returns the data in the shape expected by ``add_block_model``.
+
+The output ``centers`` array is in source-CRS (float64 UTM) and is NOT yet
+origin-subtracted — that happens at ``build_config`` time in ``Viewer``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+import pandas as pd
+
+
+@dataclass
+class BlockModelData:
+    """Regular-grid block model in source CRS."""
+
+    centers: np.ndarray    # (N, 3) float64 block-centre X, Y, Z
+    values: dict[str, np.ndarray] = field(default_factory=dict)
+    # Detected uniform block spacing [dx, dy, dz].
+    block_size: tuple[float, float, float] = (1.0, 1.0, 1.0)
+    # Grid dimensions [nx, ny, nz] — number of cells per axis.
+    grid_dims: tuple[int, int, int] = (1, 1, 1)
+
+
+def read_block_model(
+    source,
+    x_col: str = "x",
+    y_col: str = "y",
+    z_col: str = "z",
+    attribute_cols: list[str] | None = None,
+) -> BlockModelData:
+    """Read a regular block model from *source* (CSV path or DataFrame).
+
+    Grid dimensions are auto-detected from the unique sorted X/Y/Z values.
+    ``attribute_cols`` lists extra columns to extract as scalar attributes; if
+    *None*, all non-coordinate columns are included.
+    """
+    if isinstance(source, pd.DataFrame):
+        df = source
+    else:
+        df = pd.read_csv(source)
+
+    x = df[x_col].to_numpy(dtype="float64")
+    y = df[y_col].to_numpy(dtype="float64")
+    z = df[z_col].to_numpy(dtype="float64")
+
+    ux = np.unique(x)
+    uy = np.unique(y)
+    uz = np.unique(z)
+    nx, ny, nz = int(len(ux)), int(len(uy)), int(len(uz))
+
+    dx = float(np.median(np.diff(ux))) if nx > 1 else 1.0
+    dy = float(np.median(np.diff(uy))) if ny > 1 else 1.0
+    dz = float(np.median(np.diff(uz))) if nz > 1 else 1.0
+
+    centers = np.stack([x, y, z], axis=1)  # (N, 3) float64
+
+    attr_names = attribute_cols if attribute_cols is not None else [
+        c for c in df.columns if c not in (x_col, y_col, z_col)
+    ]
+    values = {
+        name: df[name].to_numpy(dtype="float32")
+        for name in attr_names
+        if name in df.columns
+    }
+
+    return BlockModelData(
+        centers=centers,
+        values=values,
+        block_size=(dx, dy, dz),
+        grid_dims=(nx, ny, nz),
+    )

vixar-1.0.0/src/vixar/io/coords.py

@@ -0,0 +1,84 @@
+"""UTM coordinate strategy (plan §4.3).
+
+Large UTM coordinates (~500,000 m) lose precision when cast to float32 in
+WebGL. Vixar keeps full float64 precision in Python, computes a scene origin
+(the bounding-box centroid), and subtracts it so the JS engine only ever sees
+small, float32-safe local offsets. The absolute origin travels in the scene
+config so picks/exports can be mapped back to real-world UTM.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from vixar.errors import UnsupportedEPSGError
+
+
+@dataclass(frozen=True)
+class Origin:
+    easting: float
+    northing: float
+    elevation: float
+    epsg: int | None = None
+
+    def as_array(self) -> np.ndarray:
+        return np.array([self.easting, self.northing, self.elevation], dtype="float64")
+
+
+def reproject_to_utm(
+    points: np.ndarray,
+    src_epsg: int,
+    dst_epsg: int | None = None,
+) -> np.ndarray:
+    """Reproject (N, 3) points from ``src_epsg`` to ``dst_epsg``.
+
+    When ``dst_epsg`` is None or equals the source, points are returned
+    unchanged (already in the working projected CRS). Z is passed through.
+    """
+    if dst_epsg is None or dst_epsg == src_epsg:
+        return np.asarray(points, dtype="float64")
+
+    try:
+        from pyproj import Transformer
+    except ImportError as exc:  # pragma: no cover - import guard
+        raise UnsupportedEPSGError(
+            "pyproj is required for reprojection but is not installed."
+        ) from exc
+
+    try:
+        transformer = Transformer.from_crs(src_epsg, dst_epsg, always_xy=True)
+    except Exception as exc:  # noqa: BLE001 - surface a clear message
+        raise UnsupportedEPSGError(
+            f"Could not build a transform from EPSG:{src_epsg} to EPSG:{dst_epsg}: {exc}"
+        ) from exc
+
+    pts = np.asarray(points, dtype="float64")
+    x, y = transformer.transform(pts[:, 0], pts[:, 1])
+    out = pts.copy()
+    out[:, 0] = x
+    out[:, 1] = y
+    return out
+
+
+def compute_origin(points_utm: np.ndarray, epsg: int | None = None) -> Origin:
+    """Compute the scene origin as the bounding-box centroid of the points."""
+    pts = np.asarray(points_utm, dtype="float64")
+    if pts.ndim != 2 or pts.shape[1] != 3:
+        raise ValueError("compute_origin expects an (N, 3) array")
+    lo = pts.min(axis=0)
+    hi = pts.max(axis=0)
+    center = (lo + hi) * 0.5
+    return Origin(
+        easting=float(center[0]),
+        northing=float(center[1]),
+        elevation=float(center[2]),
+        epsg=epsg,
+    )
+
+
+def subtract_origin(points_utm: np.ndarray, origin: Origin) -> np.ndarray:
+    """Subtract the origin and downcast to float32 local coordinates."""
+    pts = np.asarray(points_utm, dtype="float64") - origin.as_array()
+    return pts.astype("float32")