This document describes how to define the AssetStatsCommand Batch Command for Cogs.Core.Runtime program.
A minimal batch file looks like
{
"source":"<some_root.asset>",
"destination": "<output directory>",
"batch": [ ],
"post": [
{
"type": "AssetStats",
"properties": {
// ... properties, se below
}
},
{
"type": "Exit"
}
]
}
This command can also be automatically invoked as part of the
BuildOctreeCommand if the statistics property for
that command is set to true. In that case, properties will be fetched from
the properties of the BuildOctreeCommand.
It reads the asset hierarchy starting from the root asset specified in the source, calculates statistics and checks rules and outputs the result in a json file in the destination directory.
The properties allow one to override the default settings and rules:
referenceFieldOfView: The field of view used to estimate projected sizes.
Value is in radians, and defaults to pi/4.
referenceScreenSize: The screen height used to estimate projected sizes.
Value is in pixels, and defaults to 1000.
splitPointScreenCoverMin: The smallest relative screen height of a lod
node that is acceptable before the lod node should be split. A value of 0.5
indicates that if the lod node fills less than half the height of the
screen when it transitions to a more detailed lod node, the transition is
premature.
splitPointScreenCoverMax: The largest relative screen height of a lod node
that is acceptable before a split. A value of 2 indicates that if a lod is
more than double the height of the screen before transitions to a more
detailed lod level, the lod transitions too late.
splitPointScreenCoverFurthesSplitMax: The maximum relative screen height
of the most coarse lod node when it transitions from the next-to-coarsest
lod node. A value of 0.2 means that the lod node should maximally have the
height of 20% of the screen when transitioning to the most coarse lod
node.
splitPointMinTriangleEdgeLength: The minimum of mean max edge of triangles
to accept before a transitioning. A value of 10 means that the mean longest
edge of triangles should be more than 10 pixels before switching to a more
detailed lod-level.
perLevelMinTriangleIncrease: The minimum amount of increase of triangle
count between levels. A value of 1.5 means that at least a 50% increase in
triangle count from a level to a more refined level is required.
The statistics of each threshold interval/level of detail is checked against a set of rules. These rules are to be treated as a guide to identify problematic errors that might warrant some extra inspection.
TriangleMeanMaxEdgeTooSmall: This triggers when the triangles for the
models in a lod level become too small on screen. This might indicate that
the lod level can be further simplified, have a bigger tolerance or a
smaller threshold.
NearScreenCoverOutOfRange: This triggers when the projected screen height
of a lod node is either too small or too large when it transitions to a
more detailed lod level. Usually paired with a FarScreenCoverOutOfRange
for the more detailed lod level.
FarScreenCoverOutOfRange: This triggers when the projected screen height
of a lod node is either too small or too large when it transitions to a
more coarse lod level. Usually paired with a NearScreenCoverOutOfRange
for the coarser lod level.
NearScreenCoverAtCoarsestLodTooBig: This triggers when the most coarse
lod-level is too big on screen, and there might be necessary with
additional coarser lod levels.
TooLittleTriangleIncrease: Too little increase in triangle count between
two adjacent levels. This might indicate that the more detailed level is
unnecessary, since it doesn't introduce much new geometry, or the coarse
level is too detailed.
The statistics and the violations are output in hierarchical form in a json file.
This is how a pure lod-node looks:
{
"minDistance": 10.0, // Minimum distance/threshold for this lod node
"maxDistance": 20.0, // Maximum distance/threshold for this lod node
"lodNodeBounds": { // Statistics for the world-space max side length of lod node bounding boxes
"count": 4, // Number of lod nodes at this level
"mean": 358.7559, // The mean max side length
"minValue": 358.7559, // The smallest max side length encountered
"maxValue": 358.7559 // The largest max side length encountered.
},
"issues": [ ... ], // A list of issues found, not present if there were no issues
"children": [ ... ] // The child nodes
}
A node with geometry looks like this:
{
"minDistance": 20.0, // Minimum distance/threshold for this lod node
"maxDistance": 40.0, // Maximum distance/threshold for this lod node
"modelBounds": { // Statistics for the world-space max side length of the models
"count": 218, // Number of models at this level
"mean": 6.2234, // The mean bounding box max side length of models
"minValue": 0.1139, // Smallest max side length encountered
"maxValue": 22.4222 // Largest max side length encountered
},
"triangleCount": 5372, // Number of triangles in this lod level
"triangleArea": { // Statistics for triangle world-space area
"mean": 0.602,
"minValue": 0.0012,
"maxValue": 12.9268
},
"triangleMinEdge": { // Statistics for the shortest edge of each triangle
"mean": 0.5733,
"minValue": 0.0289,
"maxValue": 6.661
},
"triangleMaxEdge": { // Statistics for the longest edge of each triangle
"mean": 2.2705,
"minValue": 0.0567,
"maxValue": 22.1911
},
"pixels": { // Triangle statistics projected to reference screen when this is well-defined
"screenDistance": 5.0, // Distance from eye to triangle used when projecting
"triangleArea": { // Statistics of projected triangle areas, in pixels^2
"mean": 35088.6875,
"minValue": 72.4276,
"maxValue": 753431.125
},
"triangleMinEdge": { // Statistics of projected shortest edge of each triangle, in pixels
"mean": 138.4121,
"minValue": 6.9994,
"maxValue": 1608.1289
},
"triangleMaxEdge": { // Statistics of projected longest edge of each triangle, in pixels
"mean": 548.1669,
"minValue": 13.6996,
"maxValue": 5357.4218
}
}
"issues": [ ... ], // A list of issues found, not present if there were no issues
}
An issue looks like this:
{
"id": "FarScreenCoverOutOfRange", // Identifies the class of issue
"severity": 0, // Severity of issue, currently always 0
"what": "..." // A textual description of the issue
}