3D Models

The 3D viewer provides photorealistic visualization of your PCB design, helping verify component placement, clearances, and mechanical fit. KiCad supports STEP and VRML model formats through a caching system for optimal performance.

Overview

The 3D system is built around the S3D_CACHE class (source/3d-viewer/3d_cache/3d_cache.h:54), which manages model loading, caching, and rendering. Each footprint can reference multiple 3D models.

3D Architecture

S3D_CACHE Class

// Source: 3d-viewer/3d_cache/3d_cache.h:54
class S3D_CACHE : public PROJECT::_ELEM
{
    PROJECT* m_project;
    S3D_PLUGIN_MANAGER* m_pluginManager;  // Model format handlers
    FILENAME_RESOLVER* m_resolver;        // Path resolution
    
    // Load 3D model from file or cache
    SCENEGRAPH* Load( const wxString& aModelFile,
                     const wxString& aBasePath,
                     std::list<EMBEDDED_FILES*>* aEmbeddedFilesStack );
};

Model Association

Footprints reference 3D models:

// Source: pcbnew/footprint.h:107
struct FP_3DMODEL
{
    wxString m_Filename;      // Path to STEP or WRL file
    VECTOR3D m_Scale;         // X, Y, Z scaling factors
    VECTOR3D m_Rotation;      // X, Y, Z rotation (degrees)
    VECTOR3D m_Offset;        // X, Y, Z position offset (mm)
    double   m_Opacity;       // Transparency (0.0 - 1.0)
    bool     m_Show;          // Visibility toggle
};

Each footprint can have multiple 3D models. For example, a connector might have separate models for the housing and pins.

Supported Formats

STEP (.step, .stp)
VRML (.wrl)

Recommended format for mechanical design:

Industry standard CAD format
Precise dimensional data
Supports complex assemblies
Best for mechanical integration
Can be exported for enclosure design

// Loaded via OpenCascade plugin
// Plugin: libs/kiplatform/3d_oce/

Legacy 3D format:

Older KiCad versions used primarily VRML
Smaller file sizes
Faster loading
Limited precision vs STEP
Good for visualization only

// Native VRML support
// Plugin: 3d-viewer/3d_cache/sg/

Use STEP models when available. They provide better accuracy and integrate with mechanical CAD tools.

Adding 3D Models to Footprints

Open Footprint Editor

Launch the Footprint Editor and load your footprint.

Open 3D Model Settings

Go to Footprint Properties → 3D Models tab.

Add Model

Click Add 3D Model and browse to the model file:

# Standard library location
${KICAD8_3DMODEL_DIR}/Package_SO.3dshapes/SOIC-8_3.9x4.9mm_P1.27mm.step

# Project-specific model
${KIPRJMOD}/3d_models/custom_connector.step

Adjust Position

Set scale, rotation, and offset:

m_Scale: { 1.0, 1.0, 1.0 }       // Default: no scaling
m_Rotation: { 0.0, 0.0, 0.0 }    // Degrees around X, Y, Z
m_Offset: { 0.0, 0.0, 0.0 }      // mm offset from footprint origin

STEP models often require rotation to align with KiCad’s coordinate system. Common adjustments:

X: 0° or 180° (flip)
Y: 0° (usually)
Z: 0°, 90°, 180°, or 270° (orientation)

Preview in 3D Viewer

Open the 3D Viewer (Alt+3 or View → 3D Viewer) to verify alignment.

3D Model Organization

Standard Library Structure

KiCad’s 3D model library is organized by package type:

${KICAD8_3DMODEL_DIR}/
├── Capacitor_SMD.3dshapes/
│   ├── C_0402_1005Metric.step
│   ├── C_0603_1608Metric.step
│   └── C_0805_2012Metric.step
├── Package_SO.3dshapes/
│   ├── SOIC-8_3.9x4.9mm_P1.27mm.step
│   └── TSSOP-16_4.4x5mm_P0.65mm.step
├── Resistor_SMD.3dshapes/
└── Connector_USB.3dshapes/

Custom Model Paths

Add project-specific models:

# Add to KiCad configuration
export KICAD8_3DMODEL_DIR="/path/to/models"

Path Resolution

The filename resolver handles path variables:

// Source: 3d-viewer/3d_cache/3d_cache.h:80
class FILENAME_RESOLVER
{
    // Resolves:
    // - ${KICAD8_3DMODEL_DIR} → KiCad library path
    // - ${KIPRJMOD} → Project directory
    // - Relative paths from footprint library
    // - Absolute paths
};

3D Viewer Features

Rendering Options

Realistic Mode

Photorealistic rendering with materials and lighting

Raytrace Mode

Advanced rendering with shadows and reflections

Orthographic

Flat projection without perspective

Perspective

3D perspective view

Layer Visibility

Control which board layers are shown:

Copper layers: F.Cu, B.Cu, Inner layers
Silkscreen: F.SilkS, B.SilkS
Solder mask: F.Mask, B.Mask (with color/transparency)
Substrate: PCB material color and thickness
3D models: Component visibility

Export Options

Export 3D board for mechanical design:

STEP Export
VRML Export
Screenshot

File → Export → STEPOptions:

Include board body
Include components
Include virtual components
Coordinate origin (center or bottom-left)
Units (mm or inch)

Use for:

Enclosure design in CAD software
Mechanical fit verification
Manufacturing documentation

Plugin System

The 3D cache uses plugins to load different formats:

// Source: 3d-viewer/3d_cache/3d_plugin_manager.h
class S3D_PLUGIN_MANAGER
{
    std::list<S3DMODEL*> m_Plugins;  // Available format handlers
    
    // Load model using appropriate plugin
    SCENEGRAPH* LoadModel( const wxString& aFileName );
};

Plugins handle:

STEP/STP (OpenCascade)
VRML/WRL (native)
IDF (legacy)

Performance Optimization

Model Caching

The cache stores loaded models in memory:

struct S3D_CACHE_ENTRY
{
    wxString modelFile;           // Source file path
    SCENEGRAPH* sceneGraph;       // Loaded 3D data
    std::time_t modTime;          // File modification time
};

std::map<wxString, S3D_CACHE_ENTRY*> m_CacheMap;

Models are cached until the file is modified. Large boards with many components benefit significantly from caching.

Simplify Complex Models

For better performance:

Use simplified models for common parts
Remove internal details not visible in assembly
Reduce polygon count for large models
Use bounding boxes for mechanical parts

Embedded 3D Models

Embed models directly in footprints:

class FOOTPRINT : public EMBEDDED_FILES
{
    // Can embed STEP/VRML files in footprint
    // Useful for custom/proprietary parts
    // Ensures model availability across systems
};

Embedded models increase file size significantly. Use for critical custom parts only.

Creating Custom 3D Models

Model Requirements

Choose CAD Software

Use any CAD tool that exports STEP:

FreeCAD (free, open source)
Fusion 360 (free for hobbyists)
SolidWorks, Inventor (professional)
Blender (with STEP addon)

Model to Scale

Create model in millimeters at 1:1 scale.Match footprint dimensions exactly:

Pad locations
Pin pitch
Body size
Height above board

Set Origin

Place model origin at:

Footprint origin (typically pin 1 or center)
Board surface (Z=0)

This minimizes required offset/rotation in KiCad.

Export as STEP

Save as STEP AP214 or AP203 format.Avoid excessive detail:

Remove threads from screws
Simplify rounded edges
Combine small features

Test in KiCad

Add model to footprint and verify:

Correct orientation
Accurate dimensions
Acceptable file size
Reasonable load time

Board Materials and Colors

Customize board appearance: Preferences → Preferences → 3D Viewer → Board Colors

Solder mask: Green, blue, red, black, white
Silkscreen: White, black
Copper: Copper, gold (ENIG), silver (HASL)
Substrate: FR4 tan/green

Best Practices

Use Standard Library First

Check KiCad’s 3D model library before creating custom models. Many common packages are already available.

Organize Custom Models

Store project-specific models in a dedicated directory:

project/
├── project.kicad_pcb
├── 3d_models/
│   ├── custom_connector.step
│   └── special_ic.step
└── footprints.pretty/

Version Control Models

Track 3D models in version control alongside PCB files. Use Git LFS for large STEP files.

Document Model Sources

Keep notes on where custom models came from:

Manufacturer website
Created in-house
Modified from library Include datasheet links in footprint description.

Test Before Manufacturing

Use 3D view to verify:

Component heights for enclosure fit
Connector alignment for mating parts
No mechanical collisions
Proper polarity orientation

Source Code References

// 3D model caching and loading
// Location: source/3d-viewer/3d_cache/3d_cache.h:54
class S3D_CACHE : public PROJECT::_ELEM

Next Steps

PCB Layout

Design boards with 3D visualization

Footprint Libraries

Add models to footprints

Manufacturing Output

Export 3D for mechanical integration

Getting Started

Core Applications

Design Workflow

Advanced Features

Overview

3D Architecture

S3D_CACHE Class

Model Association

Supported Formats

Adding 3D Models to Footprints

3D Model Organization

Standard Library Structure

Custom Model Paths

Path Resolution

3D Viewer Features

Rendering Options

Realistic Mode

Raytrace Mode

Orthographic

Perspective

Layer Visibility

Export Options

Plugin System

Performance Optimization

Model Caching

Simplify Complex Models

Embedded 3D Models

Creating Custom 3D Models

Model Requirements

Board Materials and Colors

Best Practices

Source Code References

Next Steps

PCB Layout

Footprint Libraries

Manufacturing Output

Build docs developers (and LLMs) love

Getting Started

Core Applications

Design Workflow

Advanced Features

​Overview

​3D Architecture

​S3D_CACHE Class

​Model Association

​Supported Formats

​Adding 3D Models to Footprints

​3D Model Organization

​Standard Library Structure

​Custom Model Paths

​Path Resolution

​3D Viewer Features

​Rendering Options

Realistic Mode

Raytrace Mode

Orthographic

Perspective

​Layer Visibility

​Export Options

​Plugin System

​Performance Optimization

​Model Caching

​Simplify Complex Models

​Embedded 3D Models

​Creating Custom 3D Models

​Model Requirements

​Board Materials and Colors

​Best Practices

​Source Code References

​Next Steps

PCB Layout

Footprint Libraries

Manufacturing Output

Build docs developers (and LLMs) love

Overview

3D Architecture

S3D_CACHE Class

Model Association

Supported Formats

Adding 3D Models to Footprints

3D Model Organization

Standard Library Structure

Custom Model Paths

Path Resolution

3D Viewer Features

Rendering Options

Layer Visibility

Export Options

Plugin System

Performance Optimization

Model Caching

Simplify Complex Models

Embedded 3D Models

Creating Custom 3D Models

Model Requirements

Board Materials and Colors

Best Practices

Source Code References

Next Steps