ExCodecs.Spatial.PointCloud (ex_codecs v0.2.3)

Copy Markdown View Source

A collection of %ExCodecs.Spatial.Point{} values with bounds and metadata.

Fields

  • :points — [Point.t()]; defaults to []. Ordering is preserved. Coordinate units and conventions are defined by the application.

  • :bounds — Bounds.t() | nil; defaults to nil. new/2 computes an axis-aligned box by default; nil also represents an empty cloud or deliberately uncomputed bounds.

  • :metadata — Metadata.t(); defaults to %Metadata{}.

Example

iex> alias ExCodecs.Spatial.{Point, PointCloud}
iex> cloud = PointCloud.new([Point.new(0, 0, 0), Point.new(2, 1, -1)])
iex> {PointCloud.size(cloud), cloud.bounds.max_x}
{2, 2.0}

Summary

Types

t()

A point cloud. See the module documentation for every field, its default, units or conventions, and a construction example.

Functions

add_point(cloud, point)

Appends one point and expands bounds.

add_points(cloud, new_points)

Appends many points in one concat and one bounds fold (O(n)).

colored?(point_cloud)

Returns true when every point has color (empty cloud → false).

has_normals?(point_cloud)

Returns true when every point has a normal (empty → false).

new(points, opts \\ [])

Builds a point cloud from a list of points.

size(point_cloud)

Number of points.

with_bounds(cloud)

Recomputes axis-aligned bounds from points.

Types

t()

@type t() :: %ExCodecs.Spatial.PointCloud{
  bounds: ExCodecs.Spatial.Bounds.t() | nil,
  metadata: ExCodecs.Spatial.Metadata.t(),
  points: [ExCodecs.Spatial.Point.t()]
}

A point cloud. See the module documentation for every field, its default, units or conventions, and a construction example.

Functions

add_point(cloud, point)

@spec add_point(t(), ExCodecs.Spatial.Point.t()) :: t()

Appends one point and expands bounds.

Prefer new/1 or add_points/2 for bulk inserts (++ is O(n)).

Arguments

  • cloud — %PointCloud{}
  • point — %Point{}

Returns

Updated %PointCloud{}

Raises

  • FunctionClauseError unless the arguments are a %PointCloud{} and a %Point{}, or if existing bounds are neither nil nor %Bounds{}.

Examples

iex> alias ExCodecs.Spatial.{Point, PointCloud}
iex> c = PointCloud.new([])
iex> PointCloud.size(PointCloud.add_point(c, Point.new(1, 2, 3)))
1

add_points(cloud, new_points)

@spec add_points(t(), [ExCodecs.Spatial.Point.t()]) :: t()

Appends many points in one concat and one bounds fold (O(n)).

Prefer this over repeated add_point/2 for bulk inserts.

Arguments

  • cloud — %PointCloud{}
  • new_points — list of %Point{}

Returns

Updated %PointCloud{}

Raises

  • FunctionClauseError unless cloud is a %PointCloud{} and new_points is a list, or if any element is not a %Point{}.

Examples

iex> alias ExCodecs.Spatial.{Point, PointCloud}
iex> c = PointCloud.add_points(PointCloud.new([]), [Point.new(0, 0, 0), Point.new(1, 1, 1)])
iex> PointCloud.size(c)
2

colored?(point_cloud)

@spec colored?(t()) :: boolean()

Returns true when every point has color (empty cloud → false).

Arguments

  • cloud — %PointCloud{}

Returns

boolean

Raises

  • FunctionClauseError if cloud is not a %PointCloud{}, or if any point has an unsupported :color value.

Examples

iex> alias ExCodecs.Spatial.{Point, PointCloud}
iex> PointCloud.colored?(PointCloud.new([Point.new(0, 0, 0, color: {1, 2, 3})]))
true

has_normals?(point_cloud)

@spec has_normals?(t()) :: boolean()

Returns true when every point has a normal (empty → false).

Arguments

  • cloud — %PointCloud{}

Returns

boolean

Raises

  • FunctionClauseError if cloud is not a %PointCloud{}, or if any point has an unsupported :normal value.

Examples

iex> alias ExCodecs.Spatial.{Point, PointCloud}
iex> PointCloud.has_normals?(PointCloud.new([Point.new(0, 0, 0)]))
false

new(points, opts \\ [])

@spec new(
  [ExCodecs.Spatial.Point.t()],
  keyword()
) :: t()

Builds a point cloud from a list of points.

Arguments

  • points — list of %Point{}
  • opts:
    • :compute_bounds — boolean (default true)
    • :bounds — explicit %Bounds{} (overrides compute)
    • :metadata — %Metadata{}

Returns

%PointCloud{}

Raises

  • FunctionClauseError if points is not a list, an element is not point-like while bounds are computed, or opts is not a keyword list.

Examples

iex> alias ExCodecs.Spatial.{Point, PointCloud}
iex> cloud = PointCloud.new([Point.new(0, 0, 0), Point.new(1, 1, 1)])
iex> PointCloud.size(cloud)
2

size(point_cloud)

@spec size(t()) :: non_neg_integer()

Number of points.

Arguments

  • cloud — %PointCloud{}

Returns

non-negative integer

Raises

Examples

iex> ExCodecs.Spatial.PointCloud.size(ExCodecs.Spatial.PointCloud.new([]))
0

with_bounds(cloud)

@spec with_bounds(t()) :: t()

Recomputes axis-aligned bounds from points.

Arguments

  • cloud — %PointCloud{}

Returns

%PointCloud{} with updated bounds

Raises

  • FunctionClauseError if cloud is not a %PointCloud{} or a point is not a supported point-like value.

Examples

iex> alias ExCodecs.Spatial.{Point, PointCloud}
iex> cloud = PointCloud.new([Point.new(0, 0, 0)], compute_bounds: false)
iex> PointCloud.with_bounds(cloud).bounds != nil
true