gerbv(1)

👑 gerbv — Gerber Viewer 💅

okay bestie, welcome to the gerbv(1) page, aka the General Commands Manual moment for the Gerber Viewer. yes it's a real manual page, yes it's long, and yes we're doing the whole thing. grab a snack 🍓

---

✨ NAME ✨

gerbv — Gerber Viewer. that's it, that's the name, she's iconic 👑

---

🦋 SYNOPSIS 🦋

gerbv [OPTIONS] [gerberfile[s]]

like. you give her options, you give her files, she renders. simple as that 💖

---

🌸 DESCRIPTION 🌸

so gerbv is a viewer for RS274-X files, which everyone just calls Gerber files because who has time. these RS274-X files get generated by all the different PCB CAD programs out there, and they're what gets used in the actual printed circuit board manufacturing process. so like, they matter fr fr.

and she doesn't stop there — gerbv also supports Excellon/NC drill files as well as XY (centroid) files produced by the program PCB (that's http://pcb.geda-project.org/). multi-talented. ate. 💅

---

💖 OPTIONS 💖

⚠️ Warning! On some platforms, which hasn't long option available, only short options are available. so like, if your platform is being difficult, the long options might just not exist. keep that in mind bestie 🫶

---

🌈 gerbv General options:

• -V, --version — prints the version number of gerbv and then exits. quick little flex ✨
• -h, --help — prints a brief usage guide and exits. the classic "help me" move 🙈
• -b<hex>, --background=<hex> — sets the background color to <hex>. <hex> is written as an html-color code, like #FF0000 for Red. 🎨
• -f<hex>, --foreground=<hex> — sets the foreground color to <hex>, also an html-color code, like #00FF00 for Green. and listen, if you also want to set the alpha (that's when you're rendering with Cairo), you can write it as an #RRGGBBAA code. use multiple -f flags to set the color for multiple layers. one per layer, queen 💅
• -l <filename>, --log=<filename> — all error messages etc are stored in a file with filename <filename>. receipts, basically 🧾
• -t <filename>, --tools=<filename> — reads Excellon tools from the file <filename>.
• -p <project filename>, --project=<project filename> — loads a stored project. please note that the project file must be stored in the same directory as the Gerber files. she's picky like that 😭

---

🎀 gerbv Export-specific options:

the following commands can be used in combination with the -x flag. so like, -x is the main character and these are her supporting cast 💅

• -B<b>, --border=<b> — sets the border around the image to <b> percent of the width and height. default <b> is 5%. 🖼️
• -D<XxY>or<R>, --dpi=<XxY>or<R> — resolution (Dots per inch) for the output bitmap. use <XxY> when you want different resolutions for the width and the height (only when compiled with Cairo as render engine). use <R> when you want the same resolution in both directions. defaults to 72 DPI in both directions. 🔍
• -T<XxYrR|X;YrR>, --translate=<XxYrR|X;YrR> — translate the image by X and Y, and rotate by R degree. use multiple -T flags to translate multiple files. the distance defaults to inches but may be changed with --units. only evaluated when exporting as RS274X or drill. ✨
• -O<XxY|X;Y>, --origin=<XxY|X;Y> — sets the lower left corner of the exported image to coordinate <XxY>. coordinates default to inches but may be changed with --units.
• -a, --antialias — use antialiasing for the generated output-bitmap. smooth edges, slay ✨
• -o <filename>, --output=<filename> — export to <filename>.
• -u<inch/mm/mil>, --units=<inch/mm/mil> — use the given unit for coordinates. defaults to inches.
• -W<WxH>, --window_inch=<WxH> — window size in inches <WxH> for the exported image.
• -w<WxH>, --window=WxH> — window size in pixels <WxH> for the exported image. autoscales to fit if no resolution is specified (note that the default 72 DPI also changes in that case). if a resolution is specified, it will clip the image to this size. 🪟
• -x<png/pdf/ps/svg/rs274x/drill>, --export=<png/pdf/ps/svg/rs274x/drill> — export to a file and set the format for the output file.

---

💜 GTK Options

• --gtk-module=MODULE — load an additional GTK module
• --g-fatal-warnings — make all warnings fatal
• --gtk-debug=FLAGS — GTK debugging flags to set
• --gtk-no-debug=FLAGS — GTK debugging flags to unset
• --gdk-debug=FLAGS — GDK debugging flags to set
• --gdk-no-debug=FLAGS — GDK debugging flags to unset
• --display=DISPLAY — X display to use
• --sync — make X call synchronous
• --no-xshm — don't use X shared memory extension
• --name=NAME — program name as used by the window manager
• --class=CLASS — program class as used by the window manager

---

🌟 GENERAL 🌟

when you start gerbv you can give her the files to be loaded right there on the command line, either as each file separated with a space, or by using wildcards. easy 💅

the user interface is graphical. simply press and drag the middle mouse button (that's the scroll wheel, bestie) and the image will pan as you move the mouse. to manipulate a layer, right-click on one of the rightmost list items. that brings up a pop-up menu where you can select what you want to do with that layer — reload file, change color, etc. you get the vibe ✨

and if you hold the mouse button over one of the rightmost buttons, a tooltip will show you the name of the file loaded on that layer. cute little peek 👀

---

🦋 ACTIVATION AND DEACTIVATION OF LAYERS 🦋

you can load several files at one time, no big deal. then you can turn the displaying of the layers on and off by clicking on one of the check boxes near the layer names. toggling, iconic 💅

you can also control this from the keyboard. press Ctrl, enter the number of the layer you want to activate/deactivate on the numerical keypad, and then release the Ctrl key. keyboard shortcuts are the moment ⌨️

---

🧚 ALIGNING OF LAYERS 🧚

you can align two layers by selected elements. select one element on each of two layers and click Align layers from the context menu. match made in heaven fr fr 🫶

---

🔍 ZOOMING 🔍

zooming can be handled by either menu choices, keypressing, or mouse scroll wheel. here's the tea:

• press z and you will zoom in
• press Shift+z (i.e. Z) and you will zoom out
• scroll wheel works if you enabled that in your X server and mapped it to button 4 and 5
• you can make the image fit by pressing f (there's also a menu alternative for this, don't worry)
• if Pan, Zoom, or Measure Tool is selected you can press the right mouse button for zoom in, and if you press Shift and the right mouse button you will zoom out

you can also do zooming by outline. select Zoom Tool, press mouse button, draw, release. the dashed line shows how the zooming will be dependent on the resolution of the window. the non-dashed outline will show what you actually selected. and if you change your mind when you've started to mark the outline, you can always abort by pressing escape. no take-backsies needed, just escape 😌

and ooh — by holding down the Shift key when you press the mouse button, you will select an area where the point you started at will be the center of your selection. main character positioning 💅

---

📏 MEASUREMENTS 📏

you can do measurements on the image displayed. select Measure Tool and the cursor changes to a plus. by using the left mouse button you can draw the lines that you want to measure. the result of the last measurement is also displayed on the statusbar. all measurements stay in the drawing until you select another Tool. and to measure the distance between elements, select two of them and switch to Measure Tool. math girlie era 🧮

the statusbar shows the current mouse position on the layer in the same coordinates as in the file. i.e. if you have (0,0) in the middle of the image in the Gerber files, the statusbar will show (0,0) at the same place. consistent, we love that 🫶

---

🌈 SUPERIMPOSING 🌈

when you load several Gerber files, you can display them "on top of each other", i.e. superimposing. the general way to display them is that upper layers cover the layers beneath, which is called copy (GTK+ terms). stacking, but make it circuit boards ✨

the other ways selectable are and, or, xor and invert. they map directly to corresponding functions in GTK. and in GTK they are described as: "For colored images, only GDK_COPY, GDK_XOR and GDK_INVERT are generally useful. For bitmaps, GDK_AND and GDK_OR are also useful." no cap 💯

---

💖 PROJECTS 💖

gerbv can also handle projects. a project consists of a bunch of loaded layers with their respective color and the background color. the easiest way to create a project is to load all the files you want into the layer you want, set all the colors etc, and do a "Save Project As...". easy peasy 🌸

you load a project either from the menu bar or by using the commandline switches -p or --project.

⚠️ currently there is a limit in that the project file must be in the same directory as the Gerber files to be loaded. yeah, she's particular about it 😭

---

🧚 SCHEME 🧚

the project files are simple Scheme programs that are interpreted by a built in Scheme interpreter. the Scheme interpreter is TinyScheme and it needs a Scheme program called init.scm to initialize itself.

the search path for init.scm is, in the following order:

1. /usr/share/gerbv/scheme
2. the directory with the executable gerbv
3. the directory gerbv was invoked from
4. finally, according to the environment variable GERBV_SCHEMEINIT

she's thorough like that 💅

---

🔧 TOOLS FILE 🔧

not every Excellon drill file is self-sufficient, bestie. some CADs produce .drd files where tools are only referenced, but never defined (like, what diameter of the tool is??). Eagle CAD is one of such CADs, and there are more since many board houses require Tools files. 🙈

a Tools file is a plain text file which you create in an editor. each line of the file describes one tool (the name and the diameter, in inches):

     T01 0.024
     T02 0.040
     ...

these are the same tools (T01 etc.) that are used in the Drill file. a standard practice with Eagle is to create an empty Tools file, run the CAM processor, and the error report tells you which tools you "forgot". then you put these tools into the file and rerun the CAM processor. the plot twist ✨

you load a tool file by using the commandline switches -t or --tools. the file can have any name you wish, but Eagle expects the file type to be .drl, so it makes sense to keep it this way. some board houses are still using CAM software from the DOS era, so you may want to exercise caution before going beyond the 8.3 naming convention. ancient tech fr 😭

when gerbv reads the Tools file it also checks that there are no duplicate definitions of tools. this does happen from time to time as you edit the file by hand, especially if you, during design, add or remove parts from the board and then have to add new tools into the Tools file.

💀 the duplicate tools are a very serious error which will stop (HOLD) your board until you fix the Tools file and maybe the Excellon file. gerbv will detect duplicate tools if they are present, and will exit immediately to indicate such a fatal error in a very obvious way. a message will also be printed to standard error.

if your Excellon file does not contain tool definitions then gerbv will preconfigure the tools by deriving the diameter of the drill bit from the tool number. this is probably not what you want, and you will see warnings printed on the console. consider yourself warned, bestie 🫶

---

🍓 PICK&PLACE FILE 🍓

supported comma separated file (CSV) with fixed order of data:

     # X,Y in mils.
     Designator,"Description","Value",X,Y,"Rotation (deg)",top/bottom

     or

     Designator,"Footprint","Mid X","Mid Y","Ref X","Ref Y",
               "Pad X","Pad Y",T/B,"Rotation","Comment"

units can be specified in the format # X,Y in mils. or as a suffix for X/Y-coordinates, i.e. ,10mil,. supported units: in, mil, cmil, dmil, km, m, dm, cm, mm, um, nm. so many units, we're spoiled honestly ✨

---

🌿 ENVIRONMENT 🌿

• GERBV_SCHEMEINIT — defines where the init.scm file is stored. used by the scheme interpreter, which is used by the project reader. 🧚

---

✨ AUTHOR ✨

okay so this whole thing was literally built by some absolute legends and we're gonna give them their flowers fr fr 💐

• Stefan Petersen (spetm at users.sourceforge.net) — overall hacker and project leader 👑 the main character, honestly. the whole vibe is his.
• Andreas Andersson (e92_aan at e.kth.se) — drill file support and general hacking 🔥 he's the reason your drill files don't just sit there being sad.
• Anders Eriksson (aenfaldor at users.sourceforge.net) — X and GTK+ ideas and hacking 🎀 the aesthetic department, the window-dressing genius, the one making the GUI not look like a potato.

like, three dudes, one gerber viewer, and a dream. iconic behaviour, no notes. 💅

---

💖 COPYRIGHT 💖

Copyright © 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Stefan Petersen

bestie, this document can be freely redistributed according to the terms of the GNU General Public License version 2.0. so yeah — share it, spread it, be free with it, that's the whole point. 🦋

just a lil reminder to respect the license terms, mwah 💋

---

and that's the whole page, bestie — you made it to the end, which is giving dedication 🫶

this lil masterpiece comes from gerbv, and the page itself is dated Jule 13, 2013 (yes that's how it's spelled, we don't question the vibes 🌸). go look at some gerber files, you earned it. 💜