ExCodecs.Spatial.Point (ex_codecs v0.2.3)

A 3D point with optional color, surface normal, and attributes.

Fields

:x, :y, :z — float() Cartesian coordinates. new/4 requires them and converts numbers to floats; the struct defaults are 0.0. Units are application-defined and must be consistent within a cloud.
:color — rgb() | rgba() | nil; defaults to nil. Channels are non-negative integers conventionally in 0..255; alpha is last.
:normal — normal() | nil; defaults to nil. Components follow the same axis convention as the coordinates and are normally unit length, though this module does not normalize them.
:attributes — attributes(); defaults to %{}. Keys are strings (atoms passed to new/4 are converted via to_string/1). Values are numbers or binaries.

Example

iex> ExCodecs.Spatial.Point.new(1, 2.5, -3, color: {255, 128, 0}, normal: {0.0, 0.0, 1.0})
%ExCodecs.Spatial.Point{
  x: 1.0,
  y: 2.5,
  z: -3.0,
  color: {255, 128, 0},
  normal: {0.0, 0.0, 1.0},
  attributes: %{}
}

Summary

Types

attributes()

User attributes keyed by strings, with numeric or binary values. For example, %{"intensity" => 0.82, "classification" => 2}. Atom keys passed to new/4 are normalized to strings.

normal()

A surface-normal vector {nx, ny, nz} in the point coordinate convention. Unit length is conventional but is not enforced. For example, {0.0, 0.0, 1.0} points along the positive Z axis.

rgb()

An RGB color tuple {red, green, blue}. Channels are non-negative integers, conventionally in 0..255; that range is not enforced. For example, {255, 128, 0} represents orange.

rgba()

An RGBA color tuple {red, green, blue, alpha}. Channels are non-negative integers, conventionally in 0..255; that range is not enforced. For example, {0, 64, 255, 128} is a half-transparent blue.

t()

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

Functions

colored?(point)

Returns whether the point has RGB or RGBA color.

coords(point)

Returns {x, y, z}.

has_normal?(point)

Returns whether the point has a surface normal.

new(x, y, z, opts \\ [])

Builds a point from coordinates and optional fields.

Types

attributes()

@type attributes() :: %{optional(String.t()) => number() | binary()}

User attributes keyed by strings, with numeric or binary values. For example, %{"intensity" => 0.82, "classification" => 2}. Atom keys passed to new/4 are normalized to strings.

PLY encode (the only codec that stores attributes) accepts numeric attribute values only; binary values will cause an encode error. Use cloud-level Metadata for non-numeric payloads.

normal()

@type normal() :: {float(), float(), float()}

A surface-normal vector {nx, ny, nz} in the point coordinate convention. Unit length is conventional but is not enforced. For example, {0.0, 0.0, 1.0} points along the positive Z axis.

rgb()

@type rgb() :: {non_neg_integer(), non_neg_integer(), non_neg_integer()}

An RGB color tuple {red, green, blue}. Channels are non-negative integers, conventionally in 0..255; that range is not enforced. For example, {255, 128, 0} represents orange.

rgba()

@type rgba() ::
  {non_neg_integer(), non_neg_integer(), non_neg_integer(), non_neg_integer()}

t()

@type t() :: %ExCodecs.Spatial.Point{
  attributes: attributes(),
  color: rgb() | rgba() | nil,
  normal: normal() | nil,
  x: float(),
  y: float(),
  z: float()
}

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

Functions

colored?(point)

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

Returns whether the point has RGB or RGBA color.

Arguments

point — %Point{}

Returns

true | false

Raises

FunctionClauseError if the argument is not a %Point{} or its :color is neither nil, a 3-tuple, nor a 4-tuple.

Examples

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

coords(point)

@spec coords(t()) :: {float(), float(), float()}

Returns {x, y, z}.

Arguments

point — %Point{}

Returns

{float(), float(), float()}

Raises

FunctionClauseError if point is not a %Point{}.

Examples

iex> ExCodecs.Spatial.Point.coords(ExCodecs.Spatial.Point.new(1, 2, 3))
{1.0, 2.0, 3.0}

has_normal?(point)

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

Returns whether the point has a surface normal.

Arguments

point — %Point{}

Returns

true | false

Raises

FunctionClauseError if the argument is not a %Point{} or its :normal is neither nil nor a 3-tuple.

Examples

iex> ExCodecs.Spatial.Point.has_normal?(ExCodecs.Spatial.Point.new(0, 0, 0))
false
iex> ExCodecs.Spatial.Point.has_normal?(ExCodecs.Spatial.Point.new(0, 0, 0, normal: {0.0, 1.0, 0.0}))
true

new(x, y, z, opts \\ [])

@spec new(number(), number(), number(), keyword()) :: t()

Builds a point from coordinates and optional fields.

Arguments

x, y, z — numbers (stored as floats)
opts:
- :color — rgb or rgba tuple, or nil
- :normal — {nx, ny, nz} or nil
- :attributes — map of string keys (default %{}); atom keys are stringified

Returns

%ExCodecs.Spatial.Point{}

Raises

FunctionClauseError if a coordinate is not numeric, or if opts is not a keyword list accepted by Keyword.get/3.

Notes

Literal %Point{} construction with atom-keyed attributes bypasses stringification; codecs that read attributes (e.g. PLY) treat atom keys as missing and default them to 0.0. Always use Point.new/4 or pre-stringify keys when the point will be encoded.

Examples

iex> p = ExCodecs.Spatial.Point.new(1.0, 2.0, 3.0)
iex> {p.x, p.y, p.z}
{1.0, 2.0, 3.0}

iex> p = ExCodecs.Spatial.Point.new(0.0, 0.0, 0.0, color: {255, 128, 0})
iex> p.color
{255, 128, 0}