No way to set the 3D model of a placed footprint: 65 board tools, none with a model property

[triglav-modular]

A footprint instance in a .kicad_pcb can carry its own (model …) block, and KiCad's Footprint Properties → 3D Models dialog edits exactly that. Konnect has no equivalent: a wrong or missing 3D model on a placed footprint cannot be corrected through any tool, on a closed board or over IPC.

Version: v0.7.0 · KiCad 10.0.5 · macOS

What I checked

With eager_toolsets: true so all tools are advertised, dumped tools/list (209 tools) and searched every input schema:

• 65 tools take a board argument. None has a model-shaped property (model/3d/step/wrl).
• edit_component's schema is exactly {board, reference, value}.
• Only three tools mention 3D models at all:
  • set_footprint_models — takes footprint_path, a .kicad_mod library file, not a board
  • export_3d — export only
  • set_footprint_metadata — description/tags/attributes, no models

So the library side is well covered and the board side has no route at all.

Why it comes up

The board instance and the library can legitimately disagree, and in practice they do: a model gets assigned by hand in the dialog, the library footprint has none, and the board is then the only place the wrong path exists. Renders are wrong while fab output is fine, so it survives review. Fixing it means the GUI dialog, once per board, for every affected instance.

Relationship to #231

#231 is not a duplicate of this, but it overlaps and may be the better fix — please close this if you disagree.

#231 proposes update_footprints_from_library, whose scope includes refreshing library-owned 3D models onto placed footprints. That would resolve the common case via the library: correct the library footprint, refresh, done. It does not provide a way to set a model on one placed instance deliberately, which is what the KiCad dialog does.

If #231's refresh is considered the sanctioned path, then the gap worth recording here is narrower and still real: today, with #231 unimplemented, there is no route at all — not through the library either, because nothing propagates a corrected library model onto already-placed footprints.

Suggested shape

Either a model field on a placed-footprint editor (edit_component gaining models, matching set_footprint_models's mode + models shape), or an explicit set_placed_footprint_models(board, reference, mode, models). Closed-board would be the more useful of the two, since this is a file-level property that needs no live KiCad.

[neusse]

We will take this one, but I want to wait until the related footprint/IPC work has settled before starting the implementation.

The issue is narrower now than when it was opened:

• Add live Update Footprints from Library support #231 is complete and provides the common library-owned path: correct the library footprint, then run update_footprints_from_library to propagate its 3D models to placed instances.
• update_footprints_from_library refuses most official library footprints: fp_text user is unsupported #331 / PR fix(pcb): preserve library user text during refresh #348 is removing the current official-library compatibility blocker in that refresh path.
• PR refactor(ipc): share the IPC classification gate and board test mock #334 refactors the shared IPC classification gate and board-test mock. This tool should be built on that settled gate rather than adding another transport path in parallel.

So I propose waiting for #348 and #334 to merge (including any maintainer-requested follow-up changes), then branching from the updated main. There is no reason to wait for every unrelated open PR.

Remaining scope

What remains is a deliberate per-board override: set the 3D model(s) of one placed footprint without modifying its linked library definition.

I recommend a dedicated pcb_components tool rather than expanding edit_component:

set_placed_footprint_models

Suggested input:

{
  "board": "design.kicad_pcb",
  "reference": "U3",
  "mode": "append",
  "models": [
    {
      "path": "${KICAD10_3DMODEL_DIR}/Package_DIP.3dshapes/DIP-16_W7.62mm.wrl",
      "offset": { "x": 0, "y": 0, "z": 0 },
      "scale": { "x": 1, "y": 1, "z": 1 },
      "rotate": { "x": 0, "y": 0, "z": 0 },
      "visible": true,
      "opacity": 1.0
    }
  ]
}

Modes should match the existing library-side set_footprint_models behavior:

• append — retain current models and add the requested models
• replace — remove the current models and install the requested list
• delete — remove every model from that placed instance

path, offset, scale, and rotate should remain compatible with the existing library tool. The placed-footprint tool should additionally expose visible and opacity, since KiCad IPC's Footprint3DModel already represents both and the Footprint Properties dialog permits those instance-level settings.

Live KiCad implementation

A 3D model is a nested Footprint3DModel child of FootprintInstance.definition.items; it has no independent KIID. The safe IPC operation is therefore:

1. Verify that the explicitly requested board is the active KiCad board.
2. Fetch exactly one FootprintInstance matching reference; reject missing or duplicate references.
3. Clone the complete live footprint instance.
4. Change only its Footprint3DModel children according to mode.
5. Submit the complete parent footprint through UpdateItems inside one KiCad undo transaction.
6. Read the footprint back and compare its model list with the requested result before reporting success.

Pads, pad nets, graphics, fields, library ID, placement, side, rotation, lock state, symbol path, overrides, and the footprint KIID must remain byte-for-byte/protobuf-equivalent to the pre-edit instance.

Closed-board implementation

This should also support the useful closed-board case through the shared IPC/file-write gate:

1. If KiCad owns the requested board, use the IPC path above.
2. If IPC is genuinely unreachable, read the saved .kicad_pcb consistently.
3. Find exactly one top-level (footprint ...) whose Reference is the requested reference.
4. Append, replace, or delete only that footprint's direct (model ...) children.
5. Reparse and validate the complete board.
6. Write with write_atomic_if_unchanged so a concurrent edit becomes a structured conflict.

If KiCad answers but rejects the request, or has another board active, the tool must fail closed and must not fall back to editing the file behind KiCad.

The existing library-side model parser/validator/serializer should be extracted or exposed for reuse rather than introducing a second interpretation of model transforms and path quoting.

Validation and expected responses

Reject before mutation:

• empty or NUL-containing paths
• non-finite transform values
• non-finite opacity or opacity outside 0.0..=1.0
• missing/ambiguous footprint references
• empty models for append or replace
• non-empty models for delete
• a stale closed-board file revision
• an active-board mismatch or any reachable KiCad rejection

Report at least the transport (ipc or file), mode, reference, previous model count, resulting model count, and the resulting normalized model list. An already-satisfied request should return a no-op rather than creating an empty undo entry or rewriting the board.

Tests and documentation

The PR should include:

• schema and argument-validation tests
• pure append/replace/delete mutation tests
• preservation tests proving that non-model footprint state is untouched
• missing/duplicate-reference and revision-conflict tests
• mock IPC coverage proving one parent-footprint UpdateItems call in one undo transaction
• an ignored disposable live-KiCad PCB test that applies a model, reads it back, saves the board, and verifies it again
• pcb_components registry/tool-count and tool-directory.md updates
• a short KiCad integration note explaining live IPC versus the atomic closed-board fallback

This should remain one focused PR. It requires no KiCad plugin, protobuf, or KiCad API changes; the necessary typed model representation and parent-footprint update machinery already exist. Once #348 and #334 are merged, we will recheck main, update this plan if their final interfaces differ, and start the implementation with a failing regression test.

[ncolomer]

Concrete repro from a recent PCB design project (Konnect 0.11.0, KiCad 10.0): needed to attach a second, independent 3D model to an already-placed footprint instance (a header socket that already carried its own correct model), so a different component's STEP file (a module that plugs into that header, contributing no copper of its own) would render in the 3D viewer at the right position/orientation.

No Konnect tool exposes this — had to compute the offset/rotation transform by hand (matrix composition between the old footprint's placement and the new host footprint's placement) and apply it via raw pcbnew:

new_model = pcbnew.FP_3DMODEL()
new_model.m_Filename = "${KIPRJMOD}/3dmodels/some-module.step"
new_model.m_Offset = pcbnew.VECTOR3D(14.1675, 5.87, 8.8)
new_model.m_Rotation = pcbnew.VECTOR3D(-90.0, 0.0, 90.0)
new_model.m_Scale = pcbnew.VECTOR3D(1.0, 1.0, 1.0)
hdr1.Add3DModel(new_model)   # footprint.Models() is a plain list; Add3DModel appends

Worth noting for whichever tool eventually closes this: a footprint's model list supports multiple independent entries (this was relied on here — the host footprint kept its own original model plus the newly-added one), so the fix should be an "add/list/remove one model entry" API, not just "set the single model," to match what the GUI's 3D Models tab already allows.