Package: gingerbread
🍪 GingerbreadGingerbreadis a set of Python utilities used byWinterbloomto create decorative printed circuit boards (PCBs), such as the ones we used a front panels:Gingerbread consists of three utilities:converthelps convert designs created withAffinity Designerto KiCAD PCB files.fancytextis used to generate beautiful text labels for KiCAD PCBs.traceis a re-implementation of KiCAD's "Image Converter" program (bitmap2component) as a Python library and command line tool to enable automation.NOTE: This tool isextremelytailored to Winterbloom's needs. It's not perfect, it's not universal, and it probably won't work the way you think it will. Because of this, it comes with no warranty and no promise of support- again,we won't be providing any free support for this.That said, you're welcome to try it out, learn from it, take code from it, and give us feedback or evencontributeif you'd like. If you'd like to pay us to add a feature or support some use case,reach out.There are severalsimilar projectsthat might fit your use case better.InstallationPresently we've only ever tested on macOS and Linux. It might be tricky to get working regardless of platform, and it probably doesn't work on Windows except under WSL. There's aDocker option, but it has some drawbacks.macOSYou'll needhomebrewand a few dependencies:brewinstallcairopangopangocairopotraceYou'll also need Python 3.10 or later. Install usingpip:python3-mpipinstallgingerbreadLinux / WSLAt the time of writing, Ubuntu 22.04 or later is your best bet. If you want to use Debian, you'll need to buildPython 3.10or later and pango 1.50 or later, since the current versions are behind. Thisshouldwork under WSL (Windows Subsystem for Linux), just be sure to use Ubuntu 22.04 or later.You'll need at least the following system packages:sudoaptinstall-y\build-essential\cmake\libpotrace-dev\libvips-dev\libcairo2\libpango1.0-0\libpangocairo-1.0-0\libvips42Once you have the requisites installed, you can install Gingerbread:python3-mpipinstall--usergingerbreadDockerThere's a rough Docker version of Gingerbread that you can use if all else fails. From our limited testing,convertworks okay (although a bit slower), butfancytextdoes not work at all.To use the Docker version, clone this repo:gitclonehttps://github.com/wntrblm/Gingerbread.gitcdGingerbreadBuild the image- we don't publish it to Dockerhub because it's experimental:dockerbuild-tgingerbread.You can now run Gingerbread using Docker. You'll need to pass the current working directory as a volume so that Gingerbread can read and write files. You can test this out on the included example file:cdexample
dockerrun--rm-v"$PWD":/workdirgingerbread-mgingerbread.convertexample.svgUsing convertconvertis designed to convert designs created withAffinity Designerto KiCAD PCB files.convertrequires a bit of work to set up, but once working you can rapidly iterate on your design.There's an example in the./exampledirectory, including the sourceafdesignfile, the exportedsvg, and the generatedkicad_pcb. It might be useful to look at the example as you work through these docs.Page settingsIt'shighly recommendedto set up your document in Affinity to use millimeters and to have a DPI of2540:Why that specific DPI? Well, 2540 DPI happens to be 1000 dots-per-mm, which helpfully avoids rounding issues when exporting the design from Affinity and when converting the outline and drills. You can use other DPIs, just be sure to tellconvertusing the--dpiflag.Creating an outlineThe outline should be drawn on a layer namedEdge.Cuts(orEdgeCuts) in Affinity.converthandlesEdge.Cutsin a specific way to make sure that there is a 1-to-1 match between the size and units in Affinity and KiCAD. This approach can't handle as many complex edge cases as the rasterization approach used by the graphic layers, but as long as your paths have been converted to curves it should handle them well.Edge.Cutscan also contain "cut-outs"- closed paths within the overall board shape.The example file has a complex outline with four internal cut-outs.Graphics layersNon-transparent areas on layersF.SilkS,B.SilkS,F.Cu, andB.Cuin Affinity are converted as-is to the respective layers in KiCAD.F.MaskandB.Maskare "inverted" like they are in KiCAD, meaning that non-transparent areas indicate where toremovethe soldermask. For all of these layers,convertworks by rasterizing the individual layers to black and white images, re-vectorizing usingtrace, and plotting the results as a KiCAD footprint.The example file has graphics on theF.SilkS,F.Cu, andF.Masklayers.DrillsItems on theDrillslayer are handled seperately as well.convertwalks through all of the shapes in theDrillslayer and convertsonlycircles to drills. This is again done to preserve position and size between Affinity and KiCAD.The example file has a single drill in the center.Exporting the designWhen exporting the design to an SVG, click theMorebutton and setup the export parameters. Make sure thatRasterizeis set to "Nothing",Export text as curvesis checked, andFlatten transformsis checked.You can save this as a preset to avoid having to change these every time you export.Running convertOnce the design is exported as an SVG, you can runconvertto turn it into a KiCAD PCB:python3-mgingerbread.convertdesign.svgconvertwill report details about the converted PCB. Double-check this output to make sure that things match up with what you expect. For example. running convert on the example design shows:convert: Converting board outline
convert: Outline converted: overall board size is 100.00 mm x 100.00 mm (10000.00 mm²).
convert: Converting drills
convert: Drills converted: 1
convert: Converting graphic layers
convert: F.SilkS    converted
convert: B.SilkS    not found
convert: F.Cu       converted
convert: B.Cu       not found
convert: F.Mask     converted
convert: B.Mask     not found
convert: Writing...
convert: Written to example.kicad_pcb 💜converthas a several options for customizing the conversion process and the output. Runpython3 -m gingerbread.convert --helpto get a full list of options.Using fancytextfancytextis intended to be relatively easy to use. It's a terminal application that copies the resulting label to your clipboard.The most basic example is:python3-mgingerbread.fancytext"example"Which will generate a simple text label:This rudimentary example isn't much more useful than KiCAD's own text facilities, but Fancytext gives you much more control.You can change various aspects of how the text is rendered:python3-mgingerbread.fancytext--font"Pluto"--italic--size3"example"You can runpython3 -m gingerbread.fancytext --helpto get a complete list of options.Fancytext has another fancy trick- outlines. You can use outlines to call more attention to your text labels. There are various outline styles, starting with--outline-stroke:python3-mgingerbread.fancytext--outline-stroke0.5"example"There's also the more eye-catching--outline-fill:python3-mgingerbread.fancytext--outline-fill--outline-stroke0.2"example"The shape of the end caps can be changed by wrapping your text in[],||,<>,(),//, or\\, and you can mix and match:python3-mgingerbread.fancytext--outline-fill--outline-stroke0.2"/example>"There arelotsof options for customizing the look of these labels. You can runpython3 -m gingerbread.fancytext --helpto get a complete list of options. As an example, we like using these settings for our labels:python3-mgingerbread.fancytext--font"Space Mono"--bold--italic--stroke0.1--padding00--outline-stroke0.2--outline-fill"fancytext"Which ends up looking like this:Using tracetraceis fairly straightforward compared to the other tools in Gingerbread. Provide it with an image and it will provide you with a KiCAD footprint:python3-mgingerbread.tracefootprint.pngThere's several options fortrace, including the important--dpioption which tellstracethe physical size that the footprint should be. Runpython3 -m gingerbread.trace --helpsee all options.Similar projectsProjects similar to Gingerbread'sconvert:svg2shenzhenis an Inkscape-based tool for creating PCBs and footprints from SVGs. Gingerbread shares a lot in common with svg2shenzhen's inner workings, but svg2shenzhen is much more broadly used and handles more use cases.Gerbolyzerenders both vector and raster artwork onto existing Gerber files. This is a very different approach than the one taken by Gingerbread and svg2shenzhen and can produce some incredible results through its grayscale emulation.PCBmodEis a circuit board design program built on Inkscape.Projects similar to Fancytext:KiBuzzardcreates beautiful text labels. Fancytext is actually inspired by and inherits many stylistic choices from Buzzard. However, they differ in their implementation - Buzzard is vector graphics all the way through, whereas Fancytext has an intermediary rasterization step. KiBuzzard is also a KiCAD plugin with a GUI whereas Fancytext is (presently) a terminal application.AcknowledgementsGingerbread sits on the shoulders of the incredible work of other open source projects:cairosvgis used byconvertto rasterize SVG files.cairo(viacairocffi) is used by bothconvertandfancytextto render 2d graphics.pango(viapangocffi) is used byfancytextto layout text.svgpathtoolsis used byconvertto process the board outline.richis used throughout for pretty terminal output.pyperclipis used to copy stuff to your clipboard.numpyis used extensively to shuffle data around between various libraries.vips(viapyvips) is used for processing images efficiently.potrace(viapotracecffi) is used intracefor converting raster images to polygons.Gdsdkand the underlyingClipperlibrary are used to wrangle polygons and punch holes in them.Additionally, information and ideas from the following projects were used when building Gingerbread:svg2shenzhen's overall strategy for converting SVGs to KiCAD PCBs served as the starting point for Gingerbread'sconvert.pangocairocffi's testswere used as a starting point when implementingfancytext's text layout.librsvg's text.rswas used as a reference for implementingfancytext's text layout.KiCAD'sbitmap2componentwas used as a reference for implementingtraceand for testing its output.KiCAD'skimathwas used as a reference for implementingtrace's polygon handling.KiCAD'sS-Expression reference.ContributingBecause this tool is so specifically tailored to Winterbloom's workflow, we aren't really expecting a lot of outside contributions. However, if you'd like to contribute please file an issue or reach out to us before you start writing code, so we can make sure it's something that'll be beneficial for all of us. :)LicenseGingerbread is published under theMIT License