add-3d
The kilm add-3d
command registers a directory containing 3D models (like .step
or .wrl
files) with KiLM. This is typically used for libraries stored outside the main symbol/footprint Git repository, such as in cloud-synced folders.
kilm add-3d [OPTIONS]
Options
Section titled “Options”Option | Description | Default | Example |
---|---|---|---|
--directory DIRECTORY | Path to the directory containing 3D models | Current working directory | --directory ~/kicad/3d-models |
--name TEXT | Custom name for this 3D library entry | Auto-generated from directory name | --name standard-3d-lib |
--description TEXT | Description for this 3D library | None | --description "My custom STEP models" |
--env-var TEXT | Custom KiCad environment variable name | Auto-generated (e.g., KICAD_3D_STANDARD_3D_LIB ) | --env-var KICAD_USER_3DMOD |
--no-env-var | Don’t assign an environment variable to this library | False | --no-env-var |
--force | Overwrite existing metadata file if present | False | --force |
--help | Show help message and exit | - | --help |
Behavior
Section titled “Behavior”The command performs the following main actions:
-
Creates/Updates Metadata: Creates or modifies
.kilm_cloud_metadata
in the target directory containing:- Library name, description, and associated environment variable
- Count of detected model files
- Last updated timestamp
-
Updates Global Configuration: Adds library entry (type
cloud
) to mainconfig.yaml
-
Verification: Scans directory for common 3D model file extensions (
.step
,.stp
,.wrl
,.wings
) -
Environment Variable Setup: Prepares environment variable for use with
kilm setup
Examples
Section titled “Examples”Basic Usage
Section titled “Basic Usage”Add a 3D library with automatic configuration:
# Add directory with default settingskilm add-3d --directory ~/my-3d-parts --description "Custom 3D mechanical parts"
Add current directory as 3D library:
cd ~/kicad-3d-modelskilm add-3d --name my-3d-models --description "Project-specific 3D models"
Advanced Configuration
Section titled “Advanced Configuration”Add with custom environment variable:
kilm add-3d --directory /opt/kicad/packages3d \ --name kicad-official-3d \ --env-var KICAD_OFFICIAL_3D \ --description "KiCad Official 3D Models"
Add without environment variable:
kilm add-3d --directory ~/local-3d-models \ --name local-models \ --no-env-var \ --description "Local 3D models (no env var needed)"
Force overwrite existing metadata:
kilm add-3d --directory ~/existing-3d-lib \ --force \ --name updated-3d-lib \ --description "Updated description"
Error Handling
Section titled “Error Handling”Common Issues
Section titled “Common Issues”- No 3D models found: Command will warn but allow continuation
- Directory not found: Command will fail with clear error message
- Permission denied: Command will fail if unable to write metadata file
- Existing metadata: Use
--force
to overwrite or command will update existing file
Error Examples
Section titled “Error Examples”# Directory doesn't existkilm add-3d --directory /nonexistent/path# Error: Directory '/nonexistent/path' does not exist
# No write permissionskilm add-3d --directory /readonly/directory# Error: Permission denied when creating metadata file
Integration with Other Commands
Section titled “Integration with Other Commands”Workflow Integration
Section titled “Workflow Integration”After adding 3D libraries, you typically need to run kilm setup
to make them available in KiCad:
# Add 3D librarykilm add-3d --directory ~/my-3d-models --name my-models
# Configure KiCad to use itkilm setup --all-libraries
# Verify configurationkilm status
File Extensions Supported
Section titled “File Extensions Supported”The command automatically detects these 3D model file extensions:
.step
- STEP files.stp
- STEP files (alternative extension).wrl
- VRML files.wings
- Wings 3D files
- Environment Variables: Use
kilm setup
to activate the configured environment variables in KiCad - Cross-platform: Works on Windows, macOS, and Linux with appropriate path handling
- Metadata Storage: Library information is stored in
.kilm_cloud_metadata
in the target directory - KiCad Integration: Requires
kilm setup
to complete the integration with KiCad