InstaLOD Analyze

What is InstaLOD Analyze?

InstaLOD Analyze is an analysis/data-scoring feature that allows users to quantify the quality of their 3D data. This is important when e.g. dealing with third parties.

By using InstaLOD Analyze, companies can, for example, make sure that the data sent into their automated pipeline by their outsourcers follow certain quality standards, that the mesh is located at the scene origin, or that the files follow their material naming conventions. With this system, companies can ensure that the data entering their automated 3D pipeline is suitable for processing.

Installation

InstaLOD Analyze is integrated into InstaLOD Pipeline 2020 and runs on Windows and macOS. Please use the InstaLOD Pipeline documentation for more information on how to get started with InstaLOD Pipeline.

Creating analysis profiles

In order to analyze a file, a Profile needs to be created. Analysis profiles contain rules and parameters to extract information from files and determine their scoring. To get started with InstaLOD Analyze, it is recommended to inspect the sample JSON profile Analyze that is included in the InstaLOD Pipeline 'Profiles' folder.

Analysis Profile Overview

An Analysis profile consists of Scene Rules and Global Match Rules which both contain Match Rules to determine if a score is awarded.  

Scene Rules are only executed if they match the name of the processed file using a regular expression. Each matching scene rule can award scores based on certain scene attributes. Further, each Scene Rule can define multiple Match Rules that can award scores based on mesh attributes such as the mesh polygon count. If a Scene Rule does not match the processed file, it is ignored and does not award scores. Match Rules that are defined within a Scene Rule are then skipped as well.

Scene Rules provide a powerful tool that allows using a single Analysis profile to analyze different types of data.

Global Match Rules contain rules that can award scores based on mesh attributes. Global Match Rules are always executed when processing a file.

An Analysis profile can be structured as follows:

"SceneRules" : [
    {
        "// If the filename matches this regex the rules of this data-scoring section are run."
        "FileNameRegEx" : ".*",
        ...
        "MatchRules" : [
            {
                 ...
            },
            {
                 ...
            },
            ...
        ]
    },
    {
         "FileNameRegEx" : ".*",
         ...
    },
    ...
],
"GlobalMatchRules" : [
    {
         ...
    },
    {
         ...
    },
    ...
]

Awarding scores with rules

Rules are used to match specific parameters. If a rule matches an attribute, a score is awarded and written into the analysis result. InstaLOD Analyze awards positive or negative scores based on the following two subsets of attributes:

Scene Attributes	MeshCountMinimum, MeshCountMaximum, HierarchyDepthMaximum, SceneDimensionsMins, and SceneDimensionsMaxs
Mesh Attributes	e.g. Mesh.Polygons.Count A full list of Mesh Attributes is available here.

Awarding scores for Scene Attributes through Scene Rules is straightforward. If the attribute matches the value specified by the rule, a score can be awarded, for example: "Decrease the score by 100 if the scene contains more than 1000 individual meshes".

Mesh Attributes can be matched through Match Rules in different ways by specifying a Match Target:

1. Award scores based on each mesh that matches, e.g. :
   "Increase the score by 20 for each mesh with over 100 polygons"
2. Award scores for the whole scene, e.g.:
   "Increase the score by 20 if the total scene mesh polygon count is higher than 1000"

The final score can be used to determine if the analyzed files meet the required standards or need improvement.

Scene Rules

Scene Rules are constructed of a Scene Match Rule and any number of Mesh Match Rules. Only if the Scene Rule matches a file, additional Match Rules can be executed to analyze the mesh using various parameters and attributes.

Example:

"FileNameRegEx" : ".*",
"FileNameRegExMatchingScore" : 100.0,

If the filename matches the regex above, the rules of the following data-scoring section are run:

"// MeshCount*" : "If the number of meshes is above/below the threshold, a score is awarded.",
"MeshCountMinimum" : 0,
"MeshCountMinimumMatchingScore" : 100.0,
"MeshCountMaximum" : 10,
"MeshCountMaximumMatchingScore" : 100.0,

"// HierarchyDepthMaximum" : "If the maximum depth is below this value, a score is awarded.",
"HierarchyDepthMaximum" : 5,
"HierarchyDepthMatchingScore" : 100.0,

Match Rules

Match Rules can be either defined within the Global Match Rules section where they are always processed or within a Scene Rule. When a Match Rule is defined in a Scene Rule, it is only processed if the Scene Rule matches.

Match Rules are constructed of the following parameters:

Parameter	Explanation	Available Commands	Example
Description	Describes what the rule does		"AABB Mins aligned to 0.0"
Attribute	Specifies the analyzed attribute. This can either be a numerical attribute or a string attribute such as a name.	See List of Attributes	"Mesh.AABB.Mins.Z"
MatchValue	A relational expression that checks the value of the specified numerical attribute. Multiple expressions can be combined with the logical operator AND.	< / > / =	">0.0", ">=100", ">=0 and <50"
MatchRegEx	A regular expression that checks the value of the specified string attribute.	RegEx (ECMAScript)	".*", "LeatherMat|ClothMat", "\\w+"
MatchScore	The score the object will receive if this rule matches		“MatchScore” : -999999999
MatchTarget	Mesh rules will only be run against the individual scene meshes. Scene can be specified to run the rule against the scene mesh (a mesh that is a combination of everything in the scene). All can be used to execute the rule once for each mesh and once for the scene mesh.	Mesh/Scene/All

Executing an Analysis

In order to queue files for analysis, a valid profile needs to be loaded.
Profiles can be loaded by specifying the -profile argument followed by a filename:

-profile <filename>

Once a profile has been loaded, files can be queued. Files are queued directly using the -file argument.
The -file argument accepts the following arguments in a fixed order:

-file <input filename> <output profile> <profile name>

The <output profile> file should contain the output location and name. If no location is specified, the default InstaLOD Pipeline folder directory is used. The generated JSON file contains the analyzed data including the final data scoring information. If a different file extension other than JSON is specified, InstaLOD will still export as JSON nonetheless.

By passing the -folder argument to InstaLOD Pipeline entire folders can be queued at once by specifying a search folder and a file-mask.
The -folder argument requires the following arguments in a fixed order.

-folder <search path> <file mask> <output profile> <profile name>

If the search path argument ends with /**, InstaLOD Pipeline will recursively search for all files in all sub-folders of the specified folder.

The following command analysis the file “SM_Troll.fbx” using the Analysis profile.

InstaLODCmd -profile Analysis.json -file SM_Troll.fbx SM_Troll-report.json "Analysis"

Once the analysis is complete, a JSON file is created containing the results of the analysis.