pointcloudkit 0.1.0__py3-none-any.whl

pointcloudkit/__init__.py

@@ -0,0 +1,17 @@
+# Copyright (C) 2026 Mindkosh technologies private limited
+
+from pointcloudkit.point_cloud import PointCloud
+
+
+def convert(src: str, dst: str, binary: bool = True) -> None:
+    """Convert a point cloud file from one format to another.
+
+    Example::
+
+        convert("scan.las", "scan.pcd")
+        convert("scan.bin", "scan.ply", binary=False)
+    """
+    PointCloud.read(src).write(dst, binary=binary)
+
+
+__all__ = ['PointCloud', 'convert']

pointcloudkit/io/__init__.py

@@ -0,0 +1,62 @@
+# Copyright (C) 2026 Mindkosh technologies private limited
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pointcloudkit.point_cloud import PointCloud
+
+# Populated lazily on first call to avoid import overhead for unused formats.
+_READERS: dict = {}
+_WRITERS: dict = {}
+
+
+def _ensure_loaded() -> None:
+    if _READERS:
+        return
+    from pointcloudkit.io import pcd, ply, las
+    from pointcloudkit.io import bin as bin_
+
+    _READERS['.pcd'] = pcd.PCDFile.read
+    _READERS['.ply'] = ply.PLYFile.read
+    _READERS['.las'] = las.LASFile.read
+    _READERS['.bin'] = bin_.BINFile.read
+
+    _WRITERS['.pcd'] = pcd.PCDFile.write
+    _WRITERS['.ply'] = ply.PLYFile.write
+    _WRITERS['.las'] = las.LASFile.write
+    # .bin is read-only; users convert via .pcd or .ply
+
+
+def read(path: str) -> PointCloud:
+    """Read a point cloud from *path*. Format is inferred from the file suffix.
+
+    Supported: .pcd, .ply, .las, .bin
+    """
+    _ensure_loaded()
+    ext    = Path(path).suffix.lower()
+    reader = _READERS.get(ext)
+    if reader is None:
+        raise ValueError(
+            f"Unsupported format for reading: {ext!r}. "
+            f"Supported extensions: {sorted(_READERS)}"
+        )
+    return reader(path)
+
+
+def write(pc: PointCloud, path: str, binary: bool = True) -> None:
+    """Write *pc* to *path*. Format is inferred from the file suffix.
+
+    Supported: .pcd, .ply, .las
+    """
+    _ensure_loaded()
+    ext    = Path(path).suffix.lower()
+    writer = _WRITERS.get(ext)
+    if writer is None:
+        raise ValueError(
+            f"Unsupported format for writing: {ext!r}. "
+            f"Supported extensions: {sorted(_WRITERS)}"
+        )
+    writer(pc, path, binary=binary)

pointcloudkit/io/bin.py

@@ -0,0 +1,30 @@
+# Copyright (C) 2026 Mindkosh technologies private limited
+
+import numpy as np
+
+from pointcloudkit.point_cloud import PointCloud
+
+
+class BINFile:
+    """Read Velodyne binary (.bin) point cloud files (read-only).
+
+    BIN files store points as a flat sequence of float32 values.
+    The default layout is KITTI format: x, y, z, intensity (4 values/point).
+    """
+
+    @staticmethod
+    def read(path: str, num_attrs: int = 4) -> PointCloud:
+        """Read a Velodyne BIN file and return a PointCloud.
+
+        :param path: path to the .bin file
+        :param num_attrs: number of float32 values per point (default 4 = x, y, z, intensity)
+        """
+        data = np.fromfile(path, dtype=np.float32).reshape(-1, num_attrs)
+
+        position = data[:, :3].astype(np.float64)
+        pc       = PointCloud(position=position)
+
+        if num_attrs > 3:
+            pc.intensity = data[:, 3].copy()  # already float32
+
+        return pc

pointcloudkit/io/las.py

@@ -0,0 +1,92 @@
+# Copyright (C) 2026 Mindkosh technologies private limited
+
+import numpy as np
+import laspy
+
+from pointcloudkit.point_cloud import PointCloud
+
+
+def _has_rgb(las) -> bool:
+    return all(hasattr(las, c) for c in ('red', 'green', 'blue'))
+
+
+def _has_intensity(las) -> bool:
+    return hasattr(las, 'intensity')
+
+
+def _normalize_to_uint8(arr: np.ndarray) -> np.ndarray:
+    """Convert LAS uint16 colour channel (0-65535) to uint8 (0-255).
+
+    LAS files produced by different scanners may store 8-bit values in the
+    low byte *or* the high byte of a uint16 field. Values that fit in a byte
+    (≤ 255) are kept as-is; values that don't are right-shifted by 8.
+    """
+    arr = np.asarray(arr, dtype=np.uint32)
+    return np.where(arr > 255, arr >> 8, arr).astype(np.uint8)
+
+
+def _should_use_double(position: np.ndarray) -> bool:
+    """Return True if any coordinate magnitude exceeds float32 precision."""
+    return float(np.abs(position).max()) > 1e6
+
+
+class LASFile:
+    """Read and write LAS point cloud files."""
+
+    @staticmethod
+    def read(path: str) -> PointCloud:
+        """Read a LAS file and return a PointCloud."""
+        las = laspy.read(path)
+
+        position = np.column_stack([
+            np.asarray(las.x, dtype=np.float64),
+            np.asarray(las.y, dtype=np.float64),
+            np.asarray(las.z, dtype=np.float64),
+        ])
+        pc = PointCloud(position=position)
+
+        if _has_intensity(las):
+            pc.intensity = np.asarray(las.intensity, dtype=np.float32)
+
+        if _has_rgb(las):
+            r = _normalize_to_uint8(np.asarray(las.red))
+            g = _normalize_to_uint8(np.asarray(las.green))
+            b = _normalize_to_uint8(np.asarray(las.blue))
+            pc.rgb = np.column_stack([r, g, b]).astype(np.uint8)
+
+        return pc
+
+    @staticmethod
+    def write(pc: PointCloud, path: str, binary: bool = True) -> None:
+        """Write a PointCloud to a LAS file.
+
+        LAS is always a binary format; the *binary* parameter is accepted for
+        API consistency but has no effect.
+
+        Point format 2 is chosen when RGB data is present; format 0 otherwise.
+        Intensity (float32) is scaled to uint16 via clipping to [0, 65535].
+        RGB (uint8) is scaled to uint16 by shifting left 8 bits.
+        """
+        n = len(pc)
+        has_rgb_data       = len(pc.rgb)       == n
+        has_intensity_data = len(pc.intensity) == n
+
+        point_format = 2 if has_rgb_data else 0
+        header = laspy.LasHeader(point_format=point_format, version="1.2")
+        las    = laspy.LasData(header=header)
+
+        las.x = pc.position[:, 0]
+        las.y = pc.position[:, 1]
+        las.z = pc.position[:, 2]
+
+        if has_intensity_data:
+            # Intensity is stored as uint16 in LAS; clip to valid range
+            las.intensity = np.clip(pc.intensity, 0, 65535).astype(np.uint16)
+
+        if has_rgb_data:
+            # Scale uint8 (0-255) → uint16 (0-65535) by shifting left 8 bits
+            las.red   = pc.rgb[:, 0].astype(np.uint16) << 8
+            las.green = pc.rgb[:, 1].astype(np.uint16) << 8
+            las.blue  = pc.rgb[:, 2].astype(np.uint16) << 8
+
+        las.write(path)

pointcloudkit/io/pcd.py

@@ -0,0 +1,280 @@
+# Copyright (C) 2026 Mindkosh technologies private limited
+
+import math
+import struct
+
+import numpy as np
+
+from pointcloudkit.point_cloud import PointCloud
+
+# Points written per iteration during binary streaming writes.
+# Keeps peak extra memory at CHUNK × bytes_per_point (~8 MB for 128 B/pt).
+_CHUNK = 65_536
+
+# Beyond this absolute coordinate value float32 loses sub-millimetre precision
+# (~7 significant digits → 1 mm resolution at 10 000 m).
+_F32_POSITION_THRESHOLD = 1e4
+
+
+class PCDFile:
+    """Read and write PCD (Point Cloud Data) files."""
+
+    _KNOWN_FIELDS = {'x', 'y', 'z', 'intensity', 'rgb'}
+
+    _STRUCT_FMT = {
+        ('F', 4): 'f',  ('F', 8): 'd',
+        ('U', 1): 'B',  ('U', 2): 'H',  ('U', 4): 'I',  ('U', 8): 'Q',
+        ('I', 1): 'b',  ('I', 2): 'h',  ('I', 4): 'i',  ('I', 8): 'q',
+    }
+
+    # ── Reader ─────────────────────────────────────────────────────────────
+
+    @classmethod
+    def read(cls, path: str) -> PointCloud:
+        """Read a PCD file (ASCII or binary) and return a PointCloud."""
+        pc = PointCloud()
+
+        # Temporary list buffers; replaced by numpy arrays after all points are read
+        pc._buf_x         = []
+        pc._buf_y         = []
+        pc._buf_z         = []
+        pc._buf_intensity = []
+        pc._buf_rgb       = []
+
+        with open(path, 'rb') as f:
+            hdr    = cls._parse_header(f)
+            fields = hdr['fields']
+            types  = hdr['types']
+            sizes  = hdr['sizes']
+            counts = hdr['counts']
+            n_pts  = hdr.get('points', 0)
+            fmt    = hdr.get('data', 'ascii')
+
+            for field in fields:
+                if field not in cls._KNOWN_FIELDS:
+                    pc.extra[field] = []
+
+            field_type = dict(zip(fields, types))
+
+            if fmt == 'ascii':
+                cls._read_ascii(f, pc, fields, field_type, counts)
+            elif fmt == 'binary':
+                cls._read_binary(f, pc, fields, field_type, types, sizes, counts, n_pts)
+            else:
+                raise ValueError(f"Unsupported PCD data format: {fmt!r}")
+
+        if pc._buf_x:
+            pc.position = np.column_stack([pc._buf_x, pc._buf_y, pc._buf_z]).astype(np.float64)
+        pc.intensity = np.array(pc._buf_intensity, dtype=np.float32)
+        pc.rgb       = np.array(pc._buf_rgb, dtype=np.uint8).reshape(-1, 3)
+        pc.extra     = {k: np.array(v) for k, v in pc.extra.items()}
+
+        del pc._buf_x, pc._buf_y, pc._buf_z, pc._buf_intensity, pc._buf_rgb
+
+        return pc
+
+    @staticmethod
+    def _parse_header(f) -> dict:
+        hdr = {'fields': [], 'types': [], 'sizes': [], 'counts': []}
+        while True:
+            line = f.readline()
+            if isinstance(line, bytes):
+                line = line.decode('ascii', errors='ignore')
+            line = line.strip()
+            if not line or line.startswith('#'):
+                continue
+            parts     = line.split()
+            key, vals = parts[0].upper(), parts[1:]
+            if   key == 'FIELDS': hdr['fields'] = vals
+            elif key == 'TYPE':   hdr['types']  = vals
+            elif key == 'SIZE':   hdr['sizes']  = [int(v) for v in vals]
+            elif key == 'COUNT':  hdr['counts'] = [int(v) for v in vals]
+            elif key == 'POINTS': hdr['points'] = int(vals[0])
+            elif key == 'DATA':
+                hdr['data'] = vals[0].lower()
+                break
+        return hdr
+
+    @classmethod
+    def _read_ascii(cls, f, pc, fields, field_type, counts):
+        expected_tokens = sum(counts)
+        for line in f:
+            if isinstance(line, bytes):
+                line = line.decode('ascii', errors='ignore')
+            line = line.strip()
+            if not line:
+                continue
+
+            tokens = line.split()
+            if len(tokens) != expected_tokens:
+                continue
+
+            parsed = {}
+            valid  = True
+            tok_i  = 0
+
+            for field, count in zip(fields, counts):
+                typ = field_type[field]
+                raw = tokens[tok_i:tok_i + count]
+                tok_i += count
+                try:
+                    if typ == 'F':
+                        v = [float(t) for t in raw]
+                        if any(not math.isfinite(x) for x in v):
+                            if field in ('x', 'y', 'z'):
+                                valid = False
+                                break
+                            v = [0.0] * count  # zero out NaN/Inf in non-position fields
+                        v = v[0] if count == 1 else v
+                    else:
+                        v = [int(float(t)) for t in raw]
+                        v = v[0] if count == 1 else v
+                except (ValueError, OverflowError):
+                    valid = False
+                    break
+                parsed[field] = v
+
+            if valid:
+                cls._append_point(pc, fields, field_type, parsed)
+
+    @classmethod
+    def _read_binary(cls, f, pc, fields, field_type, types, sizes, counts, n_pts):
+        fmt_str = '<' + ''.join(
+            cls._STRUCT_FMT[(typ, size)] * count
+            for typ, size, count in zip(types, sizes, counts)
+        )
+        packer     = struct.Struct(fmt_str)
+        point_size = packer.size
+
+        for _ in range(n_pts):
+            raw = f.read(point_size)
+            if len(raw) < point_size:
+                break
+
+            unpacked = packer.unpack(raw)
+            parsed   = {}
+            valid    = True
+            idx      = 0
+
+            for field, count in zip(fields, counts):
+                typ = field_type[field]
+                v   = unpacked[idx] if count == 1 else list(unpacked[idx:idx + count])
+                idx += count
+
+                if typ == 'F':
+                    check = [v] if count == 1 else v
+                    if any(not math.isfinite(x) for x in check):
+                        if field in ('x', 'y', 'z'):
+                            valid = False
+                            break
+                        v = 0.0 if count == 1 else [0.0] * count  # zero out NaN/Inf in non-position fields
+
+                parsed[field] = v
+
+            if valid:
+                cls._append_point(pc, fields, field_type, parsed)
+
+    @classmethod
+    def _append_point(cls, pc, fields, field_type, parsed):
+        if 'x'         in parsed: pc._buf_x.append(parsed['x'])
+        if 'y'         in parsed: pc._buf_y.append(parsed['y'])
+        if 'z'         in parsed: pc._buf_z.append(parsed['z'])
+        if 'intensity' in parsed: pc._buf_intensity.append(parsed['intensity'])
+        if 'rgb'       in parsed:
+            pc._buf_rgb.append(cls._decode_rgb(parsed['rgb'], field_type['rgb']))
+        for field, val in parsed.items():
+            if field in pc.extra:
+                pc.extra[field].append(val)
+
+    @staticmethod
+    def _decode_rgb(val, typ: str) -> tuple:
+        """Decode a packed RGB value (integer or reinterpreted float) into (r, g, b)."""
+        if typ == 'F':
+            # PCL packs RGB into a float's bit pattern
+            packed = struct.unpack('I', struct.pack('f', float(val)))[0]
+        else:
+            packed = int(val)
+        return ((packed >> 16) & 0xFF, (packed >> 8) & 0xFF, packed & 0xFF)
+
+    # ── Writer ─────────────────────────────────────────────────────────────
+
+    _KIND_TO_PCD_TYPE = {'f': 'F', 'u': 'U', 'i': 'I'}
+
+    @classmethod
+    def write(cls, pc: PointCloud, output_path: str, binary: bool = True) -> None:
+        """Write a PointCloud to a PCD file.
+
+        All non-empty fields are written: position (x, y, z), intensity, rgb,
+        and any 1-D arrays in pc.extra.
+
+        Binary mode uses chunked writes so that peak extra memory stays at
+        _CHUNK × bytes_per_point regardless of total cloud size.
+        """
+        n = len(pc)
+
+        # Each entry: (field_name, little-endian np.dtype, PCD type char, PCD size in bytes, 1-D array)
+        fields_info = []
+
+        use_f64 = n > 0 and np.max(np.abs(pc.position)) > _F32_POSITION_THRESHOLD
+        xyz_dt  = np.dtype('<f8') if use_f64 else np.dtype('<f4')
+        fields_info.append(('x', xyz_dt, 'F', xyz_dt.itemsize, pc.position[:, 0].astype(xyz_dt)))
+        fields_info.append(('y', xyz_dt, 'F', xyz_dt.itemsize, pc.position[:, 1].astype(xyz_dt)))
+        fields_info.append(('z', xyz_dt, 'F', xyz_dt.itemsize, pc.position[:, 2].astype(xyz_dt)))
+
+        if len(pc.intensity) == n:
+            idt = pc.intensity.dtype.newbyteorder('<')
+            fields_info.append(('intensity', idt, 'F', pc.intensity.dtype.itemsize, pc.intensity))
+
+        if len(pc.rgb) == n:
+            r = pc.rgb[:, 0].astype(np.uint32)
+            g = pc.rgb[:, 1].astype(np.uint32)
+            b = pc.rgb[:, 2].astype(np.uint32)
+            packed_rgb = (r << 16) | (g << 8) | b
+            fields_info.append(('rgb', np.dtype('<u4'), 'U', 4, packed_rgb))
+
+        for name, arr in pc.extra.items():
+            if arr.ndim == 1 and len(arr) == n:
+                pcd_type = cls._KIND_TO_PCD_TYPE.get(arr.dtype.kind, 'F')
+                fields_info.append((name, arr.dtype.newbyteorder('<'), pcd_type, arr.dtype.itemsize, arr))
+
+        field_names = [fi[0] for fi in fields_info]
+        field_types = [fi[2] for fi in fields_info]
+        field_sizes = [str(fi[3]) for fi in fields_info]
+
+        header = "\n".join([
+            "# .PCD v0.7 - Point Cloud Data file format",
+            "VERSION 0.7",
+            f"FIELDS {' '.join(field_names)}",
+            f"SIZE {' '.join(field_sizes)}",
+            f"TYPE {' '.join(field_types)}",
+            f"COUNT {' '.join(['1'] * len(field_names))}",
+            f"WIDTH {n}",
+            "HEIGHT 1",
+            "VIEWPOINT 0 0 0 1 0 0 0",
+            f"POINTS {n}",
+            "DATA binary" if binary else "DATA ascii",
+        ]) + "\n"
+
+        with open(output_path, 'wb' if binary else 'w') as out:
+            out.write(header.encode('ascii') if binary else header)
+
+            if n == 0:
+                return
+
+            if binary:
+                cls._write_binary(out, fields_info, n)
+            else:
+                arrays = [fi[4] for fi in fields_info]
+                for i in range(n):
+                    out.write(" ".join(str(arr[i]) for arr in arrays) + "\n")
+
+    @staticmethod
+    def _write_binary(out, fields_info, n: int) -> None:
+        struct_dt = np.dtype([(fi[0], fi[1]) for fi in fields_info])
+        buf       = np.empty(_CHUNK, dtype=struct_dt)
+        for start in range(0, n, _CHUNK):
+            end        = min(start + _CHUNK, n)
+            chunk_size = end - start
+            for fi in fields_info:
+                buf[fi[0]][:chunk_size] = fi[4][start:end]
+            out.write(buf[:chunk_size].tobytes())

pointcloudkit/io/ply.py

@@ -0,0 +1,196 @@
+# Copyright (C) 2026 Mindkosh technologies private limited
+
+import numpy as np
+
+from pointcloudkit.point_cloud import PointCloud
+
+_CHUNK = 65_536
+
+
+class PLYFile:
+    """Read and write PLY (Polygon File Format) point cloud files."""
+
+    _KNOWN_PROPS = {'x', 'y', 'z', 'intensity', 'red', 'green', 'blue'}
+
+    # PLY type name → numpy dtype char (endian-neutral)
+    _PLY_TO_NUMPY = {
+        'char':    'i1', 'int8':    'i1',
+        'uchar':   'u1', 'uint8':   'u1',
+        'short':   'i2', 'int16':   'i2',
+        'ushort':  'u2', 'uint16':  'u2',
+        'int':     'i4', 'int32':   'i4',
+        'uint':    'u4', 'uint32':  'u4',
+        'float':   'f4', 'float32': 'f4',
+        'double':  'f8', 'float64': 'f8',
+    }
+
+    # numpy (kind, itemsize) → PLY type string
+    _NUMPY_TO_PLY = {
+        ('f', 4): 'float',  ('f', 8): 'double',
+        ('u', 1): 'uchar',  ('u', 2): 'ushort', ('u', 4): 'uint',  ('u', 8): 'uint',
+        ('i', 1): 'char',   ('i', 2): 'short',  ('i', 4): 'int',   ('i', 8): 'int',
+    }
+
+    # ── Reader ─────────────────────────────────────────────────────────────
+
+    @classmethod
+    def read(cls, path: str) -> PointCloud:
+        """Read a PLY file (ASCII or binary) and return a PointCloud."""
+        with open(path, 'rb') as f:
+            hdr   = cls._parse_header(f)
+            fmt   = hdr['format']      # 'ascii' | 'binary_little_endian' | 'binary_big_endian'
+            props = hdr['properties']  # list of (name, ply_type_str)
+            n_pts = hdr['count']
+
+            if fmt == 'ascii':
+                raw = cls._read_ascii(f, props, n_pts)
+            else:
+                endian = '<' if 'little' in fmt else '>'
+                raw = cls._read_binary(f, props, n_pts, endian)
+
+        pc = PointCloud()
+
+        if 'x' in raw:
+            pc.position = np.column_stack([raw['x'], raw['y'], raw['z']]).astype(np.float64)
+        if 'intensity' in raw:
+            pc.intensity = raw['intensity'].astype(np.float32)
+        if 'red' in raw:
+            pc.rgb = np.column_stack([raw['red'], raw['green'], raw['blue']]).astype(np.uint8)
+
+        for name, arr in raw.items():
+            if name not in cls._KNOWN_PROPS:
+                pc.extra[name] = arr
+
+        return pc
+
+    @staticmethod
+    def _parse_header(f) -> dict:
+        """Parse PLY header; leaves f positioned at the first data byte."""
+        magic = f.readline().decode('ascii', errors='ignore').strip()
+        if magic != 'ply':
+            raise ValueError("Not a PLY file (missing 'ply' magic line)")
+
+        hdr       = {'format': 'ascii', 'count': 0, 'properties': []}
+        in_vertex = False
+
+        while True:
+            line  = f.readline().decode('ascii', errors='ignore').strip()
+            if not line or line.startswith('comment'):
+                continue
+            parts = line.split()
+            kw    = parts[0]
+
+            if kw == 'format':
+                hdr['format'] = parts[1]
+            elif kw == 'element':
+                in_vertex = (parts[1] == 'vertex')
+                if in_vertex:
+                    hdr['count'] = int(parts[2])
+            elif kw == 'property' and in_vertex:
+                if parts[1] == 'list':
+                    continue  # skip face index lists
+                hdr['properties'].append((parts[2], parts[1]))
+            elif kw == 'end_header':
+                break
+
+        return hdr
+
+    @classmethod
+    def _read_ascii(cls, f, props, n_pts) -> dict:
+        bufs = {name: [] for name, _ in props}
+
+        for _ in range(n_pts):
+            raw  = f.readline()
+            line = raw.decode('ascii', errors='ignore').strip() if isinstance(raw, bytes) else raw.strip()
+            if not line:
+                continue
+            tokens = line.split()
+
+            for i, (name, ply_type) in enumerate(props):
+                nc = cls._PLY_TO_NUMPY[ply_type]
+                bufs[name].append(float(tokens[i]) if 'f' in nc else int(float(tokens[i])))
+
+        return {
+            name: np.array(bufs[name], dtype=np.dtype(cls._PLY_TO_NUMPY[ply_type]))
+            for name, ply_type in props
+        }
+
+    @classmethod
+    def _read_binary(cls, f, props, n_pts, endian) -> dict:
+        dt   = np.dtype([(name, endian + cls._PLY_TO_NUMPY[ply_type]) for name, ply_type in props])
+        data = np.frombuffer(f.read(n_pts * dt.itemsize), dtype=dt)
+        return {name: data[name].copy() for name, _ in props}
+
+    # ── Writer ─────────────────────────────────────────────────────────────
+
+    @classmethod
+    def write(cls, pc: PointCloud, output_path: str, binary: bool = True) -> None:
+        """Write a PointCloud to a PLY file.
+
+        All non-empty fields are written: position (x, y, z), intensity, rgb
+        (as separate red/green/blue uchar properties), and any 1-D arrays in
+        pc.extra.
+
+        Binary mode uses chunked writes so that peak extra memory stays at
+        _CHUNK × bytes_per_point regardless of total cloud size.
+        """
+        n = len(pc)
+
+        # Each entry: (ply_prop_name, ply_type_str, little-endian np.dtype, 1-D array)
+        props_info = []
+
+        xyz_ply = cls._NUMPY_TO_PLY.get((pc.position.dtype.kind, pc.position.dtype.itemsize), 'double')
+        xyz_ndt = np.dtype('<' + cls._PLY_TO_NUMPY[xyz_ply])
+        props_info.append(('x', xyz_ply, xyz_ndt, pc.position[:, 0]))
+        props_info.append(('y', xyz_ply, xyz_ndt, pc.position[:, 1]))
+        props_info.append(('z', xyz_ply, xyz_ndt, pc.position[:, 2]))
+
+        if len(pc.intensity) == n:
+            ply_t = cls._NUMPY_TO_PLY.get((pc.intensity.dtype.kind, pc.intensity.dtype.itemsize), 'float')
+            props_info.append(('intensity', ply_t, np.dtype('<' + cls._PLY_TO_NUMPY[ply_t]), pc.intensity))
+
+        if len(pc.rgb) == n:
+            u1 = np.dtype('<u1')
+            props_info.append(('red',   'uchar', u1, pc.rgb[:, 0]))
+            props_info.append(('green', 'uchar', u1, pc.rgb[:, 1]))
+            props_info.append(('blue',  'uchar', u1, pc.rgb[:, 2]))
+
+        for name, arr in pc.extra.items():
+            if arr.ndim == 1 and len(arr) == n:
+                ply_t = cls._NUMPY_TO_PLY.get((arr.dtype.kind, arr.dtype.itemsize), 'float')
+                props_info.append((name, ply_t, np.dtype('<' + cls._PLY_TO_NUMPY[ply_t]), arr))
+
+        fmt_str    = 'binary_little_endian' if binary else 'ascii'
+        prop_lines = "\n".join(f"property {ply_t} {name}" for name, ply_t, _, _ in props_info)
+        header     = (
+            "ply\n"
+            f"format {fmt_str} 1.0\n"
+            "comment Mindkosh point cloud\n"
+            f"element vertex {n}\n"
+            f"{prop_lines}\n"
+            "end_header\n"
+        )
+
+        with open(output_path, 'wb' if binary else 'w') as out:
+            out.write(header.encode('ascii') if binary else header)
+
+            if n == 0:
+                return
+
+            if binary:
+                cls._write_binary(out, props_info, n)
+            else:
+                arrays = [pi[3] for pi in props_info]
+                for i in range(n):
+                    out.write(" ".join(str(arr[i]) for arr in arrays) + "\n")
+
+    @staticmethod
+    def _write_binary(out, props_info, n: int) -> None:
+        struct_dt = np.dtype([(pi[0], pi[2]) for pi in props_info])
+        buf       = np.empty(_CHUNK, dtype=struct_dt)
+        for start in range(0, n, _CHUNK):
+            end        = min(start + _CHUNK, n)
+            chunk_size = end - start
+            for name, _, _, arr in props_info:
+                buf[name][:chunk_size] = arr[start:end]
+            out.write(buf[:chunk_size].tobytes())

pointcloudkit/point_cloud.py

@@ -0,0 +1,120 @@
+# Copyright (C) 2026 Mindkosh technologies private limited
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+import numpy as np
+
+
+class PointCloud:
+    """Central data model for a 3-D point cloud.
+
+    Attributes
+    ----------
+    position  : (N, 3) float64 – required
+    intensity : (N,)   float32 – empty array if absent
+    rgb       : (N, 3) uint8   – empty array if absent
+    extra     : name → (N,) ndarray for any additional per-point fields
+    """
+
+    def __init__(
+        self,
+        position: Optional[np.ndarray] = None,
+        intensity: Optional[np.ndarray] = None,
+        rgb: Optional[np.ndarray] = None,
+        extra: Optional[Dict[str, np.ndarray]] = None,
+    ) -> None:
+        self.position  = position  if position  is not None else np.empty((0, 3), dtype=np.float64)
+        self.intensity = intensity if intensity is not None else np.empty(0,      dtype=np.float32)
+        self.rgb       = rgb       if rgb       is not None else np.empty((0, 3), dtype=np.uint8)
+        self.extra: Dict[str, np.ndarray] = extra if extra is not None else {}
+
+    def __len__(self) -> int:
+        return len(self.position)
+
+    @classmethod
+    def read(cls, path: str, drop_nan: bool = True) -> PointCloud:
+        """Load a point cloud from *path*; format is inferred from the file suffix.
+
+        By default, points with NaN/Inf x/y/z are removed and NaN in intensity
+        or extra float fields is zeroed out.  Pass ``drop_nan=False`` to keep
+        raw values as-is.
+        """
+        from pointcloudkit.io import read as _read
+        pc = _read(path)
+        if drop_nan:
+            pc.drop_nan()
+        return pc
+
+    def write(self, path: str, binary: bool = True) -> None:
+        """Save this cloud to *path*; format is inferred from the file suffix."""
+        from pointcloudkit.io import write as _write
+        _write(self, path, binary=binary)
+
+    def drop_nan(self) -> PointCloud:
+        """Remove points where any of x, y, z is NaN or Inf; zero out NaN in intensity and extra float fields."""
+        n = len(self.position)
+        valid = np.isfinite(self.position).all(axis=1)
+
+        self.position = self.position[valid]
+
+        if len(self.intensity) == n:
+            self.intensity = self.intensity[valid]
+            nan_mask = ~np.isfinite(self.intensity)
+            self.intensity[nan_mask] = 0.0
+
+        if len(self.rgb) == n:
+            self.rgb = self.rgb[valid]
+            # rgb is uint8; NaN cannot occur in integer arrays
+
+        for key, arr in self.extra.items():
+            if len(arr) == n:
+                self.extra[key] = arr[valid]
+                if np.issubdtype(arr.dtype, np.floating):
+                    nan_mask = ~np.isfinite(self.extra[key])
+                    self.extra[key][nan_mask] = 0
+
+        return self
+
+    def center(self) -> PointCloud:
+        """Subtract the centroid from all positions in-place. Returns self."""
+        self.position -= np.mean(self.position, axis=0)
+        return self
+
+    def make_upright(self) -> PointCloud:
+        """Align the cloud so its dominant plane is parallel to XY (Z points up).
+
+        Uses PCA: the eigenvector corresponding to the *smallest* eigenvalue of
+        the covariance matrix is the plane normal. That normal is rotated onto
+        [0, 0, 1] using the Rodrigues rotation formula. The cloud is also
+        centered as a side-effect.
+
+        Returns self.
+        """
+        centroid = self.position.mean(axis=0)
+        Pc = self.position - centroid                      # centered copy
+
+        C = (Pc.T @ Pc) / len(Pc)                         # 3×3 covariance
+        _, vecs = np.linalg.eigh(C)
+        normal = vecs[:, 0]                                # smallest eigenvalue → plane normal
+
+        z = np.array([0.0, 0.0, 1.0])
+        v = np.cross(normal, z)
+        s = np.linalg.norm(v)
+        c = np.dot(normal, z)
+
+        if s == 0.0:
+            # normal already aligned with Z (or anti-aligned); no rotation needed
+            R = np.eye(3)
+        else:
+            # Rodrigues / cross-product matrix formula
+            vx = np.array([
+                [ 0.0,  -v[2],  v[1]],
+                [ v[2],  0.0,  -v[0]],
+                [-v[1],  v[0],  0.0],
+            ])
+            R = np.eye(3) + vx + vx @ vx * ((1.0 - c) / (s ** 2))
+
+        self.position = (R @ Pc.T).T   # Pc is already centered
+        return self

pointcloudkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: pointcloudkit
+Version: 0.1.0
+Summary: Lightweight point cloud I/O and processing library. Pure numpy — no open3d dependency.
+Project-URL: Homepage, https://github.com/mindkosh/pointcloudkit
+Project-URL: Repository, https://github.com/mindkosh/pointcloudkit
+Project-URL: Issues, https://github.com/mindkosh/pointcloudkit/issues
+License: MIT
+License-File: LICENSE
+Keywords: 3d,bin,las,lidar,pcd,ply,point cloud
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: laspy>=2.0
+Requires-Dist: numpy
+Description-Content-Type: text/markdown
+
+# pointcloudkit
+
+Lightweight point cloud I/O and processing library. Pure numpy — no open3d dependency.
+
+## Requirements
+
+```
+numpy
+laspy   # LAS format only
+```
+
+Python ≥ 3.9.
+
+## Supported Formats
+
+| Extension | Read | Write |
+|-----------|------|-------|
+| `.pcd`    | ✓    | ✓     |
+| `.ply`    | ✓    | ✓     |
+| `.las`    | ✓    | ✓     |
+| `.bin`    | ✓    | —     |
+
+PCD and PLY support both ASCII and binary modes. Binary writes are chunked and memory-efficient regardless of cloud size.
+
+---
+
+## Operations
+
+### Reading and writing
+
+```python
+from pointcloudkit import PointCloud
+
+pc = PointCloud.read("scan.pcd")
+pc.write("scan.ply")                  # binary by default
+pc.write("scan_ascii.pcd", binary=False)
+```
+
+### Format conversion
+
+```python
+from pointcloudkit import convert
+
+convert("scan.las", "scan.pcd")
+convert("scan.bin", "scan.ply")
+convert("scan.pcd", "scan_ascii.ply", binary=False)
+```
+
+### Center
+
+Subtracts the centroid from all positions in-place.
+
+```python
+pc = PointCloud.read("scan.pcd")
+pc.center()
+pc.write("centered.pcd")
+```
+
+### Make upright
+
+Rotates the cloud so its dominant plane is parallel to XY (Z axis points up).
+Uses PCA: the eigenvector with the smallest eigenvalue is the plane normal,
+which is then aligned to `[0, 0, 1]` via the Rodrigues formula.
+
+```python
+pc = PointCloud.read("scan.pcd")
+pc.make_upright()
+pc.write("upright.pcd")
+```
+
+Operations return `self` and can be chained:
+
+```python
+PointCloud.read("scan.las").center().make_upright().write("processed.pcd")
+```
+
+---
+
+## PointCloud data model
+
+```python
+pc.position   # (N, 3) float64  — always present
+pc.intensity  # (N,)   float32  — empty array if absent
+pc.rgb        # (N, 3) uint8    — empty array if absent
+pc.extra      # dict: name → (N,) ndarray for any additional fields
+```
+
+Constructing manually:
+
+```python
+import numpy as np
+from pointcloudkit import PointCloud
+
+pc = PointCloud(
+    position=np.random.rand(1000, 3),
+    intensity=np.random.rand(1000).astype(np.float32),
+    rgb=np.random.randint(0, 255, (1000, 3), dtype=np.uint8),
+)
+print(len(pc))  # 1000
+```
+
+### Reading BIN files
+
+Velodyne BIN files default to KITTI layout (x, y, z, intensity). Pass `num_attrs`
+to override the number of float32 values per point.
+
+```python
+from pointcloudkit.io.bin import BINFile
+
+pc = BINFile.read("velodyne.bin")              # 4 attrs (default)
+pc = BINFile.read("custom.bin", num_attrs=6)   # 6 attrs; first 3 → position
+```
+
+### Accessing format-specific classes directly
+
+```python
+from pointcloudkit.io.pcd import PCDFile
+from pointcloudkit.io.ply import PLYFile
+from pointcloudkit.io.las import LASFile
+
+pc = PCDFile.read("scan.pcd")
+PLYFile.write(pc, "scan.ply", binary=True)
+```

pointcloudkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pointcloudkit/__init__.py,sha256=b_qxTrxKIRmNfiD_AZiC8Jm4poORf0rR8y8jNy19GSk,442
+pointcloudkit/point_cloud.py,sha256=tKOovb0JHK8EFQJbEEsuqwEyrYUaFRNEySIlcxCNlew,4423
+pointcloudkit/io/__init__.py,sha256=GCDDab4-dN-pTdJUH6w73hmAEAdG1iHsTHXQqmQD7m4,1773
+pointcloudkit/io/bin.py,sha256=Vra4gfRB7tokUZ_PlWV3ARhxJCT8IKfyXJMfm-MPKgs,936
+pointcloudkit/io/las.py,sha256=SkWCLw49tNppudDwCcLGWr8GGAjK09bs_Cb7KUjRF2g,3171
+pointcloudkit/io/pcd.py,sha256=cMLptCQsjGWC6spQFVrgmWgQhcEiRV1M208PhjygXKI,10991
+pointcloudkit/io/ply.py,sha256=AXbDDBD8mYM22-WxS3onDEg3otYnlhG8TpmkOtINrCo,7846
+pointcloudkit-0.1.0.dist-info/METADATA,sha256=azJQeBdokGJdxgRMejOQTUwZAMYaxpP7Q6b__E3l6cI,3853
+pointcloudkit-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pointcloudkit-0.1.0.dist-info/licenses/LICENSE,sha256=jrKn3K3bCORjb2TxtYbBt8YNpyBhjo-1ik2mpCzuIJA,1068
+pointcloudkit-0.1.0.dist-info/RECORD,,

pointcloudkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pointcloudkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mindkosh AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.