Point Cloud¶

Class¶

A summary of class easyidp.pointcloud.PointCloud, can be simply accessed by easyidp.PointCloud.

PointCloud([pcd_path, offset])

EasyIDP defined PointCloud class, consists by point coordinates, and optionally point colors and point normals.

Functions¶

These functions are the recommended entry points for reading and writing point cloud files. Use these instead of the legacy per-format functions.

Function	Purpose
`read_point_cloud()`	Read a point-cloud file into a new `PointCloud`.
`write_point_cloud()`	Write a `PointCloud` through explicit format or suffix dispatch.

easyidp.pointcloud.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.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')

Old Compatibility API¶

Caution

The following per-format functions emit FutureWarning and may be deprecated in a future v3.0 release. Prefer read_point_cloud() or write_point_cloud() (or use PointCloud directly).

Function	Replacement
`read_las()`	Use `read_point_cloud()`.
`read_laz()`	Use `read_point_cloud()`.
`read_ply()`	Use `read_point_cloud()`.
`write_las()`	Use `write_point_cloud()`.
`write_laz()`	Use `write_point_cloud()`.
`write_ply()`	Use `write_point_cloud()`.

easyidp.pointcloud.read_las(las_path)¶

Read a LAS file with the legacy standalone API.

Deprecated since version 2.1.0: Use easyidp.pointcloud.read_point_cloud() instead.

Parameters:: las_path (str or pathlib.Path) – Path to a LAS point-cloud file.
Returns:: Raw (points, colors, normals) arrays.
Return type:: tuple[numpy.ndarray, numpy.ndarray or None, numpy.ndarray or None]
Warns:: FutureWarning – Always emitted to guide migration to read_point_cloud().

Examples

>>> points, colors, normals = idp.pointcloud.read_las("cloud.las")
>>> pcd = idp.pointcloud.read_point_cloud("cloud.las")

easyidp.pointcloud.read_laz(laz_path)¶

Read a LAZ file with the legacy standalone API.

Deprecated since version 2.1.0: Use easyidp.pointcloud.read_point_cloud() instead.

Parameters:: laz_path (str or pathlib.Path) – Path to a LAZ point-cloud file.
Returns:: Raw (points, colors, normals) arrays.
Return type:: tuple[numpy.ndarray, numpy.ndarray or None, numpy.ndarray or None]
Warns:: FutureWarning – Always emitted to guide migration to read_point_cloud().

Examples

>>> points, colors, normals = idp.pointcloud.read_laz("cloud.laz")
>>> pcd = idp.pointcloud.read_point_cloud("cloud.laz")

easyidp.pointcloud.read_ply(ply_path)¶

Read a PLY file with the legacy standalone API.

Deprecated since version 2.1.0: Use easyidp.pointcloud.read_point_cloud() instead.

Parameters:: ply_path (str or pathlib.Path) – Path to a PLY point-cloud file.
Returns:: Raw (points, colors, normals) arrays.
Return type:: tuple[numpy.ndarray, numpy.ndarray or None, numpy.ndarray or None]
Warns:: FutureWarning – Always emitted to guide migration to read_point_cloud().

Examples

>>> points, colors, normals = idp.pointcloud.read_ply("cloud.ply")
>>> pcd = idp.pointcloud.read_point_cloud("cloud.ply")

easyidp.pointcloud.write_las(las_path, points, colors, normals=None, offset=array([0., 0., 0.]), decimal=5)¶

Write a LAS file with the legacy standalone API.

Deprecated since version 2.1.0: Use easyidp.pointcloud.write_point_cloud() instead.

Parameters:

las_path (str or pathlib.Path) – Output LAS path.
points (numpy.ndarray of shape (N, 3)) – Absolute XYZ coordinates.
colors (numpy.ndarray of shape (N, 3) or None) – RGB values as uint8. None writes zero-valued LAS colors.
normals (numpy.ndarray of shape (N, 3) or None, optional) – Normal vectors.
offset (numpy.ndarray of shape (3,), optional) – LAS header offset.
decimal (int, optional) – Number of decimal digits used to build LAS scale values.

Return type:

None

Warns:

FutureWarning – Always emitted to guide migration to write_point_cloud().

Examples

>>> idp.pointcloud.write_las("cloud.las", points, colors)
>>> pcd = idp.PointCloud()
>>> pcd.points = points
>>> pcd.colors = colors
>>> idp.pointcloud.write_point_cloud("cloud.las", pcd)

easyidp.pointcloud.write_laz(laz_path, points, colors, normals=None, offset=array([0., 0., 0.]), decimal=5)¶

Write a LAZ file with the legacy standalone API.

Deprecated since version 2.1.0: Use easyidp.pointcloud.write_point_cloud() instead.

Parameters:

laz_path (str or pathlib.Path) – Output LAZ path.
points (numpy.ndarray of shape (N, 3)) – Absolute XYZ coordinates.
colors (numpy.ndarray of shape (N, 3) or None) – RGB values as uint8. None writes zero-valued LAS colors.
normals (numpy.ndarray of shape (N, 3) or None, optional) – Normal vectors.
offset (numpy.ndarray of shape (3,), optional) – LAS header offset.
decimal (int, optional) – Number of decimal digits used to build LAS scale values.

Return type:

None

Warns:

FutureWarning – Always emitted to guide migration to write_point_cloud().

Examples

>>> idp.pointcloud.write_laz("cloud.laz", points, colors)
>>> pcd = idp.PointCloud()
>>> pcd.points = points
>>> pcd.colors = colors
>>> idp.pointcloud.write_point_cloud("cloud.laz", pcd)

easyidp.pointcloud.write_ply(ply_path, points, colors, normals=None, binary=True)¶

Write a PLY file with the legacy standalone API.

Deprecated since version 2.1.0: Use easyidp.pointcloud.write_point_cloud() instead.

Parameters:

ply_path (str or pathlib.Path) – Output PLY path.
points (numpy.ndarray of shape (N, 3)) – Absolute XYZ coordinates.
colors (numpy.ndarray of shape (N, 3) or None) – RGB values as uint8. None writes a no-color PLY.
normals (numpy.ndarray of shape (N, 3) or None, optional) – Normal vectors.
binary (bool, optional) – Write binary PLY when True, ASCII PLY when False.

Return type:

None

Warns:

FutureWarning – Always emitted to guide migration to write_point_cloud().

Examples

>>> idp.pointcloud.write_ply("cloud.ply", points, colors)
>>> pcd = idp.PointCloud()
>>> pcd.points = points
>>> pcd.colors = colors
>>> idp.pointcloud.write_point_cloud("cloud.ply", pcd)

Advanced API¶

Advanced APIs are documented as compact module pages instead of one page per helper function:

Page	Scope
compat	Legacy wrappers and `PointCloudCompatMixin` implementation notes.
geometry	KDTree-backed polygon and multipolygon point selection helpers.
io	Public IO dispatchers and low-level LAS/PLY backend helpers.

Internal PointCloud helper methods and compatibility implementation details are maintained from these module-level advanced pages, not from the main PointCloud class page.