A structure that identifies a local transform relative to an entity or entity's animating skeletal joint.
A geometric pin has a base transform and allows an optional offset relative to the base transform.
The base transform is only available when the pin attaches to an entity.
When a geometric pin does not attach to any entity (i.e. `GeometricPin/entity` is `nil`),
the pin is just a floating local transform relative to some space to be defined.
The pin's query function such as
`GeometricPin/position` or `GeometricPin/orientation` returns the local offset in this case.
After a geometric pin has attached to an entity, or `GeometricPin/entity` is not `nil`, the base transform may be available.
If you construct a geometric pin with a generic name, the base transform resolves to the transform of the pin's owning entity.
If you construct a geometric pin with a skeletal joint name, the base transform resolves to the current transform
of the skeletal joint with the matching joint name.
When the base transform is available, the pin's query function such as `GeometricPin/position` or `GeometricPin/orientation` returns the base transform with the offset applied.
You can attach a pin to an entity by creating a `GeometricPin`, adding it to a ``GeometricPinsComponent``, and finally setting
the ``GeometricPinsComponent`` to an `Entity`.
```swift
let pin = GeometricPin(named: "genericPin")
let skeletalJointPin = GeometricPin(named: "animatingPin", skeletalJointName: "hand")
var pinsComponent = GeometricPinsComponent()
pinsComponent.set(pin)
pinsComponent.set(skeletalJointPin)
let entity = Entity()
entity.components.set(pinsComponent)
```
Another way to attach a pin is to add the `GeometricPin` to the ``Entity/pins`` collection directly.
```swift
let entity = Entity()
let pin = entity.pins.set(named: "genericPin")
let skeletalJointPin = entity.pins.set(named: "animatingPin", skeletalJointName: "hand")
```
Note that when adding a geometric pin the API does not validate the skeletal joint name. The validation only happens
when the base transform is evaluating, for example during the call to `GeometricPin/position` or `GeometricPin/orientation`.
If the skeletal joint name does not match any valid skeletal joint, those query functions return `nil`.
Each geometric pin has a unique name to identify itself from other pins on an entity.
You can use the subscript operator to retrieve a pin.
```swift
// To retrieve the skeletal joint pin in the previous snippet:
let retrievedPin = pinsComponent["animatingPin"]
```
Calculates and returns the current orientation of the pin relative to a reference entity, adjusted by the optional offset position.
- Parameter referenceEntity: Reference `Entity` which defines the frame of reference for the returned orientation.
Can be `nil`, which is equivalent to "world space".
get · iOS 18.0+
orientation
TypeScript
get orientation(): Promise<(SDKHandle) | null>
Swift declaration
@MainActor var orientation: simd_quatf? { get }
Calculates and returns the current orientation of the pin relative to the pin's owning entity, adjusted by the optional offset orientation.
If the pin is on a skeletal joint but there is no skeletal joint matching the given skeletal joint name, this property returns `nil`.
get · iOS 18.0+
offsetPosition
TypeScript
get offsetPosition(): SDKHandle
Swift declaration
var offsetPosition: SIMD3<Float> { get set }
Offset from the pin's base position.
If a pin has a generic name, this offset is relative to the pin's owning entity's position.
If a pin is on a skeletal joint, this offset is relative to the skeletal joint's current position.
By default this offset is the zero position vector.
set · iOS 18.0+
offsetPosition
TypeScript
set offsetPosition(value: SDKHandle)
Swift declaration
var offsetPosition: SIMD3<Float> { get set }
Offset from the pin's base position.
If a pin has a generic name, this offset is relative to the pin's owning entity's position.
If a pin is on a skeletal joint, this offset is relative to the skeletal joint's current position.
By default this offset is the zero position vector.
get · iOS 18.0+
offsetOrientation
TypeScript
get offsetOrientation(): SDKHandle
Swift declaration
var offsetOrientation: simd_quatf { get set }
Offset from the pin's base orientation.
If a pin has a generic name, this offset is relative to the pin's owning entity's orientation.
If a pin is on a skeletal joint, this offset is relative to the skeletal joint's current orientation.
By default this offset is the identity rotation.
set · iOS 18.0+
offsetOrientation
TypeScript
set offsetOrientation(value: SDKHandle)
Swift declaration
var offsetOrientation: simd_quatf { get set }
Offset from the pin's base orientation.
If a pin has a generic name, this offset is relative to the pin's owning entity's orientation.
If a pin is on a skeletal joint, this offset is relative to the skeletal joint's current orientation.
By default this offset is the identity rotation.
get · iOS 18.0+
name
TypeScript
get name(): string
Swift declaration
var name: String
The name of the pin.
Each ``GeometricPins`` for an``Entity``
have unique names. Adding a pin with the same name as another
overrides the duplicate.
set · iOS 18.0+
name
TypeScript
set name(value: string)
Swift declaration
var name: String
The name of the pin.
Each ``GeometricPins`` for an``Entity``
have unique names. Adding a pin with the same name as another
overrides the duplicate.
Creates a geometric pin that identifies a local position and orientation.
- Parameters:
- name: Name of the `GeometricPin` in the namespace of the owning entity.
- offsetPosition: Adjustment of the `GeometricPin` position in the local coordinate frame.
- offsetOrientation: Adjustment of the `GeometricPin` orientation in the local coordinate frame.
Creates a geometric pin that attaches to a skeletal joint.
The current animated joint transform defines the position and orientation of the pin.
- Parameters:
- name: Name of the `GeometricPin` in the namespace of the owning entity.
- skeletalJointName: Name of the skeletal joint that this pin attaches to.
- offsetPosition: Adjustment of the `GeometricPin` position in the coordinate frame of the joint.
- offsetOrientation: Adjustment of the `GeometricPin` orientation in the coordinate frame of the joint.
Calculates and returns the current position of the pin relative to a reference entity, adjusted by the optional offset position.
- Parameter referenceEntity: Reference `Entity` which defines the frame of reference for the returned position.
Can be `nil`, which is equivalent to "world space".
get · iOS 18.0+
position
TypeScript
get position(): Promise<(SDKHandle) | null>
Swift declaration
@MainActor var position: SIMD3<Float>? { get }
Calculates and returns the current position of the pin relative to the pin's owning entity, adjusted by the optional offset position.
If the pin is on a skeletal joint but there is no skeletal joint matching the given skeletal joint name, this property returns `nil`.
