> 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/core-api/parameters.md).

# Parameters

### Accessing a Parameter

A Parameter is accessed through its Object handle followed by the Parameter path.

For example:

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

This returns the **Parameter handle** itself.

The general access pattern is:

```
sp.<ScriptingID>.<parameterPath>
```

For example:

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

### Parameter Handles

A Parameter handle represents the Parameter itself rather than its current value.

Parameter handles can be stored in variables and reused:

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

The current value can then be accessed through the handle:

```python
print(position.value)
```

{% hint style="info" %}
Without `.value`, the reference points to the Parameter itself rather than its current value.
{% endhint %}

### `.value`

#### Reading a Value

Use `.value` to read the current value of a Parameter.

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

For example:

```python
focus_distance = sp.Camera1.camera.camera.focusDistance.value

print(focus_distance)
```

The returned Python value depends on the Parameter type.

#### Writing a Value

Assign a value to `.value` to change the Parameter.

```python
sp.Camera1.coordinates.position.value = [0, 1, 2]
```

The same can be done through a stored Parameter handle:

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

position.value = [0, 1, 2]
```

The assigned value must be compatible with the Parameter type.

### Parameter Paths

Parameter paths follow the hierarchy of the Object in the Inspector.

A common structure is:

```
Object → Tab → Container → Parameter
```

Additional Containers extend the path:

```
Object → Tab → Container → Container → Parameter
```

For example:

```python
sp.Camera1.camera.camera.focusDistance.value
```

The final `.value` accesses the current value of the Parameter.

For more information about finding and understanding Parameter paths, see **Accessing Objects and Parameters**.

### Multi-Value Parameters

Point, Vector and Color Parameters are represented as Python lists.

For example, a Vector Parameter can return:

```python
[0, 1, 2]
```

Individual values can be accessed using normal Python indexing:

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

x = position[0]
y = position[1]
z = position[2]
```

A component can also be accessed directly:

```python
x = sp.Tracker1.coordinates.position.value[0]
```

See **Data Types & ValueTree** for details about Point, Vector and Color values.

### Parameter Aliases

A Script Alias can point directly to a Parameter.

For example:

```python
sp.alias.posi
```

The returned value is a Parameter handle and can be used in the same way as a directly addressed Parameter:

```python
print(sp.alias.posi.value)
```

or:

```python
sp.alias.posi.value = [99, 88, 77]
```

See **Alias API** for the complete Script Alias reference.

### Point, Vector and Color Values

Point, Vector and Color Parameters are exposed through `.value` as Python lists.

| Parameter Type | Python Value   |
| -------------- | -------------- |
| Point          | `[x, y]`       |
| Vector         | `[x, y, z]`    |
| Color          | `[r, g, b, a]` |

For example, a Vector Parameter can be read as:

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

print(position)
```

Example value:

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

Individual components are accessed through normal Python list indexing:

```python
x = sp.Tracker1.coordinates.position.value[0]
y = sp.Tracker1.coordinates.position.value[1]
z = sp.Tracker1.coordinates.position.value[2]
```

{% hint style="info" %}
Point, Vector and Color Parameter values are exposed as Python lists. They are not returned as `sp.Point`, `sp.Vector` or `sp.Color` objects.
{% endhint %}

### `sp.Point`

`sp.Point` provides a two-component Point helper type.

It can be created with:

```python
point = sp.Point(
    1.0,
    2.0
)
```

Components are available through:

```python
point.x
point.y
```

Both properties can be changed:

```python
point.x = 10.0
point.y = 20.0
```

To use an `sp.Point` as a normal Point Parameter value, convert its components to a list:

```python
value = [
    point.x,
    point.y
]
```

### `sp.Vector`

`sp.Vector` provides a three-component Vector helper type.

It can be created from individual components:

```python
vector = sp.Vector(
    1.0,
    2.0,
    3.0
)
```

or from a list:

```python
vector = sp.Vector(
    [1.0, 2.0, 3.0]
)
```

Components are available through:

```python
vector.x
vector.y
vector.z
```

They can also be changed directly:

```python
vector.x = 10.0
vector.y = 20.0
vector.z = 30.0
```

Convert an `sp.Vector` to a Python list using:

```python
value = vector.list()
```

For example:

```python
vector = sp.Vector(
    1.0,
    2.0,
    3.0
)

print(vector.list())
```

returns:

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

#### Assigning `sp.Vector` to a Parameter

An `sp.Vector` can be assigned directly to a Vector Parameter:

```python
sp.Tracker1.coordinates.position.value = sp.Vector(
    1.0,
    2.0,
    3.0
)
```

Reading the Parameter afterwards still returns its normal Python list representation:

```python
print(
    sp.Tracker1.coordinates.position.value
)
```

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

#### Vector Operations

`sp.Vector` also provides common Vector operations.

Length:

```python
vector.length()
```

Squared length:

```python
vector.lengthSquared()
```

Normalized Vector:

```python
normalised = vector.normalised()
```

Dot product:

```python
result = vector.dot(otherVector)
```

Cross product:

```python
result = vector.cross(otherVector)
```

Axis Vectors are available through:

```python
sp.Vector.xAxis()
sp.Vector.yAxis()
sp.Vector.zAxis()
```

and return:

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

when converted using `.list()`.

### `sp.Color`

`sp.Color` provides an RGBA Color helper type.

A Color can be created from individual floating-point components:

```python
color = sp.Color(
    1.0,
    0.5,
    0.25,
    1.0
)
```

or from an RGBA list:

```python
color = sp.Color(
    [1.0, 0.5, 0.25, 1.0]
)
```

Components are available through:

```python
color.r
color.g
color.b
color.a
```

They can also be changed directly:

```python
color.r = 1.0
color.g = 0.5
color.b = 0.25
color.a = 1.0
```

The Color can be retrieved as an RGBA list through:

```python
color.value
```

For example:

```python
parameterValue = color.value
```

can be used when a normal Color Parameter list value is required.

{% hint style="info" %}
Color component values may not always read back as exactly the same floating-point number that was supplied.

For example, a supplied value such as `0.5` may read back as a nearby value such as `0.5019608`.
{% endhint %}