Merge pull request #36 from asam-ev/geometry-general-structure

General structure in Geometry group

.antora/antora.yml

@@ -35,7 +35,7 @@ asciidoc: # Sets global AsciiDoc attributes that are applied for every page of t
     asamBibliography: 'specification:general_docs/bibliography.bib'
 
 nav:
-  - modules/specification/nav_introduction.adoc
+  - modules/specification/nav_openmaterial.adoc
 
 # Add more items here as required.
 # Recommended: One navigation file per document/repository!

.antora/modules/specification/nav_openmaterial.adoc

@@ -0,0 +1,13 @@
+* xref:general_docs/foreword.adoc[]
+* xref:general_docs/introduction.adoc[]
+* xref:general_docs/scope.adoc[]
+* xref:general_docs/normative_references.adoc[]
+* xref:general_docs/abbreviations.adoc[]
+* xref:general_docs/backward_compatibility.adoc[]
+* xref:terms_and_definitions/terms_and_definitions.adoc[]
+* xref:use_cases/use_cases.adoc[]
+* Geometry
+** xref:geometry/general-structure-index.adoc[]
+* Material
+** xref:material/general-structure-index.adoc[]
+

content/geometry/File_format_support.adoc

@@ -0,0 +1,10 @@
+= File format
+The ASAM OpenMATERIAL standard supports the following file formats for 3D models:
+
+* glTF
+* FBX
+* USD
+
+NOTE: The details of FBX's IP are protected by Autodesk's license and are not publicly available information, but are there any concerns?
+https://download.autodesk.com/us/FY17/Suites/LSA/en-us/lsa.html
+

content/geometry/General.adoc

@@ -0,0 +1,71 @@
+= General
+
+== Dimensions
+The unit used for object dimensions is meters.
+
+== Coordinate systems
+The local coordinate system is a right-handed coordinate system according to
+ISO 8855 with the axes pointing to the directions mentioned below. For a non-rotated
+coordinate system, the following applies:
+
+* Forward matches x-axis
+* Left matches y-axis
+* Up matches z-axis
+
+NOTE: TODO: Add images similar to OpenDRIVE? See
+https://publications.pages.asam.net/standards/ASAM_OpenDRIVE/ASAM_OpenDRIVE_Specification/latest/specification/08_coordinate_systems/08_04_local_coordinate_system.html
+
+
+The coordinate system is in line with the standards ASAM OpenDRIVE,
+ASAM OpenSCENARIO, and ASAM OSI.
+
+NOTE: Origins of the coordinate frames for specific object classes are under
+discussion.
+
+== Naming conventions
+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.
+
+NOTE: Putting more information in file name to be discussed for specific object classes.
+
+== 3D asset file
+The 3D asset file provides meta data 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.
+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 ?
+
+NOTE: TODO: Add short descriptions and references
+
+== Requirements
+Materials shall be separated.
+
+NOTE: TODO: Extend rule and find better location. What do you want to express, that two
+materials with different properties need to be modeled by separate objects?
+Are there any other requirements regarding quality, semantic/animation/material structure?
+
+
+== Recommendations
+
+* The same texel density should be used within a file. (asset file?)
+* For each object class, the recommended mesh resolution should be used.
+* To improve performance of vegetation objects, alpha textures should be used.
+
+NOTE: TODO: Move recommendations to descriptive sections, e.g. object class
+recommendation to section "Object Class".

content/geometry/Introduction.adoc

@@ -0,0 +1 @@
+= Introduction

content/geometry/Metadata.adoc

@@ -0,0 +1,27 @@
+= Metadata
+
+In ASAM OpenMATERIAL, metadata of material assets and geometries is stored in
+each asset file. The metadata is independent of the 3D file format.
+
+The following list provides examples of metadata information:
+
+* 3D model name/title, unique ID, version
+* ASAM OpenMATERIAL version
+* Author and authoring tool, creation date
+* Origin/source (3D scan, modeled by image, public ressource, ...)
+* Description field (free text)
+* Copyright information (notice/protection) and license type (CC0, GPL, ...)
+* Labeling (object class, materials, abstraction level: Scene/object/component/animation)
+* Complexity information (Mesh/texture resolution or class (real-time, non-real-time), ...)
+* Used technologies (alpha textures, normal maps (DirectX or OpenGL), and so on) ?
+* Validation information
+* Material mapping type (per mesh, per vertex, per texel)
+* Class-dependent metadata ?
+** Vehicles:
+*** Axes and wheel positions
+
+NOTE: What about other geometrical data in the Asset file? E.g. Thickness of meshes, mass of meshes etc. (CL)  
+
+NOTE: Within the metadata, the available nodes of a model should be spcified. I can image classes of model fidelity specifying sets of nodes (LF)  
+
+NOTE: Eyepoint limits could be part of the metadata (LF)  

content/geometry/Object-Geometry_classes_and_segmentation.adoc

@@ -0,0 +1,59 @@
+= Object and geometry classes
+
+== Object classes
+In ASAM OpenMATERIAL, object classes represent a collection of similar objects.
+Examples of object classes are vehicles, humans, and the road network. Each
+instance of the object class is described by the same properties, but has
+individual property values.
+
+The ASAM OpenMATERIAL standard supports the following object classes:
+
+* Vehicle
+* Human
+* Road and road infrastructure
+* Vegetation, including trees
+* Building
+* Animal
+* Custom class
+
+NOTE: TODO: Add references to dedicated sections describing object classes. Vegetation, building, and
+animal are not yet supported
+
+If the human is clearly distinguishable from the vehicle, then both the
+human and the vehicle are represented by two different objects. Examples are
+bicycles, motorbikes, or scooters, where the human and the vehicle are
+perceived as separate entities.
+
+== Class-specific information
+Each object class has a specific set of properties, such as:
+
+* Node structure
+* Semantic structure
+* Animation structure
+* Material structure
+* Coordinate system
+* Pivot points
+* Mesh resolution
+
+The interpretation of the following coordinates depends on the class-specific
+rules:
+
+* The x/y position represents the center of the bounding box used
+to describe the shape of the object.
+* The value on the z-axis on the ground represents the default pose.
+
+*Example*
+For object class `vehicle`, the z-value defines the pose if a vehicle door is
+closed. For object class `human`, the z-value defines the T-pose.
+
+For each object class, the recommended mesh resolution should be used.
+
+NOTE: TODO: Added information on mesh resolution to this section. We should consider
+extending the description of the properties above.
+
+NOTE: TODO: Discuss and document
+- Class-specific file name conventions
+- New or rare structures (for example, front trunk)
+- Class-specific levels of detail and impostors
+
+NOTE: TODO: Add information on geometry classes + segmentation?

content/geometry/Performance.adoc

@@ -0,0 +1,3 @@
+= ASAM OpenMATERIAL Performance
+
+* ...

content/geometry/general-structure-index.adoc

@@ -0,0 +1,9 @@
+= General Structure
+
+include::Introduction.adoc[]
+include::General.adoc[]
+include::Object-Geometry_classes_and_segmentation.adoc[]
+include::File_format_support.adoc[]
+include::Metadata.adoc[]
+include::Performance.adoc[]
+

content/index.adoc

@@ -31,16 +31,15 @@ include::general_docs/introduction.adoc[leveloffset=+1]
 
 :sectnums:
 include::general_docs/scope.adoc[leveloffset=+1]
-
 include::general_docs/normative_references.adoc[leveloffset=+1]
-
-include::terms_and_definitions/terms_and_definitions.adoc[leveloffset=+1]
-
 include::general_docs/abbreviations.adoc[leveloffset=+1]
-
 include::general_docs/backward_compatibility.adoc[leveloffset=+1]
+include::terms_and_definitions/terms_and_definitions.adoc[leveloffset=+1]
+include::use_cases/use_cases.adoc[leveloffset=+1]
+include::geometry/general-structure-index.adoc[leveloffset=+1]
+include::material/general-structure-index.adoc[leveloffset=+1]
+
 
-// Add further sections and chapters here as needed
 
 :sectnums!:
 == Annexes