RTM format¶

The armaio.rtm module provides utilites for reading and writing the RTM animation format. The implementations are based on the Community Wiki RTM page and further research.

For “plain” RTM files, the module supports both reading and writing.

Examples¶

Reading¶

from armaio.rtm import RtmFile

rtm = RtmFile.read_file("animation.rtm")
print(rtm.motion)

Writing¶

from armaio.rtm import RtmFile, RtmFrame

rtm = RtmFile()
rtm.add_property(0.1, "StepSound", "")
bones = ("bone1", "bone2")
frame0 = RtmFrame(0.0, bones)
frame1 = RtmFrame(1.0, bones)

mat = (
    (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)
)
frame1.set_transform(
    "bone1",
    mat
)

rtm.add_frame(frame0)
rtm.add_frame(frame1)

rtm.write_file("animation.rtm")

Exceptions¶

class armaio.rtm.RtmError¶: Exception raised upon RTM reading and writing errors.

Functions¶

armaio.rtm.read_rtm(stream: IO[bytes], skeleton: dict[str, dict[str, BoneStructure]] | tuple[Bone, ...]) → RtmFile¶

Reads RTM animation data from a binary stream.

If the data is in binarized format, the conversion is done automatically.

Parameters:

stream (IO[bytes]) – Source binary stream
skeleton (BoneStructure | BoneSequence) – Skeleton structure data

Returns:

Animation data

Return type:

RtmFile

armaio.rtm.read_rtm_file(filepath: str, skeleton: dict[str, dict[str, BoneStructure]] | tuple[Bone, ...]) → RtmFile¶

Reads RTM animation data from a file at a given path.

If the data is in binarized format, the conversion is done automatically.

Parameters:

filepath (str) – Path to RTM file
skeleton (BoneStructure | BoneSequence) – Skeleton structure data

Returns:

Animation data

Return type:

RtmFile

armaio.rtm.rot_loc_to_matrix(q: RtmQuaternion, v: RtmVector) → tuple[tuple[float, float, float, float], tuple[float, float, float, float], tuple[float, float, float, float], tuple[float, float, float, float]]¶

Converts a quaternion-vector pair to matrix representation.

Parameters:

q (RtmQuaternion) – Orientation
v (RtmVector) – Position

Returns:

Transformation matrix

Return type:

RtmMatrix

Classes¶

class armaio.rtm.RtmProperty(phase: float, name: str, value: str)¶

Name-value property.

Create new instance of RtmProperty(phase, name, value)

name: str¶: Property name.

phase: float¶: Animation phase the property is linked to.

value: str¶: Property value.

armaio.rtm.RtmMatrix¶

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

alias of tuple[tuple[float, float, float, float], tuple[float, float, float, float], tuple[float, float, float, float], tuple[float, float, float, float]]

class armaio.rtm.RtmVector(x: float, y: float, z: float)¶

Vector representing a 3D position.

Create new instance of RtmVector(x, y, z)

x: float¶: Alias for field number 0

y: float¶: Alias for field number 1

z: float¶: Alias for field number 2

class armaio.rtm.RtmQuaternion(x: float, y: float, z: float, w: float)¶

Quaternion representing a 3D rotation.

Create new instance of RtmQuaternion(x, y, z, w)

w: float¶: Alias for field number 3

x: float¶: Alias for field number 0

y: float¶: Alias for field number 1

z: float¶: Alias for field number 2

class armaio.rtm.RtmFrame(phase: float, bones: tuple[str, ...])¶

Animation frame at a given phase, containing the transformation data for all bones.

Parameters:

phase (float) – Animation phase
bones (tuple[str, ...]) – Bones animated in the frame

Raises:

RtmError – Duplicate bones

classmethod from_binarized(frame_bmtr: BmtrFrame, bones: tuple[str, ...], skeleton: dict[str, dict[str, BoneStructure]] | tuple[Bone, ...]) → Self¶

Converts a frame from a binarized RTM to a plain frame.

Note

Plain animations store transformations as absolute 3D transformation matrices, while the binarized format stores them as relative quaternion-vector pairs. Therefore to perform the conversion, the skeleton bone hierarchy must be known.

Parameters:

frame_bmtr (BmtrFrame) – Binarized (BMTR) frame
bones (tuple[str, ...]) – List of bones
skeleton (BoneStructure | BoneSequence) – Skeleton structure data

Returns:

Converted frame

Return type:

Self

classmethod read(stream: IO[bytes], bones: tuple[str, ...]) → Self¶

Reads an animation frame from a binary stream.

Parameters:

stream (IO[bytes]) – Source binary stream
bones (tuple[str, ...]) – List of expected bones

Raises:

RtmError – The bones read did not match the bones provided

Returns:

Animation frame

Return type:

Self

set_transform(bone: str, matrix: tuple[tuple[float, float, float, float], tuple[float, float, float, float], tuple[float, float, float, float], tuple[float, float, float, float]] | None) → None¶

Sets the transformation matrix of a bone.

Parameters:

bone (str) – Name of bone
matrix (RtmMatrix | None) – New transformation matrix

Raises:

ValueError – Bone not found in frame

write(stream: IO[bytes]) → None¶

Writes an animation frame to a binary stream.

Parameters:: stream (IO[bytes]) – Target binary stream

property phase: float¶

Returns:: Animation phase
Return type:: float

property transforms: MappingProxyType¶

Returns:: Bone transformations
Return type:: MappingProxyType[str, RtmMatrix | None]

class armaio.rtm.RtmFile¶

Animation data read from a plain RTM file.

classmethod from_binarized(bmtr: BmtrFile, skeleton: dict[str, dict[str, BoneStructure]] | tuple[Bone, ...]) → Self¶

Converts data from a binarized RTM to plain data.

Note

Plain animations store transformations are absolute 3D transformation matrices, while the binarized format stores them as relative quaternion-vector pairs. Therefore the perform the conversion, the skeleton bone hierarchy must be known.

Parameters:

bmtr (BmtrFile) – Binarized animation data
skeleton (BoneStructure | BoneSequence) – Skeleton structure data

Returns:

Animation data

Return type:

Self

classmethod read(stream: IO[bytes]) → Self¶

Reads animation data from a binary stream.

Parameters:: stream (IO[bytes]) – Source binary stream
Raises:: RtmError – Stream is not valid RTM data
Returns:: Animation data
Return type:: Self

classmethod read_file(filepath: str) → Self¶

Reads an RTM file at a given path.

Parameters:: filepath (str) – Path to RTM file
Returns:: Animation data
Return type:: Self

add_frame(frame: RtmFrame) → None¶

Adds a new frame to the animation.

Parameters:: frame (RtmFrame) – Frame to add
Raises:: ValueError – Bones in frame did not match the expected bones

add_property(phase: float, name: str, value: str) → None¶

Adds a new animation property.

Parameters:

phase (float) – Animation phase to link to
name (str) – Property name
value (str) – Property value

pop_frame(idx: int) → RtmFrame¶

Removes and returns the frame at the given index.

Parameters:: idx (int) – Index to remove.
Returns:: Frame removed.
Return type:: RtmFrame

pop_property(idx: int) → RtmProperty¶

Removes and returns the property at the given index.

Parameters:: idx (int) – Index to remove
Returns:: Removed property
Return type:: RtmProperty

write(stream: IO[bytes]) → None¶

Writes animation data to a binary stream.

Parameters:: stream (IO[bytes]) – Target binary stream
Raises:: RtmError – Data has no frames

write_file(filepath: str) → None¶

Writes animation data to a specific file path.

Parameters:: filepath (str) – Path to RTM file

property bones: tuple[str, ...] | None¶

Returns:: Bones in the animation (None if there are no frames)
Return type:: tuple[str, …] | None

property frames: tuple[RtmFrame, ...]¶

Returns:: Animation frames
Return type:: tuple[RtmFrame, …]

property motion: RtmVector¶

Returns:: Motion vector
Return type:: RtmVector

property properties: tuple[tuple[float, str, str], ...]¶

Returns:: Phase-linked animation properties
Return type:: tuple[tuple[float, str, str], …]

property source: str | None¶

Returns:: Path to source file (None if not read from file)
Return type:: str | None