日本語

PITM data format

PITM is a combination of glTF-2.0 and Cluster-developed extensions and extras. PITM is serialized in the GLB container format. The extensions specification is described in Protocol Buffers.

The Python sample code includes a utility class for exporting craft items and accessories using some of the PITM specifications. See the following file.

https://github.com/ClusterVR/PITMSample/blob/main/python/pitm.py

glTF Structure

The PITM must be a valid glTF.

A PITM has a single scene. Also, references to external resources such as buffer uris cannot be used. (All textures, meshes, and other data must be contained entirely within the GLB file.)

glTF requires ClusterItem extension at the top level and ClusterItemNode extension for every node.

The basic structure of PITM is the same for craft items and accessories, but the functions available for each are different.

Craft Items

Follow Craft item restrictions. Standard glTF materials such as pbrMetallicRoughness are available.

Accessories

Follow Accessory limitations.

Only Item.meta and Item.accessory_item are available for Items, and these two fields are required. Fields within ItemNode are not available for accessories, but an empty ItemNode is still required.

Only MToon can be used for materials. MToon parameters are described in ClusterVRM0MToon extra of glTF material.

ClusterItem extension and ClusterItemNode extension

The top level requires the ClusterItem extension.

"extensions": [
    "ClusterItem": {
      {"item": "URL-safe base64 encoded message Item"}
    }
]

All nodes require the ClusterItemNode extension.

"extensions": [
    "ClusterItemNode": {
      {"itemNode": "URL-safe base64 encoded message ItemNode"}
    }
]

The specifications for Item and ItemNode are written in proto3. Please see the following file.

https://github.com/ClusterVR/PITMSample/blob/main/pitm.proto

URL-safe base64 encoding uses a variant of RFC 4648: Base 64 Encoding with URL and Filename Safe Alphabet.

  • No trailing =
  • Use -_ instead of +/

Example: URL-safe base64 encoded ItemNode “OiQKIgogCg4KDAAAAAAAAAAAmpmZPRIOCgwAAAA_AAAAP5qZGT4”

ClusterHumanoidAnimation extension and ClusterHumanoidAnimationTarget extension

In PITM, HumanoidAnimation is stored as glTF animation.

Whether the animation is a loop animation or not is stored in the extensions of animation as ClusterHumanoidAnimation. If ClusterHumanoidAnimation does not exist in an animation, it is treated as not a loop animation.

{
  "extensions": {
    "ClusterHumanoidAnimation": {
      "isLoop": true
    }
  }
}

The animation targets are required to be stored in the extensions of animation.channel.target as ClusterHumanoidAnimationTarget. Any other fields of animation.channel.target are ignored. The key frame data of the animation is stored as glTF sampler.

{
  "target": {
    "extensions": {
      "ClusterHumanoidAnimationTarget": {
        "humanoidAnimationTargetType": "LeftShoulderFrontBack"
      }
    },
    "path": "muscle"
  }
}

humanoidAnimationTargetType may take any of the following values.

  • "CenterPosition" corresponds to the translation relative to the world coordinate system of glTF, and receives VEC3 sampler output as XYZ.
  • "CenterRotation" corresponds to the rotation relative to the world coordinate system of glTF, and receives VEC4 sampler output as XYZW quaternion.
  • Other values corresponds to muscle values of humanoid bones, and receives SCALAR sampler output.
"CenterPosition"
"CenterRotation"
"SpineFrontBack"
"SpineLeftRight"
"SpineTwistLeftRight"
"ChestFrontBack"
"ChestLeftRight"
"ChestTwistLeftRight"
"UpperChestFrontBack"
"UpperChestLeftRight"
"UpperChestTwistLeftRight"
"NeckNodDownUp"
"NeckTiltLeftRight"
"NeckTurnLeftRight"
"HeadNodDownUp"
"HeadTiltLeftRight"
"HeadTurnLeftRight"
"LeftEyeDownUp"
"LeftEyeInOut"
"RightEyeDownUp"
"RightEyeInOut"
"JawClose"
"JawLeftRight"
"LeftUpperLegFrontBack"
"LeftUpperLegInOut"
"LeftUpperLegTwistInOut"
"LeftLowerLegStretch"
"LeftLowerLegTwistInOut"
"LeftFootUpDown"
"LeftFootTwistInOut"
"LeftToesUpDown"
"RightUpperLegFrontBack"
"RightUpperLegInOut"
"RightUpperLegTwistInOut"
"RightLowerLegStretch"
"RightLowerLegTwistInOut"
"RightFootUpDown"
"RightFootTwistInOut"
"RightToesUpDown"
"LeftShoulderDownUp"
"LeftShoulderFrontBack"
"LeftArmDownUp"
"LeftArmFrontBack"
"LeftArmTwistInOut"
"LeftForearmStretch"
"LeftForearmTwistInOut"
"LeftHandDownUp"
"LeftHandInOut"
"RightShoulderDownUp"
"RightShoulderFrontBack"
"RightArmDownUp"
"RightArmFrontBack"
"RightArmTwistInOut"
"RightForearmStretch"
"RightForearmTwistInOut"
"RightHandDownUp"
"RightHandInOut"
"LeftThumb1Stretched"
"LeftThumbSpread"
"LeftThumb2Stretched"
"LeftThumb3Stretched"
"LeftIndex1Stretched"
"LeftIndexSpread"
"LeftIndex2Stretched"
"LeftIndex3Stretched"
"LeftMiddle1Stretched"
"LeftMiddleSpread"
"LeftMiddle2Stretched"
"LeftMiddle3Stretched"
"LeftRing1Stretched"
"LeftRingSpread"
"LeftRing2Stretched"
"LeftRing3Stretched"
"LeftLittle1Stretched"
"LeftLittleSpread"
"LeftLittle2Stretched"
"LeftLittle3Stretched"
"RightThumb1Stretched"
"RightThumbSpread"
"RightThumb2Stretched"
"RightThumb3Stretched"
"RightIndex1Stretched"
"RightIndexSpread"
"RightIndex2Stretched"
"RightIndex3Stretched"
"RightMiddle1Stretched"
"RightMiddleSpread"
"RightMiddle2Stretched"
"RightMiddle3Stretched"
"RightRing1Stretched"
"RightRingSpread"
"RightRing2Stretched"
"RightRing3Stretched"
"RightLittle1Stretched"
"RightLittleSpread"
"RightLittle2Stretched"
"RightLittle3Stretched"

ClusterVRM0MToon extra

In PITM, MToon is stored in the extras of glTF material as ClusterVRM0MToon.

If MToonMat’s normalMapAsGltfFormat is true, the texture specified with “_BumpMap” as the key in MToonMat’s textureProperties is treated as glTF’s normalTexture. For details, see Schema. This value is recommended to be true. Any other texture will be treated as a gamma space texture. Other data in MToonMat follows the same format as each element of materialProperties in VRM-0.x.

{
  ..., // other fields in the material
  "extras": {
    "ClusterVRM0MToon": {
      "MToonMat": {
        "normalMapAsGltfFormat": boolean,
        "shader": "VRM/MToon",
        "renderQueue": {...},
        "keywordMap": {...},
        "tagMap": {...},
        "floatProperties": {...},
        "textureProperties": {...},
        "vectorProperties": {...}
      }
    }
  }
}