@kognifai/cogsengine
    Preparing search index...

    Cogs Batch Format

    This document describes how wo define batch processing commands for Cogs.Core.Runtime program.

    Version 1.0

    Add command argument

    --editor.batch=PathToJsonBatchFile.json
    
    {
    "extensions": [
    "Cogs.Core.Extensions.RationalReducer",
    "Cogs.Core.Extensions.RVM"
    ],
    "source": "",
    "destination": "",
    "batch": [
    // Commands to be run on each input file.
    ],
    "post": [
    // Commands to be run after all 'batch' commands processed.
    ]
    }

    List of Cogs Extensions to load.

    The source section must be a string pattern matching one or more files.

    The source string may use regular expressions for advanced file pattern matching in the stem of the filename.

    {
    // All .fbx files in current directory
    "source": "*.fbx",
    // All .cogsbin files in /Data/Models with MECH or STRU in name
    "source": "/Data/Models/.*MECH|STRU.*.cogsbin",
    }

    An alternative is to specify "sourcedir" and (then required) "match".

    {
    // Search through everything recursively in this directory
    "sourcedir": "modelfolder",
    // For all .cogsbin files
    "match": "*.cogsbin",
    }

    The destination section must be a string path to a directory used to store exported models.

    {
    // Current directory
    "destination": ".",
    // /Data/ProcessedModels
    "destination": "/Data/ProcessedModels",
    }

    If used with 'sourcedir' as explained above, corresponding sub-folders will be created in the destination directory. Note that currently textures won't be written to these folders. A workaround for the moment is to set destination to the same as sourcedir. Writing out to sub-folders also works when combined with the fileName option of the Export command.

    The batch section is an array of commands to execute per input source file.

    Commands are run in the order they are specified in the array.

    {
    "batch": [
    {
    // Executed first
    "type": "Type1"
    },
    {
    // Executed second
    "type": "Type2"
    }
    ]
    }

    Each command object must specify a type, and any options available for the given command type. Unspecified options are set to their default values.

    {
    "type": "MyCommand",
    "myOption": false,
    "myOtherOption": 123.0,
    }

    Post Commands

    Build an .asset/.cogsbin hierarchy with an octtree structure from all inputs. Large model CAD import command.

    "post": [
    {
    "type": "BuildOctree",
    // Params...
    }
    ]

    For details see BuildOctree.

    Exit Cogs.Core.Runtime after processing the batch file - e.g.g run unattended. Leaving this out is useful for debugging as processed input is displayed in editor.

    Batch commands allows reading models, processing and exporting (for example to cogsbin). If using batch commands note that naming input files works different from PostCommand like BuildOctree. Recommand passing full path of input file(s) in input array and output directory in output.

    Read an hierarchy of .asset-files and .cogsbin files, process, and write the result to a target directory.

    • Replaces filenames with numbers
    • If not pretty-print is true, .asset files are stripped of names and compressed
    • Target specifies the how the meshes should be repacked. Available options:
      • webgl1-lo: Format compatbile with WebGL1, aim at using 2x8 bits for normal vectors.
      • webgl2-lo: Format compatbile with WebGL2, aim at using 2x8 bits for normal vectors.
      • webgl2-med: Format compatible with WebGL2, aim at using 2x16 bits for normal vectors. Default.
      • webgl1: currently alias for webgl1-lo.
      • webgl2: currently an alias for webgl2-med.
    • 'compressAsFile': If true, compress cogsbin as a file to cogsbin.zst instead of compressing individual sections. This allows decompressing entire file in cogs.js during transit at the cost of not being able to decompress individual sections in the file.
    • trackIdRanges: Specifies the number of id ranges to track, zero implies no id tracking.

    Example:

    {
    "source": "foobar.asset",
    "destination": "Q:\\targetDirectory",
    "batch": [ ],
    "post": [
    {
    "type": "AssetPipe",
    "properties": {
    "target":"WebGL1",
    "prettyPrint": true,
    "compressAsFile": true,
    "trackIdRanges": 4
    }
    },
    {
    "type": "Exit"
    }
    ]
    }

    The DumpStats command can be used to display model statistics at any stage of batch processing.

    {
    "type": "DumpStats",
    // Set a title to be displayed alongside the statistics
    "title": "Unprocessed stats"
    }

    The export command exports the model hierarchy as a binary Cogs Model.

    Special tokens may be used in the fileName option to build a file name from model parameters.

    Supported parameters:

    • $Date - "YYYY-MM-DD" Date string
    • $FileName - Original file name, excluding extension.
    • $Extension - Original file extension. Currently this also includes "."
    • $Year - "YYYY" Year string
    • $Month - "MM" Month string
    • $Day - "DD" Day string
    {
    "type": "Export"
    // If source fileName was Model.fbx the following would result in "2018-01-01 - Model.fbx.cogsbin"
    "fileName": "$Date - $FileName.$Extension.cogsbin"
    }

    If fileName is not provided it will just be $FileName.cogsbin

    Example Batch-file Converting RvmDump to CogsBin

    {
    "extensions": [
    "Cogs.Core.Extensions.RVM"
    ],
    // Pass full path to input file
    "source": "C:/Dir/model.rvmdump",
    // Output directory.
    "destination": "C:/DirAsset",
    // Run Export command
    "batch": [
    {
    "type": "Export",
    "fileName": "model.cogsbin"
    }
    ],
    "post": [
    {
    "type": "Exit"
    }
    ]
    }

    TODO

    The Merge command can be used to simplify the hierarchy of a model by merging leaf nodes in the entity graph to single entities.

    TODO: Implement/describe merge criteria.

    {
    "type": "Merge",
    "matchRegex": "^/[^/]*$"
    }

    The MergeMesh command can be used to improve rendering efficiency in a model by merging mesh data into larger batched mesh chunks. The hierarchy of the model is not affected, all entities render using the same materials and same geometry as before running the command.

    {
    "type": "MergeMesh"
    // Controls how large a merged mesh should be before moving to the next batched mesh resource.
    "vertexCountThreshold": 100000
    }

    TODO - MaterialInstance usage remapping...

    Apply editor select command. Parameter: "entityId" = EntityId to select. Used for debugging as entity ids are only known after viewing processed batch.

    TODO

    {
    "type": "UniqueVertices"
    "keepNormals": bool // Does not work
    "keepTexCoords": bool // Does not work
    "keepTangents": bool // Does not work
    }