Merge pull request #185 from asam-ev/85-documentation-naming-conventi…

…ons-723

Complete chapter naming convention

content/geometry/general.adoc

@@ -85,41 +85,52 @@ The origin of the world coordinate system in ASAM OSI should also be aligned wit
 
 === Local coordinate system
 
-Top-most local coordinate frames of 3D assets (so called reference coordinate frames) in OpenMATERIAL are defined in the center of the bounding box of the corresponding asset, projected to the bottom of the bounding box.
+Top-most local coordinate frames of 3D assets (so-called reference coordinate frames) in OpenMATERIAL are defined in the center of the bounding box of the corresponding asset, projected to the bottom of the bounding box.
 By static transformations, these coordinate frames may be synchronized with reference coordinate frames in ASAM OpenSCENARIO and ASAM OSI.
 Besides reference coordinate frames, 3D assets may incorporate other local coordinate frames, see xref:../geometry/object-classes.adoc[Object classes].
 
 == Naming conventions
 
+=== General
+
 The following naming conventions apply to ASAM OpenMATERIAL geometry files:
 
-* The name of a 3D model file shall have the prefix `omg_` to indicate that the file
-complies with the ASAM OpenMATERIAL geometry specification.
 * The 3D model file and the related 3D asset file shall have the same base name.
+  Example: Example.gltf, Example.xoma
+* The naming convention inside the 3D model file (contains 3D information) must follow the capital Snake_Case definition, to improve human readability and enable consistent parsing of the file structure.
+* The naming convention inside the 3D asset file (contains metadata) must follow the lowerCamelCase definition, to allow a consistent naming convention in all .json files and consistent parsing.
+* Keywords are predefined names for objects inside the node structure.
+
+=== Node structure
+
+Every node structure for a 3D object uses predefined keywords to allow a consistent naming convention and parsing.
+Some keywords are already defined by the standard and more could follow in future updates.
+The user is free to add more keywords for himself, if they are needed.
+
+* All components shall be named according to the capital Snake_Case definition, starting with uppercase letters.
+* Group nodes (also known as empty nodes or parent nodes) shall have "Grp_" as a prefix.
+* Iterators are added as suffixes.
+  In the documentation, iterator names are written in pointy braces (e.g. <type_idx>).
+  In the node names itself, the iterator names are replaced by integer values starting from 0.
+* Sequence of suffixes: 1: Iterator 2: Type Enumerator 3: Subtype Enumerator.
+* The predefined keywords shall be used for the corresponding asset parts and can be found in the according subchapters.
 
-NOTE: Putting more information in file name to be discussed for specific object classes.
+=== Metadata
+
+* Naming of fields shall be according to lowerCamelCase definition, starting with lower letters.
+* Naming of custom properties shall follow the predefined keys.
+* Objects, arrays (lists) and enums shall follow the .json notation.
 
 == 3D asset file
 
-The 3D asset file provides meta data as well as a mapping table to ASAM OpenMATERIAL material property files.
+The 3D asset file provides metadata as well as a mapping table to ASAM OpenMATERIAL material property files.
 This information extends the geometry of an asset given in standard 3D model file formats, e.g. glTF, FBX or USD.
 The 3D asset file is in JSON format with the file extension `xoma`.
-As indicated above, the asset file has to have the same file name as the accompanying 3D model with the prefix `omg` indicating,
-that the 3D model file is structured according to the ASAM OpenMATERIAL geometry specification.
+As indicated above, the asset file has to have the same file name as the accompanying 3D model.
 This is an example of a 3D model file in glTF format with an accompanying 3D asset file:
 
-* `omg_my-model.glTF`
-* `omg_my-model.xoma`
-
-Each 3D asset file contains the following information:
-
-* Metadata
-* Material mapping (with possibility to easily change assignment)
-* Optional link to another asset file to facilitate instancing (same asset file for different 3D models)
-* Semantic information (labels) for sub-meshes ?
-* Description of coordinates, pivot points and so on instead of hierarchy in 3D model file ?
-* Assigning data streams (for example, wheel rotation) to certain sub-meshes ?
-
+* `my-model.gltf`
+* `my-model.xoma`
 
 == Requirements
 

content/geometry/object-human/human-naming-convention.adoc

@@ -0,0 +1,6 @@
+=== Naming convention
+
+Every bone has a unique name and represents a part of the human body. The left and right side of the armature are indicated with the keywords "Left" and "Right" as a postfix.
+All included meshes use a keyword as a prefix to indicate which kind of asset it represents. They shall be named meaningful.
+
+If needed, the user is free to add more prefixes or bones, which are not part of the standard, for himself.

content/geometry/object-road-network/environment-naming-convention.adoc

@@ -0,0 +1,8 @@
+=== Naming convention
+
+Every asset has a unique name and represents a part of the environment. All included meshes are part of a group to indicate which kind of asset type it represents.
+All meshes should be named meaningful.
+
+If needed, the user is free to add more groups and new keywords, which are not part of the standard, for himself.
+
+|===

content/geometry/object-vehicle/vehicle-naming-convention.adoc

@@ -0,0 +1,11 @@
+=== Naming convention
+
+Every mesh has a unique name and represents a part of the vehicle. The different vehicle components can be identified by the keywords.
+All included meshes use one or more keywords to indicate which kind of asset it represents and where it is located.
+Count the axle index from front to rear starting with 0 (according to the https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/gen/structosi3_1_1MovingObject_1_1VehicleAttributes_1_1WheelData.html#a094de989f5a2aab080f9a65f0feb3867[OSI definition]).
+Count the wheel index per axle from right to left (in positive y-direction and according to the https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/gen/structosi3_1_1MovingObject_1_1VehicleAttributes_1_1WheelData.html#a094de989f5a2aab080f9a65f0feb3867[OSI definition]).
+Count the door index per side from front to rear and right to left (in positive y-direction).
+Count the seat index per level from first level front to rear, and right to left, to the next level from right to left and front to rear. Note: A rear bench with 3 seats will be consideres as 3 seats, because 3 passengers could take a seat on it.
+
+If needed, the user is free to add more groups and new keywords, which are not part of the standard, for himself.
+