Getting Started

3. Getting Started

KESE is a pure Python program. It reads the .kicad_pcb text file itself, so KiCad does not need to be installed on the machine that runs it. With the versions pinned in requirements.txt it needs Python 3.12 or later: numpy 2.5.3 requires it. On Python 3.11, install the same packages without the pinned versions (python -m pip install numpy shapely mapbox_earcut) and pip picks the last versions built for 3.11, as requirements.txt explains.

3.1 Install

git clone https://github.com/RolandThsive/KiCad-EM-Stackup-Exporter-KESE.git
cd KiCad-EM-Stackup-Exporter-KESE/Generator
python -m pip install -r requirements.txt

Generator/ holds everything KESE is made of: the program, its settings, Input/, Output/ and the tests. Every command on this page runs from there.

requirements.txt pins the versions the project was tested with (Python 3.13 on Linux). The packages are:

Package	Used for
numpy	Numerics, and the meshes: KESE builds them, writes GLB, STL, OBJ and STEP, and casts the Verifier's rays itself
shapely	All 2D geometry: tracks, pads, zones, outline, mask, silk, and the faces of every solid
mapbox_earcut	Cutting the faces into triangles (GEOS's constrained Delaunay triangulation, through shapely, where earcut's triangles do not close on the edges)

KESE writes every format itself, STEP included, with no CAD kernel. The program checks the packages before it starts and prints the pip install line to run, instead of a traceback. Only the tests that read STEP files back use OpenCascade (python -m pip install cadquery-ocp), and they skip that check without it.

Or install the project itself through pyproject.toml, with the packages unpinned (it also accepts Python 3.11, which is not tested):

python -m pip install -e .            # the kese command, the same as python run_KESE.py

-e keeps parameters/ editable in place. Input/ and Output/ stay relative to the folder the command is run from.

3.2 First Run

1. Put a board file in Input/, or use one of the three example boards already there (see Examples). Make sure every copper zone in the board has been filled in KiCad (press B) and the file saved: KESE takes the zone fill polygons stored in the file, and a zone without a stored fill produces no copper.

2. Run the default export: every board in Input/, simulation mode, one GLB in metres with the board centred at the origin:

   python run_KESE.py

3. Read the terminal. For each board it prints the KiCad format version, the number of copper layers, the mode, any warnings, and the output folder:

   hdi_module: KiCad format 20221018, 6 copper layers, mode simulation
     -> Output/hdi_module/simulation_GLB  (hdi_module.glb, materials.json)  in 0m 12s
   pcie_card: KiCad format 20221018, 4 copper layers, mode simulation
     -> Output/pcie_card/simulation_GLB  (pcie_card.glb, materials.json)  in 0m 14s
   rf_module: KiCad format 20221018, 4 copper layers, mode simulation
     -> Output/rf_module/simulation_GLB  (rf_module.glb, materials.json)  in 0m 16s
   

4. Open Output/<board>/simulation_GLB/report.txt. It lists the stack-up heights, every item that was read, every item that was skipped and why (hidden text and text on layers that are not drawn are left out without a count), and the triangle count of every part. See Project Output Organization.

5. Bring the model into your solver or viewer: Choosing An Export and KiCad And Solver Compatibility.

3.3 All Commands

python run_KESE.py                                   # every .kicad_pcb in Input/, settings from parameters/
python run_KESE.py Input/board.kicad_pcb             # one board (several paths are allowed)
python run_KESE.py board.kicad_pcb --mode visual     # simulation (solids) or visual (surface for viewers)
python run_KESE.py board.kicad_pcb --format glb step stl obj --set Run.UNITS=mm   # mm for CAD and solvers
python run_KESE.py board.kicad_pcb --for hfss        # a preset: hfss, cst, openems or viewer
python run_KESE.py board.kicad_pcb --verify          # run the Verifier; results in report.txt
python run_KESE.py board.kicad_pcb --out /some/dir   # output root other than Output/
python run_KESE.py board.kicad_pcb --set Copper.VIA_WALL_MM=0.02 --set Board.BOARD_THICKNESS_MM=0.8
python run_KESE.py --version

Option	Meaning
boards	One or more .kicad_pcb paths. With none, every board in Run.INPUT_DIR (Input/) is exported.
--mode	simulation or visual. Default: Run.MODE.
--format	Any of glb, stl, obj, step, several at once. Default: Run.FILE_FORMAT (["glb"]). Visual mode allows only glb and obj.
--for	Applies a preset from Run.PRESETS before any --set: hfss, cst, openems, viewer. See Choosing An Export.
--verify	Runs the Verifier after the model files are written (2 to 4 s on the example boards). See Checks, Errors And Warnings.
--out	Output root. Default: Run.OUTPUT_DIR (Output/).
--set Module.NAME=value	Overrides one parameter for this run. Module is the short name of the parameter file (Run, Board, Copper, SolderMask, Silkscreen, Finish, Geometry, Color). The value is parsed as a Python literal (0.02, True); anything that does not parse, such as net, is kept as a string. Quote a list for the shell, as in --set 'Run.FILE_FORMAT=["glb","stl"]': unquoted, the shell strips its inner quotes and the run stops. An unknown name stops the run.
--version	Prints kese 2.2.0.

Every preset, --set, --mode, --format and --verify is applied as an override of the parameters (--mode sets Run.MODE, --format sets Run.FILE_FORMAT, --verify sets Run.VERIFY), so all of them are listed on the first line of the run's parameters.txt and show in its values. Only --out is not recorded there; the run folder's path shows it.

Note

Run the program from the Generator/ folder: Input/ and Output/ (Run.INPUT_DIR, Run.OUTPUT_DIR) are relative to the folder the command is run from. The exit code is 0 when every board succeeded and 1 when any board failed; with a single board the full traceback is shown, with several the failing board is reported and the run continues.

3.4 Next

• Decide what to export for your solver: Choosing An Export.
• Set your fabricator's thicknesses: Parameter Reference.
• See what the model contains: Board and Copper And Traces.
• See what happens in a run, stage by stage: Working Principle.

Previous	Next
Contents	Project Capabilities