move_footprint
Move a KiCad PCB footprint by reference to new X/Y coordinates, rotation, or layer, updating placement while keeping pads, texts, and graphics intact.
Instructions
Move a footprint to a new position.
A move rewrites the footprint's own position and nothing of its pads, texts
or graphics, which KiCad stores relative to the footprint. The zones it owns
and a KiCad 10 footprint's points are stored in board coordinates, so they
move by the same delta, as KiCad's FOOTPRINT::SetPosition moves them
(pcbnew/footprint.cpp:2553-2584 at 9.0.8). A rotation turns the footprint to
that angle as KiCad's own rotate turns it: every pad and text turns by the
change from the angle it had, its zones and points turn about it, and a
keep-upright text that would read upside down is turned half a turn with its
justification mirrored, so it stays readable on the same side of its anchor.
Angles are written as KiCad writes them: the footprint's between -180 and 180
and left out at 0. Off the quarter turns the result reads as KiCad's turn
without matching pcbnew's save byte for byte: footprint-relative coordinates
stay as written where pcbnew re-derives them through two RotatePoint roundings,
an fp_rect stays where pcbnew writes an fp_poly, and arc mid points stay as
written. A footprint carrying what this tool does not move with it
(a dimension, image, table or barcode, or a child no KiCad it knows reads) is
refused and nothing is written. The keep-out warning reads keepouts as
check_placement does.
Args:
reference: Reference designator (e.g. "R1")
x: New X position
y: New Y position
rotation: The footprint's angle after the move, in degrees (None keeps the
current one). An angle the footprint already has (270 for one at -90,
360 for one at 0) changes nothing and leaves the file byte-identical,
where KiCad's footprint properties dialog would still re-run its
rotate by a full turn. inf and nan are refused and nothing is written.
layer: F.Cu or B.Cu (empty keeps the side; anything else is refused). The
other side flips the footprint as KiCad's own flip does (FOOTPRINT::Flip,
pcbnew/footprint.cpp:2491-2550 at 9.0.8): pads, texts and graphics
mirror, their layers go to their opposites on this board (user layers it
pairs included), a text's mirror toggles on side-specific layers only,
zones and points mirror about the footprint with their layers, and 3D
models stay as they are. With a rotation the flip comes first, so
rotation names the angle the footprint ends at. Refused, with nothing
written: a text box, a pad's own padstack, KiCad 10's back drills, and on
a board of four or more copper layers an item (a zone included) on inner
copper that does not name every inner layer, which KiCad 9 and 10 flip
apart.
pcb_path: Path to .kicad_pcb file. Optional; omit to use the configured default.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| layer | No | ||
| pcb_path | No | ||
| rotation | No | ||
| reference | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |