vixar 1.0.0__py3-none-any.whl

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/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/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/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/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/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/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")

vixar/io/csv_reader.py

@@ -0,0 +1,160 @@
+"""CSV / XYZ ingestion for point clouds and boreholes (plan Phase 1).
+
+Accepts a file path, a pandas DataFrame, or a numpy array, and returns float64
+positions plus named attribute arrays. Coordinates are returned in their source
+CRS; reprojection and origin subtraction happen later in the Viewer.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+import numpy as np
+import pandas as pd
+
+from vixar.errors import InputValidationError
+
+Source = "str | os.PathLike | pd.DataFrame | np.ndarray"
+
+
+@dataclass
+class PointCloudData:
+    positions: np.ndarray  # (N, 3) float64
+    attributes: dict[str, np.ndarray] = field(default_factory=dict)
+
+    @property
+    def count(self) -> int:
+        return int(self.positions.shape[0])
+
+
+@dataclass
+class BoreholeData:
+    positions: np.ndarray  # (M, 3) float64, concatenated across holes
+    hole_offsets: np.ndarray  # (K,) uint32 start index of each hole
+    attributes: dict[str, np.ndarray] = field(default_factory=dict)
+
+    @property
+    def count(self) -> int:
+        return int(self.positions.shape[0])
+
+
+def _to_dataframe(source) -> pd.DataFrame:
+    if isinstance(source, pd.DataFrame):
+        return source
+    if isinstance(source, np.ndarray):
+        if source.ndim != 2 or source.shape[1] < 3:
+            raise InputValidationError(
+                "numpy point source must be an (N, >=3) array of [x, y, z, ...]"
+            )
+        cols = ["x", "y", "z"] + [f"col{i}" for i in range(3, source.shape[1])]
+        return pd.DataFrame(source, columns=cols)
+    path = os.fspath(source)
+    if not os.path.exists(path):
+        raise InputValidationError(f"File not found: {path}")
+    # LAS/LAZ paths are routed to the LAS reader upstream (see _is_las_path);
+    # this reader only handles delimited text. Let pandas sniff the delimiter.
+    sep = None
+    return pd.read_csv(path, sep=sep, engine="python")
+
+
+def _require_columns(df: pd.DataFrame, columns: list[str]) -> None:
+    missing = [c for c in columns if c is not None and c not in df.columns]
+    if missing:
+        raise InputValidationError(
+            f"Column(s) not found: {missing}. Available columns: {list(df.columns)}"
+        )
+
+
+def read_point_csv(
+    source,
+    x_col: str = "x",
+    y_col: str = "y",
+    z_col: str = "z",
+    attribute_cols: dict[str, str] | None = None,
+) -> PointCloudData:
+    """Read a point cloud from CSV/DataFrame/ndarray.
+
+    ``attribute_cols`` maps an output attribute name to a source column name.
+    """
+    df = _to_dataframe(source)
+    if isinstance(source, np.ndarray):
+        x_col, y_col, z_col = "x", "y", "z"
+    _require_columns(df, [x_col, y_col, z_col])
+
+    positions = np.column_stack(
+        [
+            df[x_col].to_numpy(dtype="float64"),
+            df[y_col].to_numpy(dtype="float64"),
+            df[z_col].to_numpy(dtype="float64"),
+        ]
+    )
+
+    attributes: dict[str, np.ndarray] = {}
+    if attribute_cols:
+        _require_columns(df, list(attribute_cols.values()))
+        for out_name, col in attribute_cols.items():
+            attributes[out_name] = df[col].to_numpy(dtype="float64")
+
+    return PointCloudData(positions=positions, attributes=attributes)
+
+
+def read_borehole_csv(
+    source,
+    id_col: str,
+    x_col: str,
+    y_col: str,
+    z_col: str,
+    from_col: str | None = None,
+    attribute_cols: dict[str, str] | None = None,
+) -> BoreholeData:
+    """Read desurveyed borehole samples grouped into per-hole polylines.
+
+    Rows are grouped by ``id_col`` and ordered by ``from_col`` (down-hole depth)
+    when provided, else by input order. Each row contributes one 3-D sample.
+    """
+    df = _to_dataframe(source)
+    required = [id_col, x_col, y_col, z_col]
+    if from_col is not None:
+        required.append(from_col)
+    _require_columns(df, required)
+
+    positions_parts: list[np.ndarray] = []
+    offsets: list[int] = []
+    attr_parts: dict[str, list[np.ndarray]] = {k: [] for k in (attribute_cols or {})}
+    if attribute_cols:
+        _require_columns(df, list(attribute_cols.values()))
+
+    cursor = 0
+    # Stable grouping preserves hole encounter order.
+    for _hole_id, group in df.groupby(id_col, sort=False):
+        if from_col is not None:
+            group = group.sort_values(from_col, kind="stable")
+        if len(group) < 2:
+            # A single sample cannot form a tube; skip with no crash.
+            continue
+        offsets.append(cursor)
+        xyz = np.column_stack(
+            [
+                group[x_col].to_numpy(dtype="float64"),
+                group[y_col].to_numpy(dtype="float64"),
+                group[z_col].to_numpy(dtype="float64"),
+            ]
+        )
+        positions_parts.append(xyz)
+        for out_name, col in (attribute_cols or {}).items():
+            attr_parts[out_name].append(group[col].to_numpy(dtype="float64"))
+        cursor += len(group)
+
+    if not positions_parts:
+        raise InputValidationError(
+            "No borehole had >= 2 samples; cannot build any drill traces."
+        )
+
+    positions = np.concatenate(positions_parts, axis=0)
+    attributes = {name: np.concatenate(parts) for name, parts in attr_parts.items()}
+    return BoreholeData(
+        positions=positions,
+        hole_offsets=np.asarray(offsets, dtype="uint32"),
+        attributes=attributes,
+    )

vixar/io/encode.py

@@ -0,0 +1,25 @@
+"""Encode numpy arrays into the little-endian base64 the JS engine decodes.
+
+The JS ``decodeFloat32`` / ``decodeUint32`` helpers read little-endian buffers,
+so we force byte order here regardless of host endianness.
+"""
+
+from __future__ import annotations
+
+import base64
+
+import numpy as np
+
+from vixar.schema import Base64Ref
+
+
+def encode_f32(values: np.ndarray) -> Base64Ref:
+    """Encode an array as a little-endian float32 base64 DataRef."""
+    arr = np.ascontiguousarray(values, dtype="<f4")
+    return Base64Ref(dtype="f32", data=base64.b64encode(arr.tobytes()).decode("ascii"))
+
+
+def encode_u32(values: np.ndarray) -> Base64Ref:
+    """Encode an array as a little-endian uint32 base64 DataRef."""
+    arr = np.ascontiguousarray(values, dtype="<u4")
+    return Base64Ref(dtype="u32", data=base64.b64encode(arr.tobytes()).decode("ascii"))

vixar/io/las_reader.py

@@ -0,0 +1,108 @@
+"""LAS / LAZ 1.x ingestion via laspy (plan Phase 2).
+
+Reads positions and common attributes (intensity, classification, RGB, Z) and
+auto-detects the EPSG from the file's CRS/VLRs. LAZ (LASzip-compressed LAS) is
+read transparently when a decompression backend is installed — ``vixar[las]``
+ships the ``lazrs`` backend, so ``.laz`` works out of the box.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from vixar.errors import InputValidationError, LAZBackendError
+
+
+@dataclass
+class LASData:
+    positions: np.ndarray  # (N, 3) float64 in the file's CRS
+    attributes: dict[str, np.ndarray] = field(default_factory=dict)
+    epsg: int | None = None
+
+    @property
+    def count(self) -> int:
+        return int(self.positions.shape[0])
+
+
+def read_las(source, color_by: str | None = None) -> LASData:
+    """Read a LAS/LAZ 1.x file into positions + attributes with EPSG detection.
+
+    ``.laz`` files are decompressed transparently when a LAZ backend (e.g.
+    ``lazrs``, bundled with ``vixar[las]``) is installed; otherwise a clear
+    :class:`~vixar.errors.LAZBackendError` is raised.
+    """
+    path = os.fspath(source)
+    if not os.path.exists(path):
+        raise InputValidationError(f"File not found: {path}")
+
+    try:
+        import laspy
+    except ImportError as exc:  # pragma: no cover - import guard
+        raise InputValidationError(
+            "Reading LAS/LAZ files requires the optional 'laspy' dependency. "
+            "Install it with: pip install 'vixar[las]'"
+        ) from exc
+
+    is_laz = path.lower().endswith(".laz")
+    if is_laz and not _laz_backend_available():
+        raise LAZBackendError(path)
+
+    las = laspy.read(path)
+
+    positions = np.column_stack(
+        [np.asarray(las.x, dtype="float64"),
+         np.asarray(las.y, dtype="float64"),
+         np.asarray(las.z, dtype="float64")]
+    )
+
+    attributes: dict[str, np.ndarray] = {
+        "z": positions[:, 2].copy(),
+    }
+    # Intensity is present in all standard point formats.
+    if hasattr(las, "intensity"):
+        attributes["intensity"] = np.asarray(las.intensity, dtype="float64")
+    if hasattr(las, "classification"):
+        attributes["classification"] = np.asarray(las.classification, dtype="float64")
+    # RGB only on point formats 2, 3, 5, 7, 8.
+    if {"red", "green", "blue"} <= set(las.point_format.dimension_names):
+        attributes["red"] = np.asarray(las.red, dtype="float64")
+        attributes["green"] = np.asarray(las.green, dtype="float64")
+        attributes["blue"] = np.asarray(las.blue, dtype="float64")
+
+    if color_by is not None and color_by not in attributes:
+        raise InputValidationError(
+            f"color_by={color_by!r} not found in LAS attributes "
+            f"{sorted(attributes)}. Use one of those, or 'z'."
+        )
+
+    return LASData(positions=positions, attributes=attributes, epsg=_detect_epsg(las))
+
+
+def _laz_backend_available() -> bool:
+    """True when laspy has at least one usable LAZ decompression backend."""
+    try:
+        from laspy.compression import LazBackend
+    except Exception:  # noqa: BLE001 - older/newer laspy layouts
+        return False
+    try:
+        return any(b.is_available() for b in LazBackend)
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _detect_epsg(las) -> int | None:
+    """Best-effort EPSG detection from the LAS CRS / VLRs."""
+    try:
+        crs = las.header.parse_crs()
+    except Exception:  # noqa: BLE001 - laspy raises various errors here
+        return None
+    if crs is None:
+        return None
+    try:
+        epsg = crs.to_epsg()
+        return int(epsg) if epsg is not None else None
+    except Exception:  # noqa: BLE001
+        return None