We are aware of this issue but recommend waiting until no other PRs are open: Then we could simply create a branch for the file name changes and merge it without any conflicts. Does that work for you or do you feel this is urgent?

Also, as this relates to #68 I'd propose closing that issue and keeping the discussion/progress in this issue, ok?

Also, as this relates to #68 I'd propose closing that issue and keeping the discussion/progress in this issue, ok?

This is not in any case related to #68. This issue here is about the naming convention for OpenMATERIAL assets that should go into the documentation.
What you are referring to is the naming of asciidoc files.

Is your feature request related to a problem? Please describe.
[WIP] In the documentation of the Geometry Subgroup on Naming conventions, some information is missing:

• Node Structures
  ** Naming of nodes shall be accoding to SnakeCase definition, starting with capital letters
  ** Group Nodes (also known as empty nodes or parent nodes) shall have "Grp_"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
  ** Enums (e.g. from OpenDRIVE road/lane type) should be added as suffixes in capital letters
  ** Sequence of suffixes: 1: Iterator 2: Type Enumerator 3: Subtype Enumerator
• Metadata
  ** Naming of fields shall be accoding to SnakeCase definition, starting with capital letters
  ** (Complex) objects, Arrays (lists) and Enums should follow json notation

Describe the solution you'd like
Add information to the naming section in the document

Describe alternatives you've considered

Additional context

We have added "starting with capital letters" to the metadata naming convention. For consistency, then all fields in the json fields should be capital letters. Also the material properties in the corresponding files.
Are we sure we want to do it that way?

Officially there are some hard restrictions, that do not touch this: https://jsonapi.org/format/#document-member-names
But the recommendations are to use camelCase with a lower first letter (so a completely different convention): https://jsonapi.org/recommendations/#naming

Since this is relevant to all further development in both sub-groups, we should make a decision fast.

What is your opinion @LudwigFriedmann ?

Hi @ClemensLinnhoff, If there's a binding restriction from JSON here I'd rather change our naming scheme for file and node names, We should discuss this in the group.

@ClemensLinnhoff @LudwigFriedmann I will wait with this topic until the next group meeting then.

But I can say upfront, that I am personally not a big fan of camelCase (with a lower first letter) for the node structure, because it is harder to read for the human eye in the 3D application. It could be benefitial to use different naming conventions here.

I agree with @ipg-sig. I also don't like camelCase at all. But I am also a bit reluctant to go against a common convention.

We did a quick poll in the material group meeting:

snake_case: 2
camelCase: 5

Comment from @ipg-sig in the material meeting:
OpenUSD: A legible prim hierarchy should promote consistency for readability. Common naming conventions include snake_case, UpperCamelCase (or PascalCase), and lowerCamelCase.

We did a quick poll in the gometry group meeting:

snake_case: 1
camelCase: 3

-> Decision: use camelCase for JSON parameters

WIP Naming conventions

The following naming conventions apply to ASAM OpenMATERIAL geometry files:

File Names

• 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 must have the same base name.
  Example: omg_Example.gltf, omg_Example.xoma
• The naming convention inside the 3D model file (contains 3D informations) must follow the snake_case definition, to better human readability and consistent parsing of the file structure
• The naming convention inside the 3D asset file (contains meta data) must follow the lowerCamelCase definition, to allow a consistent naming convention in all .json files and an consistent parsing.
• LOD levels (Level of Detail) are not part of the first version of the standard, but will be added in future versions for each asset type.

Node Structure for the 3D Model

• All components should be named according to the snake_case definition, starting with upper 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
• Enums (e.g. from OpenDRIVE road/lane type) should be added as suffixes in capital letters
• Sequence of suffixes: 1: Iterator 2: Type Enumerator 3: Subtype Enumerator
• Count the axle index by following the OSI definition (NOTE: include link to: https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/gen/structosi3_1_1MovingObject_1_1VehicleAttributes_1_1WheelData.html#a094de989f5a2aab080f9a65f0feb3867) counting from front to rear starting with 0
• Count the wheel index by following the OSI definition(NOTE: include link to: https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/gen/structosi3_1_1MovingObject_1_1VehicleAttributes_1_1WheelData.html#a094de989f5a2aab080f9a65f0feb3867) counting per axle from right to left (in positive y-direction)
• 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.
• The predefined subkeys and keywords must be used for the corresponding asset parts
• LOD levels (Level of Detail) are not part of the first version of the standard, but will be added in future versions for each asset type
• Meshes, which should be included but not visible, need to be hidden before export and need metadata to define the state and visibility (needs to be duscussed in the group)

**Subkeys **
To allow a consistent naming convention and parsing, some subkeys and keywords are already predefined by the standard. more could follow in future updates. The User is free to add more subkeys for himself, if they are needed.

Vehicles:

General naming structure: <Component_Idx>_Specification_Idx_Idx

• "Grp_" - Subkey and prefix for Group Nodes
• "Static" - Subkey, which contains only static components
• "Dynamic" - Subkey, which contains dynamic components
• "Vehicle_Part" - Subkey, describes an vehicle (part), that moves independently from other parts of the same vehicle
• "Exterior" - Subkey, contains the exterior of an vehicle
• "Interior" - Subkey, contains the interior of an vehicle
• "Wheel" - Subkey, contains wheels of an vehicle
• "Wheel_Steering"- Subkey, contains the wheel steering
• "Door" - Subkey, contains doors of an vehicle (inlucding trunks, engine hoods, etc.). After this subkey always follows a subkey which indicates the specific view side.
• "Front" - Subkey, specifies the front view side
• "Left" - Subkey, specifies the left view side
• "Right" - Subkey, specifies the right view side
• "Top" - Subkey, specifies the top view side
• "Rear" - Subkey, specifies the rear view side
• "Light" - Subkey, contains vehicle lights. After this subkey always follows a subkeys which indicates the specific vehicle light.
• • "Day" - Subkey, specifies day lights of the vehicle, always used after the subkey "Light". After this subkey always follows a subkey which indicates the specific view side.
• • "Low_Beam" - Subkey, specifies low beam lights of the vehicle, always used after the subkey "Light". After this subkey always follows a subkey which indicates the specific view side.
• • "High_Beam" - Subkey, specifies high beam lights of the vehicle, always used after the subkey "Light". After this subkey always follows a subkey which indicates the specific view side.
• • "Corner" - Subkey, specifies corner lights of the vehicle, always used after the subkey "Light". After this subkey always follows a subkey which indicates the specific view side.
• • "Position" - Subkey, specifies position lights of the vehicle, always used after the subkey "Light". After this subkey always follows a subkey which indicates the specific view side.
• • "Park" - Subkey, specifies park lights of the vehicle, always used after the subkey "Light". After this subkey always follows a subkey which indicates the specific view side.
• • "Indicator" - Subkey, specifies indicator lights of the vehicle, always used after the subkey "Light". After this subkey always follows a subkey which indicates the specific view side.
• • "License_Plate" - Subkey, specifies the license plate(s) light(s) of the vehicle, always used after the subkey "Light". After this subkey always follows a subkey which indicates the specific view side.
• • "Tail"- Subkey, specifies tail lights of the vehicle, always used after the subkey "Light". After this subkey always follows a subkey which indicates the specific view side.
• • "Brake" - Subkey, specifies brake lights of the vehicle, always used after the subkey "Light". After this subkey always follows a subkey which indicates the specific view side.
• • "Reverse" - Subkey, specifies reverse lights of the vehicle, always used after the subkey "Light". After this subkey always follows a subkey which indicates the specific view side.
• • "Fog" - Subkey, specifies fog lights of the vehicle, always used after the subkey "Light". After this subkey always follows a subkey which indicates the specific view side.
• • "Warning" - Subkey, specifies warning lights of the vehicle, always used after the subkey "Light". After this subkey always follows a subkey which indicates the specific view side.
• "Number_Plate" - Subkey, contains license plates of an vehicle.
• "Convertible_Top" - Subkey, contains the convertible top of an vehicle.
• "Sensors" - Subkey, contains the convertible top of an vehicle.
• "Mirror" - Subkey, contains the side mirror(s) of an vehicle.
• • "Side" - Subkey, specifies the side mirror(s) of an vehicle.
• • "Blindspot" - Subkey, specifies the blindspot mirror(s) of an vehicle.
• • "Rearview" - Subkey, specifies the rearview mirror(s) of an vehicle.
• • "Mounting" - Subkey, specifies the mirror mounting on the vehicle, always used after the subkey, which specifies the mirror.
• • "View" - Subkey, specifies the side mirror (glass) on the vehicle, always used after the subkey, which specifies the mirror.
• "Steering_Wheel" - Subkey, specifies the steering wheel of an vehicle.
• "Eyepoint" - Subkey, specifies the eyepoint levels of the driver or passenger(s).
• "Seat" - Subkey, specifies the seat position of the driver or passenger(s).

Additional recommended Subkeys

• "Lever" - Subkey, specifies a lever, for example shift levers or levers on the steering wheel
• "Pedal" - Subkey, specifies a pedal of the vehicle, which has one the following specifications: Brake, Shift, Gas
• "Hitch" - Subkey, specifies a hitch, for example for trailers

An example vehicle structure can be found in chapter (add link to chapter from #103 ).

Human:

Predefined Subkeys

• "Grp_" - Subkey and prefix for Group Nodes
• "Static" - Subkey, which contains only static components
• "Dynamic" - Subkey, which contains dynamic components
• "Equipment" Subkey, which contains equipment of the pedestrian. After this subkey always follows a subkey which indicates if it is static or dynamic.

General naming structure: BoneName_SideIndicator

Predefined Bone Names

• "Root" - Root Bone, can be used to transform the whole asset
• "Hip" - Hip bone
• "Upper_Leg" - Tigh bone
• "Lower_Leg" - Lower leg bone
• "Foot" - Foot bone
• "Toes" - Toe bone, used for all toes.
• "Lower_Spine"- Bone for the lower part of the upper body (abdomen)
• "Upper_Spine" - Bone for the upper part of the upper body (thorax)
• "Neck" - Bone for the neck
• "Head" - Bone for the head
• "Eye" - Bone for the eye
• "Shoulder" - Shoulder bone
• "Upper_Arm" - Upper arm bone
• "Lower_Arm" - Lower arm bone
• "Upper Thumb" - Bone for the upper thumb
• "Lower_Thumb" - Bone for the lower thumb
• "Hand" - Bone for the middle hand
• "Upper_Fingers" - Bone for the upper part of the other fingers
• "Lower_Fingers" - Bone for the lower part of the other fingers
• "Helper" - Prefix for Helper Bones, they are used to help the user to place assets or parts of the riggs more easily
• "Left" - for left side
• "Rright" - for right side

Recommended Names for additional bone names

• "Upper_Index_Finger" - Bone for the upper part of the index finger
• "Lower_Index_Finger" - Bone for the lower part of the index finger
• "Upper Middle_Finger" - Bone for the upper part of the middle finger
• "Lower_Middle_Finger" - Bone for the lower part of the middle finger
• "Upper_Ring_Finger" - Bone for the upper part of the ring finger
• "Lower_Ring_Finger" - Bone for the lower part of the ring finger
• "Upper_Little_Finger" - Bone for the upper part of the little finger
• "Lower_Little_Finger" - Bone for the lower part of the little finger
• "Upper_Big_Toe" - Bone for the upper part of the big toe
• "Lower_Big_Toe" - Bone for the lower part of the big toe
• "Upper_DigitusII_Toe" - Bone for the upper part of the Digitus II toe
• "Lower_DigitusII_Tow - Bone for the lower part of the Digitus II toe
• "Upper_DigitusIII_Toe - Bone for the upper part of the Digitis III toe
• "Lower_DigitusIII_Toe" - Bone for the lower part of the Digitis III toe
• "Upper_DigitusIV_Toe" - Bone for the upper part of the Digitus IV toe
• "Lower_DigitusIV_Toe" - Bone for the lower part of the Digitus IV toe
• "Upper_Small_Toe" - Bone for the upper part of the small toe
• "Lower_Small_Toe" - Bone for the lower part of the small toe

An example human structure can be found in chapter (add link to chapter from #103 ).

Environment:

General naming structure: ObjectName_Idx

• "Root " - Root node, can be used to transform the whole asset
• "Terrain" - Specifies the ground/landscape of the environment
• "Objects" - Group Node, includes all object related nodes
• "Buildings" - Group Node, contains all buildings of the environment
• "Vegetation" - Group Node, contains all vegetation of the environment
• "Road_Network" - Group Node, contains all road network related objects
• "Driving_Area" - Group Node, which contains the drivable areas (comparable to scope of OpenDRIVE for on-road use-cases, including lanes, signs and related objects)
• "Sidewalks" - Group Node, contains all sidewalks
• "Road_Marks" - Group Node, contains all road markings
• "Road_Object" - Group Node, contains all road related objects
• "Signal" - Group Node, contains all traffic lights and signs
• "Sign" - Group Node, contains all traffic signs
• "Traffic_Light" - Group Node, contains all traffic lights (count from left to right, top to down)
• "Light" - Group Node, contains all light sources (emits light and casts shadows)
• "Cover" - Group Node, contains the outer cover of the traffic light

Metadata

• Naming of fields must be according to lowerCamelCase definition, starting with lower letters.
• Naming of Custom Properties must follow the predefined keys.
• (Complex) objects, Arrays (lists) and Enums must follow the .json notation.
• Needs to be discussed in the group:
• (Standard) Visibility State of Meshes will be true (1). If Meshes should be hidden, it needs to be set to No (0). This is for example usefull, if you want to switch betweens two versions of an convertible top (open and closed).
• (State) of Appearance: Open or Closed. Can be used to define the standard appearance.

Needs to be discussed in the group:

• Meshes, which should be included but not visible, need to be hidden before export and need metadata to define the state and visibility
• Add States to Meta data for hidden objects and state?
• (Standard) Visibility State of Meshes will be true (1). If Meshes should be hidden, it needs to be set to No (0). This is for example usefull, if you want to switch betweens two versions of an convertible top (open and closed).
  -(State) of Appearance: Open or Closed. Can be used to define the standard appearance.
• Use "Left" (for left side) and "Right" (for right side) instead of "L" and "R" in humane bone structure to stay consistent betweens vehicles and humans

In my opinion we could still use snake_case for the node in the 3D geometry. As I see it, we just agreed on the lowerCamelCase for the fields in the json files, as this is the recommended style for json.

That would be great. I understood it so, that you wanted to have the lowerCamelCase consistently in every file. Would be great, if we only use it in the json files, metadata. Thats why I stopped yesterday and wanted to clarify it in the group.

Blender

WIP Naming conventions

The following naming conventions apply to ASAM OpenMATERIAL geometry files:

File Names

• 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.
• All files should be named according to the lowerCamelCase definition, starting with lower letters.

Example: omg_myFileIsHere.gltf, omg_myFileIsHere.xoma

Node Structures

• All components should be named according to the lowerCamelCase definition, starting with lower 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
• Enums (e.g. from OpenDRIVE road/lane type) should be added as suffixes in capital letters
• Sequence of suffixes: 1: Iterator 2: Type Enumerator 3: Subtype Enumerator
• Count the axle index by following the OSI definition (include link to: https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/gen/structosi3_1_1MovingObject_1_1VehicleAttributes_1_1WheelData.html#a094de989f5a2aab080f9a65f0feb3867) counting%C2%A0counting) from front to rear starting with 0
• Count the wheel index by following the OSI definition(include link to: https://opensimulationinterface.github.io/osi-antora-generator/asamosi/latest/gen/structosi3_1_1MovingObject_1_1VehicleAttributes_1_1WheelData.html#a094de989f5a2aab080f9a65f0feb3867) counting%C2%A0counting) per axle from right to left (in positive y-direction)
• Count the door index per side from front to rear and right to left (in positive y-direction)
• ** To be discussed in the group: Count the seat index per level from first level right to left and front to rear, 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.**

Example Vehicles: |-------grp<Vehicle_Part_idx> | |-------grpExterior | |  |-------grpExteriorStatic | |  |-------grpExteriorDynamic | |  |-------grpWheel_<axle_idx><wheel_idx> | |  |  |-------grpWheel<axle_idx><wheel_idx>Steering | |  |  |-------grpWheel<axle_idx><wheel_idx>SteeringRotating | |  |-------grpDoorFront<DoorFront_idx> | |  |-------grpDoorLeft_<DoorLeft_idx> | |  |-------grpDoorRight_<DoorRight_idx> | |  |-------grpDoorRear_<DoorRear_idx> | |  |-------grpDoorTop_<DoorTop_idx> | |  |-------grpDoorBottom_<DoorBottom_idx> | | |-------grpLightDayLeft_<DayLeft_idx> | | |-------grpLightDayRight_<DayRight_idx> | |  |-------grpLightLowBeamLeft_<LowBeamLeft_idx> | | |-------grpLightLowBeamRight_<LowBeamRight_idx> | |  |-------grpLightHighBeamLeft_<HighBeamLeft_idx> | | |-------grpLightHighBeamRight_<HighBeamRight_idx> | |  |-------grpLightPositionLeft_<PositionLeft_idx> | | |-------grpLightPositionRight_<PositionRight_idx> | | |-------grpLightParkLeft_<PositionLeft_idx> | | |-------grpLightParkRight_<PositionRight_idx> | |  |-------grpLightTailLeft_<TailLeft_idx> | | |-------grpLightTailRight_<TailRight_idx> | |  |-------grpLightBrakeLeft_<BrakeLeft_idx> | | |-------grpLightBrakeCenter_<BrakeCenter_idx> | | |-------grpLightBrakeRight_<BrakeRight_idx> | |  |-------grpLightReverseLeft_<ReverseLeft_idx> | | |-------grpLightReverseRight_<ReverseRight_idx> | |  |-------grpLightFogLeft_<FogLeft_idx> | | |-------grpLightFogRight_<FogRight_idx> | | |-------grpLightCornerLeft_<CornerLeft_idx> | | |-------grpLightCornerRight_<CornerRight_idx> | |  |-------grpLightIndicatorLeft_<IndicatorLeft_idx> | |  |-------grpLight_Indicator_Right_<IndicatorRight_idx> | |  |-------grpNumberPlate_<NumberPlate_idx> | |  |-------grpLightNumberPlate_<NumberPlateLight_idx> | | |-------grpLightWarning_<Warning_idx> | |  |-------grpConvertibleTop | |  |-------grpSensors | |  |-------grpSideMirrorMountingLeft_<SideMirrorMountingLeft_idx> | |  |-------grpSideMirrorViewLeft_<SideMirrorViewLeft_idx> | |  |-------grpSideMirrorMountingRight_<SideMirrorMountingRight_idx> | |  |-------grpSideMirrorView_Right_<SideMirrorViewRight_idx> | | |-------grpBlindspotMirrorMounting_<BlindspotMirrorMounting_idx> | | |-------grpBlindspotMirrorView_<BlindspotMirrorView_idx> | |-------grpInterior | |  |-------grpInteriorStatic | |  |-------grpInteriorDynamic | |  | |-------grpSteeringWheel | |  | |-------grpEyepoint_<Eyepoint_idx> | |  | |-------grpRearviewMirrorMounting_<RearviewMirrorMounting_idx> | |  | |-------grpRearviewMirrorView_<RearviewMirrorView_idx> | | | |-------grpSeat_<Seat_idx>

Example Pedestrians:

|-------grpSkeletonGenderClothingActivityEquipmentRelease |-------grpFloor |-------grpEquipmentStatic |-------skeleton |-------hip |-------lowerSpine | | |-------upperSpine | | | |-------neck | | | | |-------head | | |-------shoulderR | | | |-------upperArmR | | | | |-------lowerArmR | | | | | |-------fullHandR | | |-------shoulderL | | | |-------upperArmL | | | | |-------lowerArmL | | | | | |-------fullHandL | |-------upperLegR | | |-------lowerLegR | | | |-------fullFootR | |-------upperLegL | | |-------lowerLegL | | | |-------fullFootL |-------body |-------hair |-------clothing |-------grpEquipmentDynamic |-------hip   |   |-------lowerSpine   |   |   |-------upperSpine   |   |   |   |-------neck   |   |   |   |  |-------head   |   |   |-------shoulderR   |   |   |   |-------upperArmR   |   |   |   |  |-------lowerArmR   |   |   |   |  |  |-------fullHandR    |   |   |-------shoulderL    |   |   |   |-------upperArmL    |   |   |   |   |-------lowerArmL    |   |   |   |   |  |-------fullHandL    |   |-------upperLegR    |   |   |-------lowerLegR    |   |   |  |-------fullFootR    |   |-------upperLegL    |  |   |-------lowerLegL    |  |   |   |-------fullFootL    |-------body    |-------hair    |-------clothing    |-------grpEquipmentDynamic

**Problem to be discussed in the group: We lose the ability to mirror our bones. This feature mostly depends on _L/_R or .L/.R **

Metadata

• Naming of fields shall be accoding to lowerCamelCase definition, starting with lower letters.
• Naming of Custom Properties should follow the predefined keys.
• (Complex) objects, Arrays (lists) and Enums should follow json notation.

Blender requires this naming for mirroring at first place, but after mirroring, nodes can be renamed again. This creates overhead but doesn't prevent mirroring.

Group Decision: Keep snake case (as it is) due to better readability for 3D model structure.

Open questions:

1. Meshes, which should be included but not visible, need to be hidden before export and would need metadata to define the state and visibility. I haven´t seen any notes on the miro board about it, but I am sure we discussed it in one of the meetings before. Can someone remember, what we decided for that case?

Othwerwise i would make the following proposal: Add States to Meta data for hidden objects and states.

• (Standard) Visibility State of Meshes will be true (1). If Meshes should be hidden, it needs to be set to No (0). This is for example usefull, if you want to switch between two versions of an convertible top (open and closed).
• (State) of Appearance: Open or Closed. Can be used to define the standard appearance.

2. Use "Left" (for left side) and "Right" (for right side) instead of "L" and "R" in humane bone structure to stay consistent between vehicles and humans. Is that okay for the group?

3. Add a naming conventions chapter to each object class. It is easier to have the general naming conventions under General, and for each Object Class the predefined Subkeys and recommended Subkeys (/ keywords or as we named them in the meeting today vehicle parts) and Naming Convention in each Object Class chapter directly, so all important informations are in one place.

4. One PR to have a basis with the current progress or wait, as there will be changes until the other chapters are completed? Otherwise the naming convention needs adjustements every week, since new issues are detected in the current state.
   Should we just open another issue, if something changes and needs adjustement of the naming convention part?
   Or is explaining every used subkey and recommended subkey too much in your eyes? (I think it is easier to adapt and extend and give recommendations for the naming , if it is listed here independently from the structure - but maybe thats just my point of view).

Please feel free to comment: @LudwigFriedmann @ClemensLinnhoff @MatthiasThDs @KimuraDIVP @lyndyRott @MustafaTrian @DavidJRitter904

1. Is it possible to have hidden meshes in all three file formats? If yes, having bool values in the asset file is a good idea in my opinion.
2. Then we would differ from the definitions in OSI but the naming is different anyways, because they are enums in OSI. So for me it would be okay to change to Left and Right to be consistent with the vehicle definitions.
3. I agree that makes sense.
4. I would create a PR now with the current state. I think it is always easier to spot errors or missing definitions, when you already have something in the documentation. Then we can always fix or add stuff later.