How to use the command 'assimp' (with examples)

The Assimp command-line tool is a powerful client for the Open Asset Import Library, which is a versatile and extensive library used for importing a wide variety of 3D model formats. With Assimp, users can convert 3D files between different formats, retrieve detailed information about 3D files, and tailor conversions using custom parameters. The command supports over 40 import formats and several export formats, making it a valuable tool for working with 3D assets across various applications and software.

Use case 1: List all supported import formats

Code:

assimp listext

Motivation: To understand which 3D file formats can be imported using the Assimp tool, it is essential for users to have a comprehensive list of supported formats. This information helps users plan their workflows, ensuring that their desired 3D assets are compatible with Assimp. Knowing the available import formats also aids in troubleshooting any potential file compatibility issues.

Explanation:

• assimp: This is the base command to execute the Assimp tool.
• listext: This is a subcommand used with Assimp to list all supported import formats. It doesn’t take additional arguments and directly outputs the formats supported.

Example output:

Supported import formats: 
- Collada (.dae)
- Blender 3D (.blend)
- Autodesk FBX (.fbx)
- 3DS Max 3DS (.3ds), and many others.

Use case 2: List all supported export formats

Code:

assimp listexport

Motivation: When converting a 3D model to another format, knowing the list of supported export formats helps users determine the possible output options. This is particularly useful for designers and developers looking to integrate 3D models into different platforms or software that require specific file formats.

Explanation:

• assimp: This base command runs the Assimp tool.
• listexport: This subcommand outputs a list of all supported formats that Assimp can export to, allowing users to plan their export procedures effectively.

Example output:

Supported export formats:
- Wavefront OBJ (.obj)
- Stereolithography (.stl)
- Collada (.dae), and several others.

Use case 3: Convert a file to one of the supported output formats, using the default parameters

Code:

assimp export input_file.stl output_file.obj

Motivation: Converting a 3D model from one file format to another can be necessary for compatibility with different software. This use case demonstrates how easily Assimp can perform this task using default parameters, streamlining the process for users who do not require custom settings.

Explanation:

• assimp: The base command initiating the Assimp tool.
• export: A subcommand that starts the conversion process.
• input_file.stl: This is the path to the input file in STL format, which is set for conversion.
• output_file.obj: This is the desired output file path and format (OBJ in this case) after conversion.

Example output:

Conversion successful: 'input_file.stl' to 'output_file.obj' using default settings.

Use case 4: Convert a file using custom parameters

Code:

assimp export input_file.stl output_file.obj parameters

Motivation: There are instances where the default conversion parameters of Assimp may not meet the specific needs of a project. In such cases, utilizing custom parameters allows users to fine-tune the conversion process to accommodate unique requirements such as scaling, rotation, or other transformations.

Explanation:

• assimp: Executes the Assimp command-line tool.
• export: Initiates the file conversion process.
• input_file.stl: Path to the source 3D model file to be converted.
• output_file.obj: The target path and file format for conversion.
• parameters: Placeholder for any custom parameters defined by the user. The specific parameters should be referenced from the dox_cmd.h file in Assimp’s source code.

Example output:

Conversion completed with custom parameters applied: 'input_file.stl' to 'output_file.obj'.

Use case 5: Display a summary of a 3D file’s contents

Code:

assimp info path/to/file

Motivation: Understanding the structure and content of a 3D file is crucial for both analysis and debugging. This summary provides insight into the model’s structure, including the number of vertices, faces, materials, and other vital information without the need for a graphical 3D editor.

Explanation:

• assimp: The command used to invoke the Assimp tool.
• info: This subcommand generates a comprehensive summary of the specified 3D file.
• path/to/file: The specific file path of the 3D model for which the information is needed.

Example output:

File: path/to/file
Number of vertices: 1024
Number of faces: 512
Materials: 3
Textures: 2

Use case 6: Display help

Code:

assimp help

Motivation: The help command is invaluable for users new to the Assimp command-line tool or those who need a quick refresher on available commands and usage syntax. It provides guidance on using the tool efficiently and hints at additional functionality that might not be immediately apparent.

Explanation:

• assimp: This initiates the command-line client for Assimp.
• help: A subcommand that provides detailed help and documentation for all available commands and options within Assimp.

Example output:

Usage: assimp <command> <args>
Commands:
  listext           List all supported import formats
  listexport        List all supported export formats
  export            Convert a file to another format
  info              Show information about a 3D file
  help              Show this help message

Use case 7: Display help for a specific subcommand

Code:

assimp subcommand --help

Motivation: Finding detailed information about a specific subcommand within Assimp can be crucial when learning its full range of functionalities and options. This use case helps users obtain targeted help for a particular task they wish to perform with the tool.

Explanation:

• assimp: The command to invoke the Assimp tool.
• subcommand: Placeholder to specify the subcommand for which help is needed (e.g., export, info).
• --help: An option used to display help information specific to the indicated subcommand.

Example output:

Usage of 'export' subcommand:
  assimp export <input-format> <output-format> [options]
Options include:
  -option1  Description
  -option2  Description

Conclusion:

The Assimp command-line tool offers extensive functionality for managing and converting various 3D model formats. By mastering these use cases, users can leverage Assimp to streamline their workflow, ensure compatibility between different 3D formats, and exploit the tool’s flexible conversion and analysis capabilities. Understanding these basic operations establishes a foundation for exploring the more advanced features available in Assimp, making it a go-to solution for professionals working with 3D assets.