Missing models when importing kicad_pcb with models using relative path to footprint library.

[leoheck]

Hi @easyw

I am importing a kicad_pcb, but some models are not being imported.

See:

I have a custom lib called MyLib.
And, my footprints set 3d models with a relative path.

Right now, it seems this functionality is not implemented in KicadSteUpMod workbench yet.

My projects use local settings for custom libs which use these files inside the project to set libraries path (sym-lib-table and fp-lib-table), but this config can also be global in the system (user settings).

Here is where this functionality was mentioned recently. https://forum.kicad.info/t/how-to-have-a-3d-model-path-relative-to-a-custom-footprint-path/69943/4?u=leoheck

This is how these files look inside, and if the kicad_pcb does not have the whole path to the footprint and then to the 3d model, the path can be extracted from here:

➜ cat fp_lib_table
(fp_lib_table
  (lib (name "MyLib")(type "KiCad")(uri "${KIPRJMOD}/libs/MyLib/footprints/MyLib.pretty")(options "")(descr "MyLib footprints."))
)

➜ cat sym_lib_table
(sym_lib_table
  (lib (name "MyLib")(type "KiCad")(uri "${KIPRJMOD}/libs/MyLib/symbols/MyLib.kicad_symdir")(options "")(descr "MyLib symbols."))
)

It would be very nice if the workbench could load models that use relative paths.
Thank you.

[easyw]

kSU should already (since a lot time ago) load relative paths.
Do you have a text file with the relative path you can show me? (Just the part of the kicad_pcb file that contains the 3D model would suffice?)
I'm not sure if this might be related to your Dropbox path and the version of FC you're using... (version not specified in this report)
the best option, as has already been suggested in many threads, would be to attach a minimal kicad_pcb file that exhibits the error, compressed into a zip file.

[leoheck]

Hi, I can provide a sample file/project later today. Thanks for replying. I am not on my computer right now.

[leoheck]

It should not be related to Dropbox.

But I do use the AppImages for FreeCAD and KiCad, and sometimes they require a bit of tweaking. Also, I’ve had FreeCAD installed for a long time, so some old settings may be playing a role in this.

[leoheck]

I created a sample project with my custom lib with a single part.

sample_board_and_lib_relative_footprint_paths.zip

These are my settings.

This is the message I get when importing the board.kicad_pcb

The board, inside Kicad is this

The footprint has this 3d model.
The path of the 3d model is relative to the footprint.

[easyw]

Missing models when importing kicad_pcb with models using relative paths

1. the title is wrong... you need to change to "models using relative path to footprint library" which is something completely different
2. unzipping your testing project doesn't help: on windoze no 3d model is appearing... so:
   a) your project misses some setting
   or
   b) this option doesn't work on kicad windoze
   EDIT:
   I tested it also on Appimage and it doesn't work either on linux
   -> a) your project misses some setting

[leoheck]

Hi @easyw,

To use the sample project, you have to unzip the package and keep both folders (Board and Lib) in the same folder.
In other words, unzipping it should just work.

Perhaps the .zip may be messing up the symlink for some reason.

There is a symlink to the custom library inside the Board.
Symbol and footprint libraries are set using sym-lib-table and fp-lib-table, which point to the custom library that is symlinked.

➜ ls -l ./Board/libs/
lrwxrwxrwx+1 lheck lheck    9 Sep  5 08:38 MYLIB -> ../../Lib

Please check whether the contents of the symlinked library show the Lib folders, which are these 3 folders.

➜ ls ./Board/libs/MYLIB
3dmodels  footprints  symbols

If the symlink is not working, then it is possible to fix it by:

1. Fixing the symlink if it is broken.
2. OR, updating the sym-lib-table and fp-lib-table by replacing the symlink path with the lib path.

To fix the symlink, inside the libs folder of the Board project (/Board/libs), do this:

ln -sf ../../Lib MYLIB 

OR, to fix the *-lib-table, inside the Board project, do this:

sed -i "s|libs/MYLIB|../Lib|g" fp-lib-table sym-lib-table

I am attaching a package with the fix #2 above.
sample_board_and_lib_relative_footprint_paths_NO_SYMLINK.zip

[leoheck]

The sample project was created using Kicad 10.

[leoheck]

Hi @easyw, the PR above is a suggestion on how to improve the 3d models detection.

[leoheck]

The PR was generated entirely with Claude Fable 5. This is the output if you would like to have more context.

Here's the fix — a 109-line patch to kicadStepUptools.py (apply with git apply fp-lib-relative-3dmodels.patch, or just drop in the patched file).

Why it fails today: Load_models() resolves model paths for aliases, ${HOME}, ${KIPRJMOD}, ${KISYS3DMOD}, generic env vars, and paths relative to the .kicad_pcb file, then falls back to findModelPath() which only searches the configured 3D prefix paths. KiCad's footprint editor additionally resolves bare relative paths against the footprint's own .pretty directory — and the workbench had no way to do that because the .kicad_pcb only carries the library nickname (MyLib:MyFp), and StepUp never read fp-lib-table to turn that nickname into a directory.

What the patch does, in three parts:

DrawPCB() — each entry in the PCB_Models list gains a new field at index 14: the footprint's lib id (m[0], e.g. "MyLib:R_0805"). It's appended after md_hide (index 13), so all existing positional indexing is untouched.
New helpers getFpLibDir() / parseFpLibTables() (just above Load_models) — resolves a nickname to its library directory by parsing, in precedence order, the project fp-lib-table next to the pcb file, then the global tables from the KiCad config dirs (%APPDATA%\kicad<ver> on Windows, ~/Library/Preferences/kicad/ on macOS, ~/.config/kicad/ on Linux, newest version first, KiCad 5 flat layout included). URIs get ${KIPRJMOD} expanded to the pcb directory, then OS env vars, then KiCad path variables read from kicad_common.json (so ${KICAD8_FOOTPRINT_DIR}-style URIs work even though those aren't real OS env vars). Results are cached per project so the tables are parsed once per board load, not once per model.
Load_models() — when building path_list for findModelPath(), the resolved library directory is inserted at the front. Since findModelPath joins each search path with the (still relative) model path and probes all the extension variants (stpZ/step/stp/iges/igs, both cases), this transparently handles MyModel.step, subfolders like 3dmodels/foo.step, and parent-relative paths like ../3dmodels/foo.step. Everything is wrapped in try/except so a malformed table can never break board loading — worst case you get a console warning and the old behavior.

I verified the resolver against a mock project (project-local ${KIPRJMOD} lib, global lib via kicad_common.json path var, unknown nicknames) and confirmed m[0] returns the lib id with their sexp parser. Resolution order is preserved: paths relative to the pcb still win if they exist (matching KiCad's project-dir-first behavior), and the lib dir only adds a new place to look, so nothing that loads today will resolve differently.

Two caveats worth knowing: I couldn't run the full workbench inside FreeCAD here, so do a smoke test with your board; and if your setup relies on nonstandard KiCad config locations (e.g. KICAD_CONFIG_HOME, or Flatpak/Snap sandboxed paths — the README's known mount-bind issue applies here too), the global table lookup could be extended to honor that env var. For a board where the project fp-lib-table defines the lib, none of that matters.

If this works for you, it'd make a nice PR upstream — easyw is quite responsive on that repo.

[leoheck]

I just tested it with my real project. It works just fine.
Not a single 3d model is missing; really good.

11:58:11  added 135 model(s)

[leoheck]

Does this solution also look for footprints in the global footprint setup?

Yes. parseFpLibTables() reads both tables:

Project table first: /fp-lib-table — its entries win when a nickname exists in both (same precedence KiCad uses).
Global tables: it then scans the KiCad config directories — %APPDATA%\kicad\ on Windows, ~/Library/Preferences/kicad/ on macOS, ~/.config/kicad/ on Linux — including the versioned subfolders KiCad 6+ uses (.../kicad/9.0/fp-lib-table, 8.0, etc., newest first) and the flat layout KiCad 5 used. Any fp-lib-table found there gets merged in, first-found wins per nickname.

So a footprint from a library that's only registered in your global footprint library setup (Preferences → Manage Footprint Libraries → Global Libraries tab) resolves too, as long as its URI can be expanded. For expansion it tries ${KIPRJMOD}, then real OS environment variables, then KiCad's own path variables read from kicad_common.json in those same config dirs — which is where things like ${KICAD9_FOOTPRINT_DIR} or any custom path variable you added under Preferences → Configure Paths actually live, since KiCad doesn't export them to the OS environment.

You saw this in the test I ran: GlobalLib was defined only in ~/.config/kicad/8.0/fp-lib-table with a ${KICAD8_FOOTPRINT_DIR} URI, and it resolved to /usr/share/kicad/footprints/GlobalLib.pretty via the path var from kicad_common.json.

Two edge cases where the global lookup could miss: if you've set KICAD_CONFIG_HOME to relocate KiCad's config, the patch doesn't check that custom location (easy to add — prepend os.getenv('KICAD_CONFIG_HOME') to the cfg_dirs list); and under sandboxed FreeCAD (Snap/Flatpak on Linux) the host's ~/.config/kicad may simply not be visible from inside the sandbox — that's the same mount-bind limitation the README already notes for 3D model paths generally. One more subtlety: if you have several KiCad versions installed with different global tables, the newest version's table takes precedence for any nickname defined in both, which is almost always what you want but worth knowing.