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 Restrictions.

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”

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": {...}
      }
    }
  }
}