pointtorch 0.1.0__py3-none-any.whl

pointtorch/__init__.py

@@ -0,0 +1,3 @@
+""" Classes and methods that are available in the top-level namespace. """
+
+from pointtorch.core import *

pointtorch/config/__init__.py

@@ -0,0 +1,5 @@
+""" Utilities for configuring the package setup. """
+
+from ._optional_dependencies import *
+
+__all__ = [name for name in globals().keys() if not name.startswith("_")]

pointtorch/config/_optional_dependencies.py

@@ -0,0 +1,35 @@
+""" Utilities for configuring the package setup. """
+
+__all__ = ["open3d_is_available", "pytorch3d_is_available"]
+
+
+def open3d_is_available():
+    """
+    Returns: `True` if Open3D is installed and `False` otherwise.
+    """
+
+    open3d_available = False
+    try:
+        from open3d.ml import torch as _  # pylint: disable=import-outside-toplevel
+
+        open3d_available = True
+    except (ModuleNotFoundError, TypeError, Exception):  # pylint: disable=broad-exception-caught
+        pass
+
+    return open3d_available
+
+
+def pytorch3d_is_available() -> bool:
+    """
+    Returns: `True` if PyTorch3D is installed and `False` otherwise.
+    """
+
+    pytorch3d_available = False
+    try:
+        import pytorch3d as _  # pylint: disable=import-outside-toplevel
+
+        pytorch3d_available = True
+    except (ModuleNotFoundError, TypeError):
+        pass
+
+    return pytorch3d_available

pointtorch/core/__init__.py

@@ -0,0 +1,6 @@
+""" Core data structures for point cloud processing. """
+
+from ._point_cloud import *
+from ._read import *
+
+__all__ = [name for name in globals().keys() if not name.startswith("_")]

pointtorch/core/_point_cloud.py

@@ -0,0 +1,149 @@
+""" Point cloud object. """
+
+__all__ = ["PointCloud", "PointCloudSeries"]
+
+from pathlib import Path
+from typing import Dict, Hashable, Iterable, List, Optional, Union
+
+import numpy as np
+import numpy.typing as npt
+import pandas as pd
+
+from pointtorch.io import PointCloudIoData, PointCloudWriter
+
+
+class PointCloud(pd.DataFrame):
+    """Point cloud object. Subclass of
+    `pd.DataFrame <https://pd.pydata.org/docs/reference/api/pd.DataFrame.html>`_
+
+    Args:
+        identifier: Point cloud identifier. Defaults to `None`.
+        x_max_resolution: Maximum resolution of the point cloud's x-coordinates in meter. Defaults to `None`.
+        y_max_resolution: Maximum resolution of the point cloud's y-coordinates in meter. Defaults to `None`.
+        z_max_resolution: Maximum resolution of the point cloud's z-coordinates in meter. Defaults to `None`.
+
+    For a documentation of other parameters, see the documentation of \
+   `pd.DataFrame <https://pd.pydata.org/docs/reference/api/pd.DataFrame.html>`_.
+
+    Attributes:
+        identifier: Point cloud identifier.
+        x_max_resolution: Maximum resolution of the point cloud's x-coordinates in meter.
+        y_max_resolution: Maximum resolution of the point cloud's y-coordinates in meter.
+        z_max_resolution: Maximum resolution of the point cloud's z-coordinates in meter.
+    """
+
+    _metadata = ["identifier", "x_max_resolution", "y_max_resolution", "z_max_resolution"]
+
+    def __init__(  # pylint: disable=too-many-positional-arguments
+        self,
+        data: Union[npt.ArrayLike, Iterable, Dict, pd.DataFrame],
+        index: Optional[Union[pd.Index, npt.NDArray[np.int64]]] = None,
+        columns: Optional[Union[pd.Index, npt.ArrayLike, List[str]]] = None,
+        dtype: Optional[np.dtype] = None,
+        copy: Optional[bool] = True,
+        identifier: Optional[str] = None,
+        x_max_resolution: Optional[float] = None,
+        y_max_resolution: Optional[float] = None,
+        z_max_resolution: Optional[float] = None,
+    ) -> None:
+        super().__init__(data=data, index=index, columns=columns, dtype=dtype, copy=copy)  # type: ignore[call-arg]
+        self.identifier = identifier
+        self.x_max_resolution = x_max_resolution
+        self.y_max_resolution = y_max_resolution
+        self.z_max_resolution = z_max_resolution
+
+    @property
+    def _constructor(self):
+        return PointCloud
+
+    @property
+    def _constructor_sliced(self):
+        return PointCloudSeries
+
+    def xyz(self) -> npt.NDArray[np.float64]:
+        """
+        Returns:
+            x, y, and z coordinates of the points in the point cloud.
+
+        Raises:
+            RuntimeError: if "x", "y", or "z" are not in `self.columns`.
+        """
+
+        if "x" not in self.columns or "y" not in self.columns or "z" not in self.columns:
+            raise RuntimeError("The point cloud does not contain xyz coordinates.")
+
+        return self[["x", "y", "z"]].astype(np.float64).to_numpy()
+
+    def to(self, file_path: Union[str, Path], columns: Optional[List[str]] = None) -> None:
+        """
+        Writes the point cloud to a file.
+
+        Args:
+            file_path: Path of the output file.
+            columns: Point cloud columns to be written. The x, y, and z columns are always written.
+
+        Raises:
+            ValueError: If the point cloud format is not supported by the writer or if `columns` contains a column name
+                that is not existing in the point cloud.
+        """
+
+        writer = PointCloudWriter()
+        point_cloud_data = PointCloudIoData(
+            self,
+            identifier=self.identifier,
+            x_max_resolution=self.x_max_resolution,
+            y_max_resolution=self.y_max_resolution,
+            z_max_resolution=self.z_max_resolution,
+        )
+        writer.write(point_cloud_data, file_path, columns=columns)
+
+
+class PointCloudSeries(pd.Series):
+    """
+    A data series that represents a point cloud column. Subclass of
+    `pd.Series <https://pd.pydata.org/pandas-docs/stable/reference/api/pd.Series.html>`_.
+
+    Args:
+        identifier: Point cloud identifier. Defaults to `None`.
+        x_max_resolution: Maximum resolution of the point cloud's x-coordinates in meter. Defaults to `None`.
+        y_max_resolution: Maximum resolution of the point cloud's y-coordinates in meter. Defaults to `None`.
+        z_max_resolution: Maximum resolution of the point cloud's z-coordinates in meter. Defaults to `None`.
+
+    For a documentation of other parameters, see the documentation of \
+        `pd.Series <https://pd.pydata.org/pandas-docs/stable/reference/api/pd.Series.html>`_.
+
+
+    Attributes:
+        identifier: Point cloud identifier.
+        x_max_resolution: Maximum resolution of the point cloud's x-coordinates in meter.
+        y_max_resolution: Maximum resolution of the point cloud's y-coordinates in meter.
+        z_max_resolution: Maximum resolution of the point cloud's z-coordinates in meter.
+    """
+
+    _metadata = ["identifier", "x_max_resolution", "y_max_resolution", "z_max_resolution"]
+
+    def __init__(  # pylint: disable=too-many-positional-arguments
+        self,
+        data: Optional[Union[npt.ArrayLike, Iterable, Dict, int, float, str]] = None,
+        index: Optional[Union[pd.Index, npt.NDArray[np.int64]]] = None,
+        dtype: Optional[Union[str, np.dtype, pd.api.extensions.ExtensionDtype]] = None,
+        name: Optional[Hashable] = None,
+        copy: Optional[bool] = True,
+        identifier: Optional[str] = None,
+        x_max_resolution: Optional[float] = None,
+        y_max_resolution: Optional[float] = None,
+        z_max_resolution: Optional[float] = None,
+    ) -> None:
+        super().__init__(data=data, index=index, dtype=dtype, name=name, copy=copy)  # type: ignore[call-arg]
+        self.identifier = identifier
+        self.x_max_resolution = x_max_resolution
+        self.y_max_resolution = y_max_resolution
+        self.z_max_resolution = z_max_resolution
+
+    @property
+    def _constructor(self):
+        return PointCloudSeries
+
+    @property
+    def _constructor_expanddim(self):
+        return PointCloud

pointtorch/core/_read.py

@@ -0,0 +1,35 @@
+""" Method for reading point cloud files. """
+
+import pathlib
+from typing import List, Optional, Union
+
+from pointtorch.core._point_cloud import PointCloud
+from pointtorch.io import PointCloudReader
+
+
+def read(file_path: Union[str, pathlib.Path], columns: Optional[List[str]] = None) -> PointCloud:
+    """
+    Method for reading point cloud files.
+
+    Args:
+        file_path: Path of the point cloud file to be read.
+        columns: Name of the point cloud columns to be read. The x, y, and z columns are always read.
+
+    Returns:
+        Point cloud object.
+
+    Raises:
+        ValueError: If the point cloud format is not supported by the reader.
+    """
+
+    reader = PointCloudReader()
+    point_cloud_data = reader.read(file_path, columns=columns)
+    point_cloud = PointCloud(
+        point_cloud_data.data,
+        identifier=point_cloud_data.identifier,
+        x_max_resolution=point_cloud_data.x_max_resolution,
+        y_max_resolution=point_cloud_data.y_max_resolution,
+        z_max_resolution=point_cloud_data.z_max_resolution,
+    )
+
+    return point_cloud

pointtorch/io/__init__.py

@@ -0,0 +1,13 @@
+""" Tools for reading and writing point cloud files. """
+
+from ._csv_reader import *
+from ._csv_writer import *
+from ._hdf_reader import *
+from ._hdf_writer import *
+from ._las_reader import *
+from ._las_writer import *
+from ._point_cloud_io_data import *
+from ._point_cloud_reader import *
+from ._point_cloud_writer import *
+
+__all__ = [name for name in globals().keys() if not name.startswith("_")]

pointtorch/io/_base_point_cloud_reader.py

@@ -0,0 +1,104 @@
+""" Abstract base class for implementing point cloud file readers. """
+
+__all__ = ["BasePointCloudReader"]
+
+import abc
+import pathlib
+from typing import List, Optional, Tuple, Union
+
+import pandas as pd
+
+from ._point_cloud_io_data import PointCloudIoData
+
+
+class BasePointCloudReader(abc.ABC):
+    """Abstract base class for implementing point cloud file readers."""
+
+    @abc.abstractmethod
+    def supported_file_formats(self) -> List[str]:
+        """
+        Returns:
+            File formats supported by the point cloud file reader.
+        """
+
+    def read(self, file_path: Union[str, pathlib.Path], columns: Optional[List[str]] = None) -> PointCloudIoData:
+        """
+        Reads a point cloud file.
+
+        Args:
+            file_path: Path of the point cloud file to be read.
+            columns: Name of the point cloud columns to be read. The x, y, and z columns are always read.
+
+        Returns:
+            Point cloud object.
+
+        Raises:
+            ValueError: If the point cloud format is not supported by the reader.
+        """
+
+        if isinstance(file_path, str):
+            file_path = pathlib.Path(file_path)
+
+        file_format = file_path.suffix.lstrip(".")
+        if file_format not in self.supported_file_formats():
+            raise ValueError(f"The {file_format} format is not supported by the point cloud reader.")
+
+        identifier = self._read_identifier(file_path)
+        file_id = file_path.stem if identifier is None else identifier
+
+        if columns is not None:
+            columns = columns.copy()
+
+            # The x, y, z coordinates are always loaded.
+            for idx, coord in enumerate(["x", "y", "z"]):
+                if coord not in columns:
+                    columns.insert(idx, coord)
+
+        point_cloud_df = self._read_points(file_path, columns=columns)
+        (x_max_resolution, y_max_resolution, z_max_resolution) = self._read_max_resolutions(file_path)
+
+        return PointCloudIoData(
+            point_cloud_df,
+            identifier=file_id,
+            x_max_resolution=x_max_resolution,
+            y_max_resolution=y_max_resolution,
+            z_max_resolution=z_max_resolution,
+        )
+
+    @abc.abstractmethod
+    def _read_points(self, file_path: pathlib.Path, columns: Optional[List[str]] = None) -> pd.DataFrame:
+        """
+        Reads point data from a point cloud file. This method has to be overriden by child classes.
+
+        Args:
+            file_path: Path of the point cloud file to be read.
+            columns: Name of the point cloud columns to be read.
+
+        Returns:
+            Point cloud data.
+        """
+
+    @staticmethod
+    @abc.abstractmethod
+    def _read_max_resolutions(file_path: pathlib.Path) -> Tuple[Optional[float], Optional[float], Optional[float]]:
+        """
+        Reads the maximum resolution for each coordinate dimension from the point cloud file.
+
+        Args:
+            file_path: Path of the point cloud file to be read.
+
+        Returns:
+            Maximum resolution of the x-, y-, and z-coordinates of the point cloud.
+        """
+
+    @staticmethod
+    def _read_identifier(file_path: pathlib.Path) -> Optional[str]:  # pylint: disable=unused-argument
+        """
+        Reads the point cloud identifier from the point cloud file. Storing a file identifier is not supported by all
+        file formats and :code:`None` may be returned when no file identifier is stored in a file.
+
+        Returns:
+            Point cloud identifier.
+        """
+
+        return None

pointtorch/io/_base_point_cloud_writer.py

@@ -0,0 +1,99 @@
+""" Abstract base class for implementing point cloud file writers. """
+
+__all__ = ["BasePointCloudWriter"]
+
+import abc
+import pathlib
+from typing import List, Optional, Union
+
+import pandas as pd
+
+from ._point_cloud_io_data import PointCloudIoData
+
+
+class BasePointCloudWriter(abc.ABC):
+    """Abstract base class for implementing point cloud file writers."""
+
+    @abc.abstractmethod
+    def supported_file_formats(self) -> List[str]:
+        """
+        Returns:
+            File formats supported by the point cloud file writer.
+        """
+
+    def write(
+        self, point_cloud: PointCloudIoData, file_path: Union[str, pathlib.Path], columns: Optional[List[str]] = None
+    ) -> None:
+        """
+        Writes a point cloud to a file.
+
+        Args:
+            point_cloud: Point cloud to be written.
+            file_path: Path of the output file.
+            columns: Point cloud columns to be written. The x, y, and z columns are always written.
+
+        Raises:
+            ValueError: If the point cloud format is not supported by the writer or if `columns` contains a column name
+                that is not existing in the point cloud.
+        """
+
+        if isinstance(file_path, str):
+            file_path = pathlib.Path(file_path)
+
+        file_format = file_path.suffix.lstrip(".")
+        if file_format not in self.supported_file_formats():
+            raise ValueError(f"The {file_format} format is not supported by the point cloud writer.")
+
+        point_cloud_df = point_cloud.data
+        # pylint: disable=duplicate-code
+        if columns is not None:
+            columns = columns.copy()
+
+            # The x, y, z coordinates are always written.
+            for idx, coord in enumerate(["x", "y", "z"]):
+                if coord not in columns:
+                    columns.insert(idx, coord)
+
+            missing_columns = set(columns).difference(set(point_cloud_df.columns))
+            if len(missing_columns) == 1:
+                raise ValueError(f"The point cloud does not contain a column named {list(missing_columns)[0]}.")
+            if len(missing_columns) > 1:
+                missing_columns_list = list(missing_columns)
+                missing_columns_str = f"{', '.join(missing_columns_list[:-1])}, and {missing_columns_list[-1]}"
+                raise ValueError(f"The point cloud does not contain columns named {missing_columns_str}.")
+            point_cloud_df = point_cloud_df[columns]
+
+        self._write_data(
+            point_cloud_df,
+            file_path,
+            identifier=point_cloud.identifier,
+            x_max_resolution=point_cloud.x_max_resolution,
+            y_max_resolution=point_cloud.y_max_resolution,
+            z_max_resolution=point_cloud.z_max_resolution,
+        )
+
+    @abc.abstractmethod
+    def _write_data(
+        self,
+        point_cloud: pd.DataFrame,
+        file_path: pathlib.Path,
+        *,
+        identifier: Optional[str] = None,
+        x_max_resolution: Optional[float] = None,
+        y_max_resolution: Optional[float] = None,
+        z_max_resolution: Optional[float] = None,
+    ) -> None:
+        """
+        Writes a point cloud to a file. This method has to be overriden by child classes.
+
+        Args:
+            point_cloud: Point cloud to be written.
+            file_path: Path of the output file.
+            identifier: Identifier of the point cloud.
+            x_max_resolution (float, optional): Maximum resolution of the point cloud's x-coordinates in meter. Defaults
+                to `None`.
+            y_max_resolution (float, optional): Maximum resolution of the point cloud's y-coordinates in meter. Defaults
+                to `None`.
+            z_max_resolution (float, optional): Maximum resolution of the point cloud's z-coordinates in meter. Defaults
+                to `None`.
+        """

pointtorch/io/_csv_reader.py

@@ -0,0 +1,84 @@
+""" Point cloud file reader for csv and txt files. """
+
+__all__ = ["CsvReader"]
+
+import pathlib
+from typing import List, Optional, Tuple, Union
+
+import pandas as pd
+
+from ._base_point_cloud_reader import BasePointCloudReader
+from ._point_cloud_io_data import PointCloudIoData
+
+
+class CsvReader(BasePointCloudReader):
+    """Point cloud file reader for csv and txt files."""
+
+    def supported_file_formats(self) -> List[str]:
+        """
+        Returns:
+            File formats supported by the point cloud file reader.
+        """
+
+        return ["csv", "txt"]
+
+    def read(self, file_path: Union[str, pathlib.Path], columns: Optional[List[str]] = None) -> PointCloudIoData:
+        """
+        Reads a point cloud file.
+
+        Args:
+            file_path: Path of the point cloud file to be read.
+            columns: Name of the point cloud columns to be read. The x, y, and z columns are always read.
+
+        Returns:
+            Point cloud object.
+
+        Raises:
+            ValueError: If the point cloud format is not supported by the reader.
+        """
+        # The method from the base is called explicitly so that the read method appears in the documentation of this
+        # class.
+        return super().read(file_path, columns=columns)
+
+    def _read_points(self, file_path: pathlib.Path, columns: Optional[List[str]] = None) -> pd.DataFrame:
+        """
+        Reads point data from a point cloud file in csv or txt format.
+
+        Args:
+            file_path: Path of the point cloud file to be read.
+            columns: Name of the point cloud columns to be read. The x, y, and z columns are always read.
+
+        Returns:
+            Point cloud data.
+        """
+
+        file_format = file_path.suffix.lstrip(".")
+        return pd.read_csv(file_path, usecols=columns, sep="," if file_format == "csv" else " ")
+
+    @staticmethod
+    def _read_max_resolutions(file_path: pathlib.Path) -> Tuple[float, float, float]:
+        """
+        Reads the maximum resolution for each coordinate dimension from the point cloud file.
+
+        Args:
+            file_path: Path of the point cloud file to be read.
+
+        Returns:
+            Maximum resolution of the x-, y-, and z-coordinates of the point cloud.
+        """
+
+        file_format = file_path.suffix.lstrip(".")
+        df = pd.read_csv(file_path, usecols=["x", "y", "z"], sep="," if file_format == "csv" else " ", dtype=str)
+
+        # The precision of each coordinate is calculated by counting the digits after the decimal.
+        x_max_resolution = (
+            df["x"].str.split(".").apply(lambda x: round(0.1 ** len(x[1]), len(x)) if len(x) > 1 else 1).min()
+        )
+        y_max_resolution = (
+            df["y"].str.split(".").apply(lambda x: round(0.1 ** len(x[1]), len(x)) if len(x) > 1 else 1).min()
+        )
+        z_max_resolution = (
+            df["z"].str.split(".").apply(lambda x: round(0.1 ** len(x[1]), len(x)) if len(x) > 1 else 1).min()
+        )
+
+        return x_max_resolution, y_max_resolution, z_max_resolution

pointtorch/io/_csv_writer.py

@@ -0,0 +1,80 @@
+""" Point cloud file writer for csv and txt files. """
+
+__all__ = ["CsvWriter"]
+
+import math
+import pathlib
+from typing import List, Optional, Union
+
+import pandas as pd
+
+from ._base_point_cloud_writer import BasePointCloudWriter
+from ._point_cloud_io_data import PointCloudIoData
+
+
+class CsvWriter(BasePointCloudWriter):
+    """Point cloud file writer for csv and txt files."""
+
+    def supported_file_formats(self) -> List[str]:
+        """
+        Returns:
+            File formats supported by the point cloud file writer.
+        """
+
+        return ["csv", "txt"]
+
+    def write(
+        self, point_cloud: PointCloudIoData, file_path: Union[str, pathlib.Path], columns: Optional[List[str]] = None
+    ) -> None:
+        """
+        Writes a point cloud to a file.
+
+        Args:
+            point_cloud: Point cloud to be written.
+            file_path: Path of the output file.
+            columns: Point cloud columns to be written. The x, y, and z columns are always written.
+
+        Raises:
+            ValueError: If the point cloud format is not supported by the writer or if `columns` contains a column name
+                that is not existing in the point cloud.
+        """
+        # The method from the base is called explicitly so that the read method appears in the documentation of this
+        # class.
+        super().write(point_cloud, file_path, columns=columns)
+
+    def _write_data(
+        self,
+        point_cloud: pd.DataFrame,
+        file_path: pathlib.Path,
+        *,
+        identifier: Optional[str] = None,
+        x_max_resolution: Optional[float] = None,
+        y_max_resolution: Optional[float] = None,
+        z_max_resolution: Optional[float] = None,
+    ) -> None:
+        """
+        Writes a point cloud to a file.
+
+        Args:
+            point_cloud: Point cloud to be written.
+            file_path: Path of the output file.
+            x_max_resolution: Maximum resolution of the point cloud's x-coordinates in meter. Defaults to `None`.
+            y_max_resolution: Maximum resolution of the point cloud's y-coordinates in meter. Defaults to `None`.
+            z_max_resolution: Maximum resolution of the point cloud's z-coordinates in meter. Defaults to `None`.
+        """
+
+        num_decimals = None
+
+        if x_max_resolution is not None:
+            num_decimals = math.ceil(-1 * min(0, math.log(x_max_resolution, 10)))
+        if y_max_resolution is not None:
+            num_decimals_y = math.ceil(-1 * min(0, math.log(y_max_resolution, 10)))
+            num_decimals = max(num_decimals, num_decimals_y) if num_decimals is not None else num_decimals_y
+        if z_max_resolution is not None:
+            num_decimals_z = math.ceil(-1 * min(0, math.log(z_max_resolution, 10)))
+            num_decimals = max(num_decimals, num_decimals_z) if num_decimals is not None else num_decimals_z
+
+        float_format = f"%.{num_decimals}f" if num_decimals is not None else None
+
+        file_format = file_path.suffix.lstrip(".")
+        point_cloud.to_csv(file_path, sep="," if file_format == "csv" else " ", index=False, float_format=float_format)