easyidp.pointcloud.io

Public IO dispatchers for point cloud reading and writing.

Provides read_point_cloud() and write_point_cloud() that dispatch by explicit format or by filename suffix.

Dispatcher Functions

These functions are re-exported as easyidp.pointcloud.read_point_cloud() and easyidp.pointcloud.write_point_cloud(). Prefer the re-exported module-level names in user code.

Function

Purpose

read_point_cloud()

Read by explicit format or file suffix.

write_point_cloud()

Write by explicit format or file suffix.
easyidp.pointcloud.io.read_point_cloud(path, format=None, offset=None)

Read a point cloud file and return a new PointCloud.

Parameters:

  • path (str or pathlib.Path) – Path to the point cloud file (.ply, .las, .laz).

  • format (str or None, optional) – Explicit format ("ply", "las", "laz", case-insensitive). When None, the format is inferred from the path suffix.

  • offset (list or ndarray of shape (3,) or None, optional) – User-supplied offset for the returned PointCloud.

Return type:

PointCloud

Raises:

  • ValueError – If format is unsupported.

  • FileNotFoundError – If path does not exist.

Examples

Read by suffix:

>>> pcd = idp.pointcloud.read_point_cloud("cloud.ply")
>>> isinstance(pcd, idp.PointCloud)
True

Read by explicit format:

>>> pcd = idp.pointcloud.read_point_cloud("cloud.data", format="las")

Read a Pix4D-offset local point cloud:

>>> pcd = idp.pointcloud.read_point_cloud(
...     "hasu_tanashi.ply",
...     offset=[368043, 3955495, 98],
... )
easyidp.pointcloud.io.write_point_cloud(target, pcd, format=None)

Write a PointCloud to a file.

Parameters:

  • target (str or pathlib.Path) – Target file path. Suffix is used to infer format unless format is given.

  • pcd (PointCloud) – The point cloud to write.

  • format (str or None, optional) – Explicit format ("ply", "las", "laz", case-insensitive).

Returns:

The actual file path written to (may differ from target when the suffix is adjusted).

Return type:

pathlib.Path

Raises:

ValueError – If the format cannot be determined or is unsupported.

Examples

Write by suffix:

>>> out_path = idp.pointcloud.write_point_cloud("cloud.ply", pcd)
>>> out_path.name
'cloud.ply'

Write by explicit format:

>>> idp.pointcloud.write_point_cloud("cloud_output", pcd, format="laz")

If the suffix and format disagree, EasyIDP writes to an adjusted path:

>>> idp.pointcloud.write_point_cloud("cloud.las", pcd, format="ply")
PosixPath('cloud.las.ply')

LAS/LAZ Backend

easyidp.pointcloud.io.las provides low-level array IO for LAS and LAZ files. It returns and accepts raw NumPy arrays rather than PointCloud objects.

Function

Purpose

read()

Read LAS/LAZ data into raw arrays.

write()

Write raw arrays to LAS/LAZ.
easyidp.pointcloud.io.las.read(path)

Read a LAS or LAZ file and return (points, colors, normals).

Parameters:

path (str or pathlib.Path) – Path to a .las or .laz file.

Returns:

(points (N,3), colors (N,3) uint8, normals (N,3)). colors and normals are None when not present.

Return type:

ndarray, ndarray or None, ndarray or None

Examples

>>> from easyidp.pointcloud.io import las
>>> points, colors, normals = las.read("cloud.las")
easyidp.pointcloud.io.las.write(path, points, colors, normals=None, offset=array([0., 0., 0.]), decimal=5)

Write a LAS or LAZ file (LAS version 1.2, point format 2).

Parameters:

  • path (str or pathlib.Path) – Output path (.las or .laz suffix).

  • points (ndarray of shape (N, 3)) – Absolute XYZ coordinates.

  • colors (ndarray of shape (N, 3) or None) – RGB values in [0, 255] as uint8, or None to use zeros.

  • normals (ndarray of shape (N, 3) or None, optional) – Normal vectors.

  • offset (ndarray of shape (3,), optional) – LAS header offset, default [0, 0, 0].

  • decimal (int, optional) – Scale precision exponent, default 5.

Return type:

None

Examples

>>> from easyidp.pointcloud.io import las
>>> las.write("cloud.las", points, colors, offset=np.array([0., 0., 0.]))

PLY Backend

easyidp.pointcloud.io.ply provides low-level array IO for PLY files. It returns and accepts raw NumPy arrays rather than PointCloud objects.

Function

Purpose

read()

Read PLY data into raw arrays.

write()

Write raw arrays to PLY.
easyidp.pointcloud.io.ply.read(path)

Read a PLY file and return (points, colors, normals).

Parameters:

path (str or pathlib.Path) – Path to a .ply file.

Returns:

(points (N,3), colors (N,3) uint8, normals (N,3)). colors and normals are None when not present.

Return type:

ndarray, ndarray or None, ndarray or None

Examples

>>> from easyidp.pointcloud.io import ply
>>> points, colors, normals = ply.read("cloud.ply")
easyidp.pointcloud.io.ply.write(path, points, colors, normals=None, binary=True)

Write a PLY file.

Parameters:

  • path (str or pathlib.Path) – Output path (.ply suffix).

  • points (ndarray of shape (N, 3)) – XYZ coordinates.

  • colors (ndarray of shape (N, 3) or None) – RGB values in [0, 255] as uint8, or None to omit color vertex properties.

  • normals (ndarray of shape (N, 3) or None, optional) – Normal vectors.

  • binary (bool, optional) – True for binary PLY, False for ASCII PLY. Default True.

Return type:

None

Examples

>>> from easyidp.pointcloud.io import ply
>>> ply.write("cloud.ply", points, colors, binary=True)