> For the complete documentation index, see [llms.txt](https://stage-precision.gitbook.io/grid/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://stage-precision.gitbook.io/grid/scripting/api-reference/object-apis/spatial-objects.md).

# Spatial Objects

{% hint style="info" %}
The Spatial Object API is only available on Object types that provide spatial coordinates.

For example, this API is available on Camera and Tracker Objects, but not on non-spatial Objects such as Data Tree Objects.
{% endhint %}

### Coordinates

Spatial Objects provide a `coordinates` Container.

For example:

```python
sp.Camera1.coordinates
```

or:

```python
sp.Tracker1.coordinates
```

The Container exposes the Object's local coordinate Parameters.

#### Position

```python
sp.Camera1.coordinates.position.value
```

Returns a Vector as a Python list:

```python
[x, y, z]
```

Example:

```python
position = sp.Camera1.coordinates.position.value
```

#### Rotation

```python
sp.Camera1.coordinates.rotation.value
```

Returns the local Euler rotation as:

```python
[x, y, z]
```

The values are represented in **degrees**.

Example:

```python
rotation = sp.Camera1.coordinates.rotation.value
```

#### Scale

```python
sp.Camera1.coordinates.scale.value
```

Returns the Object scale as a `float`.

#### Velocity

```python
sp.Camera1.coordinates.velocity.value
```

Returns:

```python
[x, y, z]
```

#### Acceleration

```python
sp.Camera1.coordinates.acceleration.value
```

Returns:

```python
[x, y, z]
```

### `getGlobalPosition()`

Returns the Object's position in global coordinates.

#### Syntax

```python
object.getGlobalPosition()
```

#### Returns

`list`

```python
[x, y, z]
```

#### Example

```python
position = sp.Camera1.getGlobalPosition()

print(position)
```

Example result:

```python
[1.0, 2.0, 3.0]
```

### `setLocalPosition()`

Sets the local position of the Object.

#### Syntax

```python
object.setLocalPosition(position)
```

#### Parameters

| Parameter  | Type   | Description                   |
| ---------- | ------ | ----------------------------- |
| `position` | `list` | Local position as `[x, y, z]` |

#### Returns

`None`

#### Example

```python
sp.Camera1.setLocalPosition(
    [1.0, 2.0, 3.0]
)
```

The Vector must be supplied as a single list.

### `setLocalRotation()`

Sets the local Euler rotation of the Object.

#### Syntax

```python
object.setLocalRotation(rotation)
```

#### Parameters

| Parameter  | Type   | Description                         |
| ---------- | ------ | ----------------------------------- |
| `rotation` | `list` | Local Euler rotation as `[x, y, z]` |

#### Returns

`None`

{% hint style="warning" %}
`setLocalRotation()` expects rotation values in **radians**, while `coordinates.rotation.value` represents rotation in **degrees**.
{% endhint %}

For example, to set a rotation of 90 degrees around X:

```python
import math

sp.Camera1.setLocalRotation([
    math.radians(90.0),
    0.0,
    0.0
])
```

The corresponding Parameter value is then:

```python
sp.Camera1.coordinates.rotation.value
```

```
[90.0, 0.0, 0.0]
```

### `getGlobalMatrix()`

Returns the Object's global 4 × 4 transformation matrix as a flat list.

#### Syntax

```python
object.getGlobalMatrix()
```

#### Returns

`list`

A list containing 16 floating-point values.

For an Object without translation or rotation:

```python
[
    1.0, 0.0, 0.0, 0.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    0.0, 0.0, 0.0, 1.0
]
```

The global translation is stored at:

```
Index 12 → X
Index 13 → Y
Index 14 → Z
```

For example, an Object positioned at `[1, 2, 3]` can return:

```python
[
    1.0, 0.0, 0.0, 0.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    1.0, 2.0, 3.0, 1.0
]
```

### `setGlobalMatrix()`

Sets the global transformation matrix of the Object.

#### Syntax

```python
object.setGlobalMatrix(matrix)
```

#### Parameters

| Parameter | Type   | Description                                |
| --------- | ------ | ------------------------------------------ |
| `matrix`  | `list` | Transformation matrix containing 16 values |

#### Returns

`None`

The function accepts the same flat 16-value matrix format returned by `getGlobalMatrix()`.

#### Example

```python
matrix = [
    1.0, 0.0, 0.0, 0.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    1.0, 2.0, 3.0, 1.0
]

sp.Camera1.setGlobalMatrix(matrix)
```

The resulting global position is:

```python
sp.Camera1.getGlobalPosition()
```

```
[1.0, 2.0, 3.0]
```

{% hint style="info" %}
A matrix returned by `getGlobalMatrix()` can be passed directly back to `setGlobalMatrix()`.
{% endhint %}

### Local and Global Access

Use the `coordinates` Parameters when working with the Object's local transform:

```python
sp.Camera1.coordinates.position.value
sp.Camera1.coordinates.rotation.value
```

Use the global functions when the resolved transform in global space is required:

```python
sp.Camera1.getGlobalPosition()
sp.Camera1.getGlobalMatrix()
```

### Quick Reference

| API                                     | Returns | Description                                       |
| --------------------------------------- | ------- | ------------------------------------------------- |
| `object.coordinates.position.value`     | `list`  | Local position `[x, y, z]`                        |
| `object.coordinates.rotation.value`     | `list`  | Local Euler rotation in degrees                   |
| `object.coordinates.scale.value`        | `float` | Object scale                                      |
| `object.coordinates.velocity.value`     | `list`  | Velocity `[x, y, z]`                              |
| `object.coordinates.acceleration.value` | `list`  | Acceleration `[x, y, z]`                          |
| `object.getGlobalPosition()`            | `list`  | Returns global position                           |
| `object.setLocalPosition(position)`     | `None`  | Sets local position                               |
| `object.setLocalRotation(rotation)`     | `None`  | Sets local rotation in radians                    |
| `object.getGlobalMatrix()`              | `list`  | Returns the 16-value global transformation matrix |
| `object.setGlobalMatrix(matrix)`        | `None`  | Sets the global transformation matrix             |