DOCSEARCHbyAlgolia
Submit Docs

obj2mjcf

repository·main·Indexed 18 days ago

https://github.com/kevinzakka/obj2mjcf

A CLI tool that automates the conversion of complex, multi-material Wavefront OBJ files into MuJoCo-compatible MJCF XML files. It supports splitting OBJ files by material, generating MJCF XML elements, and optional convex decomposition for collision meshes using CoACD.

Tokens
992
Snippets
3
Records
6
Agent score
13%

What's inside obj2mjcf

  1. Overview of obj2mjcf

    main

    obj2mjcf is a command-line interface (CLI) tool designed to process composite Wavefront OBJ files for use in MuJoCo. It automates the conversion process by:

    • Splitting OBJ files: It breaks down a single OBJ file into sub-meshes based on the materials referenced in the associated MTL file.
    • Generating MJCF XML: It creates an MJCF XML file that is pre-populated with the necessary <material>, <mesh>, and <geom> elements that reference the processed OBJ files.
    • Collision Mesh Generation: It can optionally generate collision meshes by performing convex decomposition on the OBJ using CoACD.

  2. Install obj2mjcf via pip

    main

    Install the package using PyPI.

    Prerequisite: MuJoCo support for OBJ files requires MuJoCo version 2.1.2 or higher. Ensure your MuJoCo installation is up to date before using this tool.

    pip install --upgrade obj2mjcf

  4. Configure obj2mjcf CLI arguments

    main

    The following arguments are available when running the obj2mjcf CLI:

    ArgumentTypeDescription
    --obj-dirstrRequired. Path to a directory containing OBJ files. All files in this directory will be converted.
    --obj-filterOptional[str]Only convert OBJ files matching this regex.
    --save-mjcfboolSave the generated MJCF (XML) file.
    --compile-modelboolCompile the MJCF file to check for errors.
    --decomposeboolApproximate mesh decomposition using CoACD.
    --coacd-argsCoacdArgsArguments passed to the CoACD decomposition engine.
    --texture-resize-percentfloatResize textures to this percentage of original size (default: 1.0).
    --overwriteboolOverwrite previous run output without prompting.
    --add-free-jointboolAdd a free joint to the root body.
    --verboseboolPrint verbose output (sets logging to INFO).

  5. Configure CoACD decomposition arguments

    main

    When using the --decompose flag, you can fine-tune the CoACD (Convex Approximate Decomposition) behavior using the following parameters:

    ArgumentTypeDefaultDescription
    preprocess_resolutionint50Resolution for manifold preprocess (20~100).
    thresholdfloat0.05Concavity threshold for terminating decomposition (0.01~1).
    max_convex_hullint-1Max # convex hulls in the result, -1 for no limit.
    mcts_iterationsint100Number of search iterations in MCTS (60~2000).
    mcts_max_depthint3Max search depth in MCTS (2~7).
    mcts_nodesint20Max number of child nodes in MCTS (10~40).
    resolutionint2000Sampling resolution for Hausdorff distance calculation (1e3~1e4).
    pcaboolFalseEnable PCA pre-processing.
    seedint0Random seed used for sampling.

  6. Use the obj2mjcf CLI to convert OBJ files to MJCF

    main

    The obj2mjcf CLI processes composite Wavefront OBJ files for use in MuJoCo. It can decompose meshes into convex parts, handle MTL material files, resize textures, and generate MJCF (XML) files.

    By default, the tool creates a directory named after the OBJ file to store processed submeshes, materials, and textures.

    To use the CLI, you provide a directory containing OBJ files. You can optionally filter which files are processed using a regex, enable mesh decomposition via CoACD, or add a free joint to the root body.

    # Example usage (assuming the package is installed and entrypoint is available)
# Convert all OBJ files in 'my_models' directory, enabling CoACD decomposition
obj2mjcf --obj-dir ./my_models --decompose --save-mjcf