7.5 Asset schema
7.5.1 Overview
This is the documentation about the JSON schema file. The actual file is located in the ASAM OpenMATERIAL 3D GitHub repository.
The following diagram shows the hierarchy of the fields defined in this schema. Fields marked with (R) are required. A field can be optional while some of its children are required. In that case, the required children only have to be filled in if the optional parent field is present.
7.5.2 metadata
The key meta information about the asset, including its identity, authorship, technical specifications, and legal details.
Type: object
Required: Yes
7.5.2.1 name
The display name of the asset, such as 'Car Model A' or 'Urban Scene 1'.
Type: string
Required: Yes
7.5.2.2 description
A concise summary of the asset’s purpose or features in two to three sentences.
Type: string
Required: No
7.5.2.3 uuid
Universally unique identifier for the asset in 8-4-4-4-12 format, see [12]. The uuid stays the same, even if version is updated.
Type: string
Pattern: \b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b$
Required: Yes
7.5.2.4 assetVersion
The version number of the asset, following semantic versioning (for example, '1.0.0').
Type: string
Pattern: ^\d+\.\d+\.\d+$
Required: Yes
7.5.2.5 openMaterial3dVersion
The version of the ASAM OpenMATERIAL 3D specification used, adhering to semantic versioning (for example, '1.0.0').
Type: string
Pattern: ^\d+\.\d+\.\d+$
Required: Yes
7.5.2.6 copyrights
Indicates copyright details, including the year and copyright holder (for example, '© 2024 ACME Inc.').
Type: array
Item count: at least 1
Item type: string
Required: Yes
7.5.2.7 license
Describes the license for asset distribution. Use an SPDX identifier for open-source licenses (for example, 'MIT'), or provide a URL or filename for proprietary licenses.
Type: string
Required: Yes
7.5.2.8 authors
Lists the author(s) of the asset as a name, email, or company.
Type: array
Item count: at least 1
Item type: string
Required: Yes
7.5.2.9 modelCreationTool
Specifies the software or tool (and version) used to create the 3D model (for example, 'Blender 3.5').
Type: string
Required: No
7.5.2.10 creationDate
The date and time of asset creation, formatted as YYYYMMDDTHHMMSSZ according to ISO 8601 (for example, '20240703T101728Z').
Type: string
Pattern: ^\d{8}T\d{6}Z$
Required: No
7.5.2.11 modelingMethod
Indicates how the model was created, for example, '3D scan', 'photo-based modeling', or 'freehand design'.
Type: string
Required: No
7.5.2.12 validationDescription
Details the validation process used to compare the model geometry with real-world objects.
Type: string
Required: No
7.5.2.13 assetType
Specifies whether the asset represents an individual object ('object') or a collection of objects ('scene'). The value 'scene' is deprecated as of ASAM OpenMATERIAL 3D 1.1.0 and is replaced by the 'externalAssetReferences' property.
Type: string
Enum: 'object', 'scene'
Required: No
7.5.2.14 objectClass
Classifies the object type when 'assetType' is 'object'. The value is one of 'vehicle', 'human', 'environment', or 'other'.
Type: string
Enum: 'vehicle', 'human', 'environment', 'other'
Required: Yes
7.5.2.15 vehicleClassData
Vehicle-specific data. This shall be filled if 'objectClass' is 'vehicle' based on the OpenSCENARIO XML vehicle definition.
Type: object
Required: No
7.5.2.15.1 vehicleCategory
Type of the vehicle.
Type: string
Enum: 'car', 'van', 'truck', 'trailer', 'semitrailer', 'bus', 'motorbike', 'bicycle', 'train', 'tram'
Required: Yes
7.5.2.15.2 performance
Performance values of a vehicle.
Type: object
Required: Yes
7.5.2.15.3 axles
A set of the axles of a vehicle. A vehicle shall have a front axle and a rear axle. It may have additional axles. The information about the rear axle is needed to transform the origin of the model to coordinate systems of other ASAM standards, for example, the ASAM OpenSCENARIO XML vehicle coordinate system or the ASAM OSI host vehicle coordinate system.
Type: object
Required: Yes
frontAxle
The definition of a vehicle axle, based on the OpenSCENARIO XML vehicle axle definition.
Type: object
Required: Yes
maxSteering
Maximum steering angle that can be performed by the wheels on this axle. Unit: rad. The steering angle is symmetrical in both directions.
Type: number
Range: [0, 3.14159]
Required: Yes
wheelDiameter
Diameter of the wheels on this axle. Unit: meter.
Type: number
Range: ]0, inf[
Required: Yes
trackWidth
Distance between the center lines of the wheels at zero steering. Unit: meter.
Type: number
Range: [0, inf[
Required: Yes
rearAxle
The definition of a vehicle axle, based on the OpenSCENARIO XML vehicle axle definition.
Type: object
Required: Yes
maxSteering
Maximum steering angle that can be performed by the wheels on this axle. Unit: rad. The steering angle is symmetrical in both directions.
Type: number
Range: [0, 3.14159]
Required: Yes
wheelDiameter
Diameter of the wheels on this axle. Unit: meter.
Type: number
Range: ]0, inf[
Required: Yes
trackWidth
Distance between the center lines of the wheels at zero steering. Unit: meter.
Type: number
Range: [0, inf[
Required: Yes
additionalAxles
An optional array of additional axles with the same properties as 'frontAxle' and 'rearAxle'.
Type: array
Required: No
maxSteering
Maximum steering angle that can be performed by the wheels on this axle. Unit: rad. The steering angle is symmetrical in both directions.
Type: number
Range: [0, 3.14159]
Required: Yes
wheelDiameter
Diameter of the wheels on this axle. Unit: meter.
Type: number
Range: ]0, inf[
Required: Yes
trackWidth
Distance between the center lines of the wheels at zero steering. Unit: meter.
Type: number
Range: [0, inf[
Required: Yes
7.5.2.16 humanClassData
Human-specific data. This shall be filled if 'objectClass' is 'human' based on the OpenSCENARIO XML pedestrian definition.
Type: object
Required: No
7.5.2.17 animated
Indicates whether the 3D model contains keyframe animations.
Type: boolean
Required: Yes
7.5.2.18 pbrMaterialWorkflow
Indicates the usage of a physically based rendering (PBR) material workflow as 'metallic', 'specular', or 'none'. This only applies to the internal materials of the 3D model file, not to mapped ASAM OpenMATERIAL 3D property files.
Type: string
Enum: 'metallic', 'specular', 'none'
Required: Yes
7.5.2.19 triangleCount
The total number of triangles in the model. A quad polygon counts as two triangles.
Type: integer
Range: [1, inf[
Required: Yes
7.5.2.20 meshCount
The total number of meshes in the 3D model file. A model geometry typically consists of several sub-meshes.
Type: integer
Range: [1, inf[
Required: Yes
7.5.2.21 textureResolutions
Lists all texture resolutions used in the 3D model, for example, for 'albedo', 'normal', or 'displacement' textures. Possible values are '1K', '2K', and '4K'. If no textures are used in the model, add a single empty string ''.
Type: array
Item count: at least 1
Unique items: Yes
Item type: string
Item enum: '1K', '2K', '4K', ''
Required: Yes
7.5.2.22 normalMapFormat
Specifies whether the 3D model uses normal maps as textures. If so, their format shall be either 'DirectX' or 'OpenGL'. Otherwise, the value is 'none'.
Type: string
Enum: 'DirectX', 'OpenGL', 'none'
Required: Yes
7.5.2.23 boundingBox
Defines the axis-aligned bounding box (AABB), which defines the spatial boundaries of an asset in 3D space. Example: "boundingBox": {"x": [-2.5, 2.5], "y": [-1.1, 1.1], "z": [0, 1.8]}
Type: object
Required: Yes
7.5.2.23.1 x
Minimum and maximum values in meters along the x-axis.
Type: array
Item count: exactly 2
Item type: number
Required: Yes
7.5.3 materialMappingUri
Relative or absolute file path to a material mapping file (.xomm). In this file, material names from the 3D model file or texture color codes from textures assigned in 'materialTextureAssignment' are linked to ASAM OpenMATERIAL 3D property files. For cross-platform compatibility, Unix-style paths are recommended.
Type: string
Pattern: .*\.xomm$
Required: No
7.5.4 materialTextureAssignment
Optional array containing material texture assignments. It links material names contained in the 3D model file to ASAM OpenMATERIAL 3D assignment textures. In a separate material mapping file, the 'color' values in this texture are linked to ASAM OpenMATERIAL 3D property files.
Type: array
Required: No
Column count: exactly 2
Columns of the table:
| Column | Type | Constraints | Description |
|---|---|---|---|
1 |
string |
Name of the material in the 3D model file. |
|
2 |
string |
Relative or absolute file path to the ASAM OpenMATERIAL 3D assignment texture. For cross-platform compatibility, Unix-style paths are recommended. |
7.5.5 materialReplacements
Optional array containing material reassignments. It links material names contained in the 3D model file to RGB codes or alternative names that are used as keys in the ASAM OpenMATERIAL 3D material mapping file. An example of the material replacement mechanism can be found in the examples folder of the ASAM OpenMATERIAL 3D GitHub repository.
Type: array
Required: No
Column count: exactly 2
Columns of the table:
| Column | Type | Constraints | Description |
|---|---|---|---|
1 |
string |
Name of the material in the 3D model file. |
|
2 |
string |
Replacement name or RGB code to use as key into the material mapping instead of the original material name in the 3D model file. RGB codes are formatted as rgb:<R>;<G>;<B>. <R>, <G>, and <B> are integers in the range [0, 255]. |
7.5.6 externalAssetReferences
Optional array containing references to external 3D assets. It links parent nodes in the 3D model file to external ASAM OpenMATERIAL 3D asset files (.xoma).
Type: array
Required: No
7.5.7 lightDefinitions
A list of discrete light sources, for example, point lights or spotlights, linked to the 3D asset hierarchy.
Type: array
Required: No
| Only one of 'color' and 'temperature' shall be set. All of them may be omitted. |
7.5.7.1 node
Identifier of the node in the 3D model hierarchy that defines the light origin. The light is located at the origin of this node, and the node name determines the lighting function the light is mapped to. For example, a light associated with the node Grp_Light_Low_Beam_Left_0 of a vehicle asset shall be turned on in a simulation when the low beam is activated. If a generic node name is used, for example, Grp_Light_0, the simulator can decide which lighting function to map it to. In this case, the behavior is not standardized.
Type: string
Required: Yes
7.5.7.2 photometricProfileUri
Relative or absolute file path to an IES or EULUMDAT file defining the light profile. For cross-platform compatibility, Unix-style paths are recommended.
Type: string
Format: uri-reference
Pattern: .*\.(ies|ldt|IES|LDT)$
Required: No
7.5.7.3 radiometricProfileUri
Relative or absolute file path to a table providing radiance per wavelength. For cross-platform compatibility, Unix-style paths are recommended. The format of the referenced radiance table is not defined in this standard. It may be defined in a future version.
Type: string
Format: uri-reference
Required: No
7.5.7.4 innerConeAngle
Half of the opening angle of a conical spotlight, measured from the cone axis to the angle at which the light falloff begins. Unit: rad; Range: [0, \(\pi\)]. If this field is not set, the default is 0. If a photometric profile is set, this value is overridden but serves as a fallback if a renderer cannot load the profile.
Type: number
Range: [0, 3.14159]
Required: No
7.5.7.5 outerConeAngle
Half of the opening angle of a conical spotlight, measured from the cone axis to the angle at which the light falloff ends. Unit: rad; Range: [0, \(\pi\)]. If this field is not set, the light is considered a point light. If a photometric profile is set, this value is overridden but serves as a fallback if a renderer cannot load the profile.
Type: number
Range: [0, 3.14159]
Required: No
7.5.7.6 luminousIntensity
Luminous intensity of the light source. Unit: candela (cd). If a photometric profile is set, this value is overridden but serves as a fallback if a renderer cannot load the profile.
Type: number
Range: [0, inf[
Required: Yes
7.5.8 emissiveLightMapping
Mapping of emissive properties to a specific material and an associated group node in the 3D model file. This concept can be used in any type of object.
Type: array
Required: No
| If 'maskingTextureUri' is set, 'emissiveTextureUri' shall also be set. |
7.5.8.1 assocNode
Identifier of the node in the 3D model hierarchy that this emissive light is associated with. In contrast to the 'node' property of 'lightDefinitions', this node does not define any spatial placement. It is used solely to derive the lighting function from its name. For example, an emissive material associated with the node Grp_Light_Indicator_Left_0 of a vehicle asset shall be turned on in a simulation when the left indicator is activated. If a generic node name is used, for example, Grp_Light_0, the simulator can decide which lighting function to map it to. In this case, the behavior is not standardized.
Type: string
Required: Yes
7.5.8.2 materialName
The name of the material within the 3D model file to which this mapping applies.
Type: string
Required: Yes
7.5.8.3 luminance
Luminance of the emissive material. Unit: candela per square meter (cd/m2).
Type: number
Range: [0, inf[
Required: Yes
7.5.8.4 emissiveTextureUri
Relative or absolute file path to an emissive texture. See the 'color' property for the equation describing how the emissive texture value is used in the lighting calculation. For cross-platform compatibility, Unix-style paths are recommended.
Type: string
Format: uri-reference
Required: No
7.5.8.5 maskingTextureUri
Relative or absolute file path to the masking texture that masks a defined part of an emissive atlas texture. For cross-platform compatibility, Unix-style paths are recommended.
Type: string
Format: uri-reference
Required: No
7.5.8.6 color
Emissive color, or RGB multiplier when used in combination with an emissive texture. The final color in the renderer is calculated as finalColor = baseColor + emissiveColor * emissiveTextureColor * emissiveStrength. The simulator shall set emissiveStrength so that the resulting luminance of the emissive material matches the defined 'luminance' value.
Type: object
Required: Yes