# pcb-stackup API

<a name="pcbStackup"></a>

## `pcbStackup(layers, [options], [done])`

The main export of pcb-stackup. Renders all individual layers, then builds a stackup render from those layers.

```js
const pcbStackup = require('pcb-stackup')

pcbStackup(layers, options)
  .then(stackup => {
    // do something with stackup
  })
  .catch(error => console.error(error))
```

### arguments

| Param     | Type                     | Description                           |
| --------- | ------------------------ | ------------------------------------- |
| layers    | [`Array<Layer>`](#Layer) | Layers to generate the stackup render |
| [options] | [`Options`](#Options)    | Optional render options               |
| [done]    | [`Callback`](#Callback)  | Optional done callback                |

### returns

If the `done` parameter is not used, `pcbStackup` will return a [`Promise<Stackup>`](#Stackup). Otherwise returns `undefined` and calls `done` when finished.

## types

<a name="Layer"></a>

### `Layer`

Object representing a single Gerber or drill file (PCB layer).

| Property   | Type                                                  | Description                                                                              |
| ---------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| gerber     | `string` &#124; `Buffer` &#124; [`ReadableStream`][2] | Gerber data for the layer. Required if `layer.converter` is not used                     |
| filename   | `string`                                              | Filename to infer the layer's type and side. Required if `side` and `type` are not used  |
| type       | `string`                                              | [whats-that-gerber layer type][3]. Required if `layer.filename` is not used              |
| side       | `string`                                              | [whats-that-gerber layer side][3]. Required if `layer.filename` is not used              |
| options    | `object`                                              | Optional [gerber-to-svg options][4]                                                      |
| converter  | [`gerber-to-svg converter`][6]                        | **Finished** [gerber-to-svg][4] converter stream. Required if `layer.gerber` is not used |
| externalId | `string`                                              | Optional. See [pcb-stackup-core docs][8] for usage                                       |

If both `layer.converter` and `layer.gerber` are specified, `layer.converter` will take precedence and the layer will **not** be re-rendered by gerber-to-svg.

<a name="Options"></a>

### `Options`

Render options object. All properties are optional.

| Property       | Type      | Default                        | Description                                                        |
| -------------- | --------- | ------------------------------ | ------------------------------------------------------------------ |
| id             | `string`  | `xid.random()`                 | Unique identifier, generated by [@tracespace/xml-id][7] by default |
| color          | `object`  | [see pcb-stackup-core docs][1] | Colors to apply to the board render by layer type                  |
| attributes     | `object`  | `{}`                           | Additional attributes to apply to SVGs                             |
| outlineGapFill | `number`  | `0.00011`                      | Threshold in `mm` for filling gaps in the board outline            |
| useOutline     | `boolean` | `true`                         | Use the outline layer to generate the board shape                  |

Any additional properties will be passed directly to `pcb-stackup-core`. [See pcb-stackup-core docs][1] for more details and additional options.

<a name="Done"></a>

### `Callback`

The done callback is a function that is called when the stackup is done rendering

```js
pcbStackup(layers, (error, stackup) => {
  if (error) return console.error(error)
  // do something with stackup
})
```

| Param   | Type                  | Description                    |
| ------- | --------------------- | ------------------------------ |
| error   | `Error` &#124; `null` | Error if something goes wrong. |
| stackup | [`Stackup`](#Stackup) | Stackup render and other data  |

<a name="Stackup"></a>

### `Stackup`

Stackup data object, including board renders

| Property       | Type                     | Description                                    |
| -------------- | ------------------------ | ---------------------------------------------- |
| id             | `string`                 | Stackup ID (from `options.id` or generated)    |
| color          | `object`                 | Actual value used for `options.color`          |
| attributes     | `object`                 | Actual value used for `options.attributes`     |
| useOutline     | `boolean`                | Actual value used for `options.useOutline`     |
| outlineGapFill | `number`                 | Actual value used for `options.outlineGapFill` |
| top            | `object`                 | Top render data from pcb-stackup-core          |
| top.svg        | `string`                 | Top SVG string                                 |
| bottom         | `object`                 | Bottom render data from pcb-stackup-core       |
| bottom.svg     | `string`                 | Bottom SVG string                              |
| layers         | [`Array<Layer>`](#Layer) | Processed layers                               |

See the [pcb-stackup-core docs][5] for the full shape of the `Stackup.top` and `Stackup.bottom` objects, as well as any additional properties that may be present on the `Stackup` object.

`Stackup.layers` may be passed back to [pcbStackup](#pcbStackup) for an inexpensive re-render, if necessary.

[1]: ../pcb-stackup-core/README.md#options
[2]: https://nodejs.org/api/stream.html#stream_readable_streams
[3]: ../whats-that-gerber/README.md#layer-types-and-names
[4]: ../gerber-to-svg/API.md#options
[5]: ../pcb-stackup-core/README.md#usage
[6]: ../gerber-to-svg/API.md#streaming-api
[7]: ../xml-id
[8]: ../pcb-stackup-core/README.md#using-externally-defined-layers