Skip to content

Commit 5fc5cde

Browse files
committed
Clarify the purpose and scope of names
1 parent d384b45 commit 5fc5cde

File tree

2 files changed

+3
-0
lines changed

2 files changed

+3
-0
lines changed

README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ Additionally, there are many fine-detail differences between G4MF and glTF™:
3636
- G4MF node transforms use a combination of `"position"` and either `"basis"` or `"rotor"`+`"scale"`, while glTF™ uses `"translation"`+`"rotation"`+`"scale"` or a 4x4 `"matrix"`. Both formats only allow a linear transform, meaning the glTF™ `"matrix"` property always has (0, 0, 0, 1) values in the last row. This last row is useful for sending the data to the GPU, but is not meaningful data for interchange, therefore it is not present in G4MF.
3737
- G4MF node `"scale"` does not allow for negative scales, while glTF™ does. G4MF requires that `"basis"` is used for flips/reflections, if needed.
3838
- G4MF node `"scale"` allows for a single value representing a uniform scale, useful for compactness especially with very high dimensions. glTF™ `"scale"` is always a 3D vector.
39+
- G4MF item names, such as node names, material names, etc, explicitly serve as file-unique human-readable semantic identifiers. In glTF™, names do not have to be unique.
3940
- G4MF mesh vertices are stored in a typically de-duplicated way, and referenced by index by the simplexes and/or edges of a surface. glTF™ stores each triangle with unique vertices, which is easier for directly loading to the GPU, but leads to confusion about vertices being duplicated. https://blender.stackexchange.com/questions/167372/gltf-export-has-twice-the-vertices-it-should/167383#167383
4041
- G4MF meshes have `"surfaces"`, which is a more user-friendly name. glTF™ meshes have `"primitives"`, which is the terminology used by OpenGL™. https://www.khronos.org/opengl/wiki/primitive
4142
- G4MF mesh surfaces explicitly define simplexes and edges on the surface, and vertices are defined on the base mesh. glTF™ mesh primitives define these inside of `"attributes"` and `"mode"`.

specification/parts/core.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,8 @@ The `"name"` property is a string that defines the file-unique name of the item.
4949

5050
If defined, this MUST be unique within the G4MF file, across all items, including all nodes, meshes, materials, textures, and other items. For example, if a G4MF node is named `"Crate"`, then the mesh data cannot also be named `"Crate"`, it must be named something else, such as `"CrateMesh"`, or be left unnamed by not defining the `"name"` property. If two or more items in the same G4MF file have the same name, the G4MF file is invalid. If the `"name"` property is not defined, it is considered equivalent to an empty string. Empty or non-existent names are the only cases where more than one item may have that name, since it is not always useful for every item to have a name.
5151

52+
Names in G4MF may be thought of as serving the same purpose as `"id"` values in other formats. They serve as unique identifiers for items within a file, allowing for external systems to unambiguously refer to specific items by name. However, this property is named `"name"` rather than `"id"` to avoid confusion with other schemes, such as numeric IDs, numeric indices, UUIDs, URIs, or other ways to specify identifiers. The `"name"` property is intended to be a human-readable and meaningful unique identifier, meant for display in user interfaces, referencing externally, and conveying semantic meaning about the item it names, such as G4MF nodes named after bones in a character skeleton rig (see [G4MF Characters/Avatars](mesh/character_avatar.md)). Note that within a G4MF file, items are referred to by index in a specification-defined array (see [IDs](#ids)), ensuring that internal references are compact, efficient, and always refer to the correct data type. For example, this design makes it impossible for a mesh's `"material"` property to refer to a node, mesh, texture, or any other non-material item. However, indices are likely to change across file edits; therefore, unique names provide a way for external references to refer to items in a more stable way.
53+
5254
All names in a G4MF file MUST NOT contain the following characters: `"`, `.`, `:`, `@`, `/`, and literal `\`. The `\` character may be used for escaping characters, but names MUST NOT contain literal backslashes, so `\\` MUST NOT appear in the serialized version of the name in a G4MF file. Furthermore, names MUST NOT contain any control characters, even escaped control characters, including both ASCII control characters and the extended Unicode control characters, as is already required for the entire G4MF JSON structure, except that names additionally MUST NOT contain newline or tab characters. Names are RECOMMENDED to not contain spaces and not contain other punctuation characters that can be interpreted as special characters in certain contexts, however, all other characters not explicitly forbidden are allowed.
5355

5456
The name uniqueness requirement exists for all items within a file, but does not apply for names between files. Two G4MF files may have up to two nodes with the same name between them, such as a each having a node named `"Crate"`. If a G4MF file uses another G4MF file as a model (see [G4MF Model](model.md)), this means that there may be multiple nodes or other items with the same name in the overall scene graph. Therefore, names are not guaranteed to be globally unique across the entire scene graph, but they are guaranteed to be unique within a single G4MF file.

0 commit comments

Comments
 (0)