Format de fichier¶

Les deux fichiers d'OTS sont du JSON UTF-8 simple, indenté et lisible. Vous pouvez en ouvrir un dans un éditeur de texte, en differ deux dans un gestionnaire de versions, ou écrire un script qui en lit un. C'est délibéré — un format d'échange que vous ne pouvez pas inspecter est un format d'échange que vous ne pouvez pas déboguer.

Le format actuel est la version 4.

En-tête commun¶

Les deux formats commencent de la même façon :

{
  "format": "octo_anm",
  "version": 4,
  "source": "harmony",
  "fps": 24.0,
  "coordinate_system": {
    "up": "y",
    "hand": "right",
    "unit": "meters",
    "rot_order": "xyz",
    "rot_repr_anim": "euler_deg",
    "rot_repr_rest": "quat_wxyz"
  }
}

Clé	Signification
`format`	`octo_pvt` ou `octo_anm`
`version`	La version du format. Doit correspondre exactement — voir ci-dessous
`source`	Quelle application l'a écrit : `harmony`, `blender` ou `maya`
`fps`	La cadence d'images de la scène source
`coordinate_system`	L'espace dans lequel sont les valeurs — voir Systèmes de coordonnées

Pas de migration ascendante

Un reader n'accepte que sa propre version. Un fichier v3 chargé dans un build v4 signale :

unsupported version 3 (this build writes/reads v4; no backward migration — re-export from the source DCC)

C'est un choix, pas un oubli. Migrer silencieusement un vieux fichier revient à deviner ce que ses nombres voulaient dire, et une mauvaise supposition produit un rig subtilement faux plutôt que manifestement cassé. Réexporter depuis la source prend quelques secondes et est toujours correct.

`.pvt` — fichier de pivot¶

{
  "format": "octo_pvt",
  "version": 4,
  "source": "harmony",
  "name": "spaceship",
  "scale_factor": 1.0,
  "pivot_space": "local",
  "fps": 24.0,
  "coordinate_system": { "…": "…" },
  "bones": [
    {
      "name": "hip",
      "parent": null,
      "pivot": [0.0, 0.0, 0.0],
      "rotation": [1.0, 0.0, 0.0, 0.0],
      "path": "Armature/hip",
      "rig": "spaceship",
      "is_camera": false
    }
  ],
  "cameras": []
}

Clé	Signification
`name`	Le nom du rig
`scale_factor`	L'option Scale exposée à l'utilisateur. Les pivots sont multipliés par elle à l'écriture, divisés à la lecture
`pivot_space`	`local` (relatif au parent) ou `armature`
`bones[].pivot`	Position de rest
`bones[].rotation`	Rotation de rest, sous forme de quaternion `[w, x, y, z]`
`bones[].path`	Le chemin complet de l'élément dans sa scène source — utilisé pour la correspondance, et pour garder distincts des éléments de même nom dans des rigs différents
`bones[].rig`	Le tag de rig

path, rig et is_camera sont omis quand ils sont vides, pour qu'un fichier simple reste petit.

`.anm` — fichier d'animation¶

{
  "format": "octo_anm",
  "version": 4,
  "source": "maya",
  "frame_range": [1, 60],
  "fps": 24.0,
  "coordinate_system": { "…": "…" },
  "pegs": [
    {
      "name": "hip-P",
      "path": "Top/spaceship/hip-P",
      "parent": "root",
      "rest_pivot": [0.0, 0.0, 0.0],
      "rest_rotation": [1.0, 0.0, 0.0, 0.0],
      "rig": "spaceship",
      "is_camera": false,
      "source_modes": {
        "position": "separate",
        "rotation": "euler",
        "scale": "separate",
        "enable_3d": true
      },
      "keyframes": [
        {
          "frame": 1,
          "pos": [0.0, 0.0, 0.0],
          "rot": [0.0, 0.0, 0.0],
          "rot_quat": [1.0, 0.0, 0.0, 0.0],
          "scl": [1.0, 1.0, 1.0],
          "interp": "BEZIER",
          "handles": { "pos": [], "rot": [], "scl": [] }
        }
      ]
    }
  ],
  "cameras": []
}

Les champs d'autosuffisance¶

parent, rest_pivot, rest_rotation et rig sont le contenu du .pvt, replié dans chaque peg. C'est la raison pour laquelle Create Rig peut construire un squelette fonctionnel à partir d'un .anm seul. Voir Fichiers d'animation (.anm).

Keyframes¶

Clé	Signification
`frame`	Numéro de frame
`pos`	Position, en mètres canoniques
`rot`	Euler XYZ, degrés — la forme lisible par un humain
`rot_quat`	La même rotation sous forme de quaternion `[w, x, y, z]`, issue du bake de la world matrix
`scl`	Scale
`interp`	`BEZIER`, `LINEAR` ou `CONSTANT`
`handles`	Handles bezier absolus, par axe, regroupés par canal

rot_quat l'emporte

Quand les deux sont présents, rot_quat fait autorité et tous les importeurs le préfèrent. Il est indépendant de l'ordre, donc il contourne entièrement l'ambiguïté d'ordre d'Euler. rot est conservé comme repli lisible.

Les handles ne sont pas émis à côté de rot_quat par les bakes de Maya et de Blender, parce que des handles en repère local ne se transposent pas sur une courbe world bakée. Le type d'interpolation, lui, voyage quand même.

Les handles sont des paires absolues [[left_x, left_y], [right_x, right_y]] dans l'espace (frame, valeur) — une par axe, regroupées en pos, rot et scl. Absolues plutôt que relatives, pour ne pas avoir à être redérivées par rapport à une cadence d'images à l'entrée.

`source_modes`¶

Un relevé de la façon dont le peg a été créé dans son application source — position séparée ou basée sur un path, rotation Euler ou quaternion-path, et si la 3D était activée.

C'est un indice, et rien qu'un indice

source_modes n'affecte jamais aucune valeur. C'est une information de diagnostic pour un humain qui lit le fichier. Un importeur ne changera pas sa façon d'écrire une courbe à cause de ça.

Caméras¶

Les deux formats transportent le même bloc de caméra, lié par nom à l'élément qui l'anime :

Clé	Signification
`name`, `peg`, `path`	Identité, et quel élément l'anime
`is_default`	Si c'est la caméra par défaut de la scène
`fov`, `fov_axis`	Field of view — vertical, conformément à la convention de Harmony
`override_fov`	Le flag d'override du FOV par caméra de Harmony
`near_plane`, `far_plane`	Clip planes, en distances canoniques
`near_field`, `far_field`	Les valeurs de clip d'origine de Harmony en fields, préservées pour qu'un aller-retour Harmony soit sans perte
`angle`	Roll, en degrés autour de Z
`offset_x/y/z`, `pivot_x/y`	Placement relatif au peg
`rig`	Le tag de rig

Voir Caméras.

Notes pratiques¶

Les fichiers sont petits. Un rig de personnage complet avec un plan de 60 frames fait quelques centaines de kilo-octets. Ils passent très bien par e-mail, dans un gestionnaire de versions, ou archivés à côté d'un plan comme trace.

Ils sont diffables. Deux exports du même rig produisent du JSON comparable, ce qui fait de « qu'est-ce qui a changé entre ces deux versions » un diff de texte plutôt qu'une devinette.

Le nommage vous appartient. OTS se moque du nom du fichier ; c'est la clé format à l'intérieur qui l'identifie. Garder les extensions .pvt / .anm sert juste à ce que les sélecteurs de fichiers se comportent correctement.