== Footprint Editor - Creating and Editing Footprints

=== Footprint Editor Overview

The footprint editor is used for editing and creating PCB footprints.
This includes:

* Adding and removing pads.

* Changing pad properties (shape, layer), for individual pads or for
  all the pads in a footprint.

* Adding and editing graphic elements (contours, text).

* Editing fields (value, reference, etc.).

* Editing the associated documentation (description, keywords).

=== Footprint Elements

A footprint is the physical representation (footprint) of the part to
be inserted in the PCB and it must  be linked to the relative
component in your schematic. Each footprint includes three different
elements:

* The pads.

* Graphical contours and text.

* Fields.

In addition, a number of other parameters must be correctly defined if
the auto-placement function will be used. The same holds for the
generation of auto-insertion files.

==== Pads

Two pad properties are important:

* Geometry (shape, layers, drill holes).
* The pad number, which is constituted by up to four alphanumeric
  characters. Thus, the following are all valid pad numbers: 1, 45 and
  9999, but also AA56 and ANOD. The pad number must be identical to that
  of the corresponding pin number in the schematic, because it defines
  the matching pin and pad numbers that Pcbnew links pins and pads with.

==== Contours

Graphical contours are used to draw the physical shape of the
footprint. Several different types of contour are available: lines,
circles, arcs, and text. Contours have no electrical significance,
they are simply graphical aids.

==== Fields

These are text elements associated with a footprint. Two are obligatory
and always present: the reference field and the value field. These
are automatically read and updated by Pcbnew when a netlist is read
during the loading of footprints into your board. The reference is
replaced by the appropriate schematic reference (U1, IC3, etc.). The
value is replaced by the value of the corresponding part in the
schematic (47K, 74LS02, etc.). Other fields can be added and these
will behave like graphical text.

=== Starting Footprint Editor and Selecting a Footprint to Edit

Footprint Editor can be started in two ways:

* Directly via the image:images/icons/module_editor.png[] icon from the main
  toolbar of Pcbnew. This allows the creation or modification of a footprint in
  the library.
* Double-clicking a footprint will launch the 'Footprint Properties' menu,
  which offers a 'Go to Footprint Editor' button. If this option is used,
  the footprint from the board will be loaded into the editor, for
  modification or for saving.

=== Footprint Editor Toolbars

Calling Footprint Editor will launch a new window that looks like this:

image::images/Modedit_main_window.png[scaledwidth="80%"]

==== Edit Toolbar (right-hand side)

This toolbar contains tools for:

* Placing pads.
* Adding graphic elements (contours, text).
* Positioning the anchor.
* Deleting elements.

The specific functions are the following:

[cols="1,4"]
|======
| image:images/icons/cursor.png[]
| No tool.
| image:images/icons/pad.png[]
| Add pads.
| image:images/icons/add_polygon.png[]
| Draw line segments and polygons.
| image:images/icons/add_circle.png[]
| Draw circles.
| image:images/icons/add_arc.png[]
| Draw circular arcs.
| image:images/icons/text.png[]
| Add graphical text (fields are not managed by this tool).
| image:images/icons/anchor.png[]
| Position the footprint anchor.
| image:images/icons/delete.png[]
| Delete elements.
| image:images/icons/grid_select_axis.png[]
| Grid origin. (grid offset). Useful for placement of pads.
The grid origin can be put on a given location (the first pad to place),
and after the grid size can be set to the pad pitch.
Placing pads is therefore very easy
|======

==== Display Toolbar (left-hand side)

These tools manage the display options in Footprint Editor:

[cols="1,4"]
|======
| image:images/icons/grid.png[]
| Display the grid.
| image:images/icons/polar_coord.png[]
| Display polar coordinates.
| image:images/icons/unit_mm.png[] image:images/icons/unit_inch.png[]
| Use units of mm or inch
| image:images/icons/cursor_shape.png[]
| Toggle cursor crosshair shape
| image:images/icons/pad_sketch.png[]
| Display pad in outline mode.
| image:images/icons/text_sketch.png[]
| Display text in outline mode.
| image:images/icons/show_mod_edge.png[]
| Display contours in outline mode.
| image:images/icons/contrast_mode.png[]
| Toggle high-contrast mode
|======

=== Context Menus

The right mouse button calls up menus that depend upon the element
beneath the cursor.

The context menu for editing footprint parameters:

image::images/Modedit_context_menu_module_parameters.png[scaledwidth="60%"]

The context menu for editing pads:

image::images/Modedit_context_menu_pads.png[scaledwidth="40%"]

The context menu for editing graphic elements:

image::images/Modedit_context_menu_graphics.png[scaledwidth="40%"]


=== Footprint Properties Dialog

This dialog can be launched when the cursor is over a footprint by
clicking on the right mouse button and then selecting 'Edit Footprint'.

image::images/Modedit_module_properties_dialog.png[scaledwidth="60%"]

The dialog can be used to define the main footprint parameters.

=== Creating a New Footprint

A new footprint can be created via the button
image:images/icons/new_footprint.png[]. The name of the new footprint
will be requested. This will be the name by which the footprint will be
identified in the library.

This text also serves as the footprint value, which is ultimately
replaced by the real value (100 µF_16 V, 100 Ω_0.5 W, ...).

The new footprint will require:

* Contours (and possibly graphic text).

* Pads.

* A value (hidden text that is replaced by the true value when used).

Alternative method:

When a new footprint is similar to an existing footprint in a library or a
circuit board, an alternative and quicker method of creating the new
footprint is as follows:

* Load the similar footprint (image:images/icons/load_module_lib.png[],
  image:images/icons/load_module_board.png[] or
  image:images/icons/import_module.png[]).
* Modify the "Footprint Name in Library" field in order to generate a new identifier (name).
* Edit and save the new footprint.

=== Adding and Editing Pads

Once a footprint has been created, pads can be added, deleted or
modified. Modification of pads can be local, affecting only the pad
under the cursor, or global, affecting all pads of the footprint.

==== Adding Pads

Select the image:images/icons/pad.png[] icon from the right hand
toolbar. Pads can be added by clicking in the desired position with
the left mouse button. Pad properties are predefined in the pad
properties menu.

Do not forget to enter the pad number.

==== Setting Pad Properties

This can be done in three different ways:

* Selecting the image:images/icons/options_pad.png[] icon from the
  horizontal toolbar.
* Clicking on an existing pad and selecting 'Edit Pad'. The pad's
  settings can then be edited.
* Clicking on an existing pad and selecting 'Export Pad Settings'.
  In this case, the geometrical properties of the selected pad will
  become the default pad properties.

In the first two cases, the following dialog window will be displayed:

image::images/Modedit_pad_properties_dialog.png[scaledwidth="80%"]

Care should be taken to define correctly the layers to which the pad
will belong. In particular, although copper layers are easy to
define, the management of non-copper layers (solder mask, solder
pads...) is equally important for circuit manufacture and
documentation.

The Pad Type selector triggers an automatic selection of layers that
is generally sufficient.

===== Rectangular Pads

For SMD footprints of the VQFP/PQFP type which have rectangular pads on
all four sides (both horizontal and vertical) it is recommended to
use just one shape (for example, a horizontal rectangle) and to
place it with different orientations (0 for horizontal and 90
degrees for vertical). Global resizing of pads can then be done in a
single operation.

===== Rotate Pads

Rotations of -90 or -180 are only required for trapezoidal pads used
in microwave footprints.

===== Non-plated Through Hole Pads

Pads can be defined as Non-Plated Through Hole pads (NPTH pads).

These pads must be defined on one or all copper layers (obviously,
the hole exists on all copper layers).

This requirement allows you to define specific clearance parameters
( for instance clearance for a screw).

When the pad hole size is the same as the pad size,  for a round or
oval pad,  this pad is NOT plotted on copper layers in GERBER files.

These pads are used for mechanical purposes, therefore no pad name
or net name is allowed. A connection to a net is not possible.

===== Offset Parameter

Pad 3 has an offset Y = 15 mils:

image::images/Modedit_pad_offset_example.png[scaledwidth="80%"]

===== Delta Parameter (trapezoidal pads)

Pad 1 has its parameter Delta X  = 10 mils

image::images/Modedit_pad_delta_example.png[scaledwidth="58%"]

==== Setting Clearances for Solder Mask and Solder Paste Layers

When defining pads containing copper layers, KiCad creates solder mask
and solder paste layers based on a fixed clearance and/or a ratio of
the pad geometry.  The non-zero settings used to calculate the final
pad size is based on the following order of precedence:

* Pad setting
* Footprint setting
* Global setting

[NOTE]
====
The solder mask pad shape is usually bigger than the pad itself. So the
clearance value is positive. The solder paste mask pad shape is usually
smaller than the pad itself. So the clearance value is negative.
====

===== Solder Paste Settings

Two settings are used to calculate the solder paste aperture:

* A fixed clearance setting.
* A percentage of the pad size.

The the final value is the product of the ratio setting and the clearance
setting.

==== Pads Not on Copper Layers

There is second method for creating pads that do not have any copper layers
defined. These pads are commonly referred to as aperture pads and can be
use to create custom apertures not based on the outline of a copper pad
geometry. This method was introduced in version 5.0.0-rc2. Pads defined
without any copper layers ignore the global and footprint level settings
and only use the pad level settings.

[WARNING]
====
Pads without copper layers defined prior to version 5.0.0-rc2 were plotted
using precedence defined above with the global and footprint settings.
Adjustments will have to be made for any boards designed prior to this
version in order to achieve the same output plots.
====

Footprint level settings:

image::images/Modedit_footprint_level_pad_settings.png[scaledwidth="50%"]

Pad level settings:

image::images/Modedit_pad_level_pad_settings.png[scaledwidth="70%"]

=== Fields Properties

There are at least two fields: reference and value.

Their parameters (attribute, size, width) must be updated. You can
access the dialog box from the pop-up menu, by double clicking on
the field, or by the footprint properties dialog box:

image::images/Modedit_footprint_text_properties.png[scaledwidth="50%"]

=== Automatic Placement of a Footprint

If the user wishes to exploit the full capabilities of the
auto-placement functions, it is necessary to define the allowed
orientations of the footprint (Footprint Properties dialog).

image::images/Modedit_module_autoplace_settings.png[scaledwidth="50%"]

Usually, rotation of 180 degrees is permitted for resistors,
non-polarized capacitors and other symmetrical elements.

Some footprints (small transistors, for example) are often permitted to
rotate by +/- 90 or 180 degrees. By default, a new footprint will have
its rotation permissions set to zero. This can be adjusted according
to the following rule:

A value of 0 makes rotation impossible, 10 allows it completely, and
any intermediate value represents a limited rotation. For example, a
resistor might have a permission of 10 to rotate 180 degrees
(unrestrained) and a permission of 5 for a +/- 90 degree rotation
(allowed, but discouraged).

=== Attributes

The attributes window is the following:

image::images/Modedit_module_attributes.png[scaledwidth="30%"]

* Normal is the standard attribute.
* Normal+Insert indicates that the footprint must appear in the automatic
  insertion file (for automatic insertion machines). This attribute is
  most useful for surface mount components (SMDs).
* Virtual indicates that a component is directly formed by the circuit
  board. Examples would be edge connectors or inductors created by a
  particular track shape (as sometimes seen in microwave footprints).

=== Documenting Footprints in a Library

It is strongly recommended to document newly created footprints, in
order to facilitate their rapid and accurate retrieval. Who is able
to recall the multiple pin-out variants of a TO92 footprint?

The Footprint Properties dialog offers a simple and yet powerful means
for documentation generation.

image::images/Modedit_module_properties_documentation_fields.png[scaledwidth="40%"]

This menu allows:

* The entry of a comment line (description).
* Multiple keywords.

The comment line is displayed with the component list in CvPcb and
in the footprint selection menus in Pcbnew. The keywords can be used to
restrict searches to those parts possessing the given keywords.

Thus, while using the load footprint command (icon  in the right-hand
toolbar in Pcbnew), it is possible to type the text `=TO220` into
the dialog box to have Pcbnew display a list of the footprints
possessing the keyword `TO220`

=== 3-Dimensional Visualization

A footprint may be associated with a file containing a three-dimensional
representation of the component. In order to associate a footprint with
a model file, select the _3D Settings_ tab as shown below.

[[img-Modedit_module_3d_options]]
.3D Model selection interface
image::images/Modedit_module_3d_options.png[scaledwidth="60%"]

The buttons on the right have the following functions:

* *Add 3D Shape* shows a 3D file selection dialog and creates a
  new model entry for the component.
* *Remove 3D Shape* deletes the selected model entry.
* *Edit Filename* shows a text editor for manual entry of
  the model file name.
* *Configure Paths* shows a configuration dialog which
  allows the user to edit the list of path aliases and
  alias values.

The _3D Settings_ tab contains a panel with a preview of the
selected model and the scale, offset, and rotation data
for the model.

Scale values are useful for visualization
formats such as VRML1, VRML2, and X3D. Since the model may
have been produced by any number of VRML/X3D editors or
exporters and VRML does not enforce a unit of length for
the models, users can enter an appropriate scale value to
ensure that the model appears as it should within the 3DViewer.
Some users employ a simple VRML box as a generic model for
components and select scale values so that the box
has the correct size to represent the component. For Mechanical
CAD (MCAD) models the scale values should be left at unity.
MCAD formats always specify a unit length and any exporters
which make use of MCAD data formats will ignore the scale values.
However the 3DViewer will always apply the scale values; if
scale values other than unity are used with MCAD models, the
output of the 3DViewer will differ from any exported MCAD
models such as IDF.

Offset and Rotation values are typically required to align
a 3D model with a footprint. Due to differences in 3D modeling
software as well as differences in how users construct a
model, in the vast majority of cases it is necessary for
users to enter Offset and Rotation values to achieve the
desired positioning of a 3D model. The Rotation values are
given in degrees and are applied successively in the order
ZYX; the convention used is that a positive angle results
in a clockwise rotation of the part when viewing from the
positive position of the axis towards the origin.

KiCad supports 3D model formats via a plugin system and
support is provided for the visual model formats VRML1,
VRML2, and X3D as well as the MCAD format IDF. The MCAD
formats IGES and STEP are supported via the OCE Plugin
which requires a suitable version of the OpenCascade or
OpenCascade Community Edition (OCE) software.


==== 3D Model Paths
In the past KiCad used a fixed path to a directory of
3D models and later relied on the _KISYS3DMOD_ environment
variable to specify the location of the model directory.
Other base directories for models could be specified by
using additional environment variables. The current
version of KiCad has a specialized _alias_ system for
handling 3D model names. The aim of the new file name
management system (filename resolution system)
is to provide a scheme which is compatible with earlier
versions of KiCad while offering a more flexible mechanism
for specifying 3D model file names and improving the
ability to share project files.

Due to the requirement to support previous schemes while
offering a flexible new scheme for finding 3D models, there
are two distinct methods for specifying base search paths
for 3D models.

In order to maintain the legibility of the _kicad_pcb_ and
_pretty_ data files, KiCad prefers to use filenames which
have been shortened via the use of environment variables
(old method) or aliases (new method). Since setting environment
variables can be cumbersome especially on GUI-based
operating systems, the environment variable scheme for
supporting model search paths has been extended to make
use of KiCad's existing internally defined _Path Configuration_
dialog.  This dialog is available via the _Preferences->Configure Paths_
menu and is shown below. Setting additional paths within this
dialog will extend the search paths used to find 3D model files.
The dialog does not actually set environment variables but the
filename resolution system acts as if it does; in cases where
an actual environment variable with the same name is
defined, the environment variable's value overrides any
internally defined values. File names relative to these
defined variables begin with _${MY_ENV_VAR}_ where _MY_ENV_VAR_
is a variable defined via the _Path Configuration_ dialog or
an actual environment variable.

[[img-Modedit_internal_path_config]]
.KiCad Path Configuration dialog
image::images/Modedit_internal_path_config.png[scaledwidth="60%"]

The newer scheme to support shortened file names is the
_alias_ system. In this system a path begins with the
string _:my alias:_ where _my alias_ is a text string which
is preferably chosen to be short while also being significant
to the user; for example an alias to a directory containing the
official KiCad models may have an alias _Official Models_ while
your personal model collection may have an alias _My Models_.
The aliases may be set up by clicking on the *Configure Paths*
button within the *3D Settings* tab shown previously. The
alias configuration dialog is shown below.

[[img-Modedit_alias_path_config]]
.KiCad Alias Configuration dialog
image::images/Modedit_alias_path_config.png[scaledwidth="60%"]

3D model files can be selected by clicking *Add 3D Shape* to
display the 3D Model Browser shown below. The model browser
provides a 3D preview, file filter, and a drop-down path
selector which contains the current list of search paths
defined via environment variables or aliases. Depending on
the model size and complexity it may take a few seconds for
a model to be displayed when it is selected. In an extreme case
a BGA package model which was used during testing took around
12 seconds to display.

[[img-Modedit_3D_file_browser]]
.KiCad 3D File Browser
image::images/Modedit_3D_file_browser.png[scaledwidth="60%"]


=== Saving a Footprint into the Active Library

The save command (modification of the file of the active library) is
activated by the image:images/icons/save_library.png[] button.

If a footprint of the same name exists (an older version), it will
be overwritten. Because it is important to be able to have confidence
in the library footprints, it is worth double-checking the footprint
for errors before saving.

Before saving, it is also recommended to change the reference or value
of the footprint to be equal to the library name of the footprint.

=== Saving a footprint to the board

If the edited footprint comes from the current board, the button
image:images/icons/update_module_board.png[] will update this
footprint on the board.
