# `ExCodecs.Spatial.Transform`
[🔗](https://github.com/AnimaLogica/codecs/blob/v0.2.4/lib/ex_codecs/spatial/transform.ex#L1)

Rigid/similarity transform metadata, not applied to points by this library.

**Reserved for future use.** No shipped codec reads or writes `Transform`
fields today. The module is provided so that formats which embed pose
metadata (e.g. EXCP v2) can use a shared type when that support lands.
Application of transforms is left to higher-level code.

## Fields

  * `:translation` — `{float(), float(), float()}` Cartesian offset; defaults
    to `{0.0, 0.0, 0.0}`. Units match the associated spatial coordinates.
  * `:rotation` — `{float(), float(), float(), float()}` scalar-first
    `{w, x, y, z}` quaternion; defaults to identity
    `{1.0, 0.0, 0.0, 0.0}`. Unit length is not enforced.
  * `:scale` — `float()` uniform dimensionless scale; defaults to `1.0`.

This module stores transform metadata but does not define composition order
or apply transforms; consumers must follow the enclosing format's convention.

## Example

    iex> ExCodecs.Spatial.Transform.new(
    ...>   translation: {10, 0, -2},
    ...>   rotation: {1, 0, 0, 0},
    ...>   scale: 0.5
    ...> )
    %ExCodecs.Spatial.Transform{
      translation: {10.0, 0.0, -2.0},
      rotation: {1.0, 0.0, 0.0, 0.0},
      scale: 0.5
    }

# `t`

```elixir
@type t() :: %ExCodecs.Spatial.Transform{
  rotation: {float(), float(), float(), float()},
  scale: float(),
  translation: {float(), float(), float()}
}
```

Transform metadata with translation, scalar-first quaternion rotation, and
uniform scale. See the module documentation for all fields, defaults, units
and conventions, and a construction example.

# `identity`

```elixir
@spec identity() :: t()
```

Identity transform.

## Arguments

None.

## Returns

`%Transform{}` with zero translation, identity quaternion, scale `1.0`.

## Raises

None.

## Examples

    iex> t = ExCodecs.Spatial.Transform.identity()
    iex> t.scale
    1.0

# `new`

```elixir
@spec new(keyword()) :: t()
```

Builds a transform.

## Arguments

  * `opts` — a keyword list with:
    * `:translation` — numeric `{x, y, z}`; defaults to the origin and is
      stored as floats.
    * `:rotation` — numeric `{w, x, y, z}` scalar-first quaternion; defaults
      to identity and is stored as floats.
    * `:scale` — `number()`; defaults to `1.0` and is stored as a float.

## Returns

`%Transform{}`

## Raises

* `FunctionClauseError` for malformed or non-numeric translation/rotation
  tuples, or if `opts` is not a keyword list.
* `ArithmeticError` if `:scale` is not numeric.

## Examples

    iex> t = ExCodecs.Spatial.Transform.new(translation: {1, 0, 0}, scale: 2)
    iex> t.translation
    {1.0, 0.0, 0.0}

---

*Consult [api-reference.md](api-reference.md) for complete listing*