##master-page:HelpTemplate
##master-date:Unknown-Date
#acl HaefnerLabGroup:read,write,delete,revert,admin All:read
#format wiki
#language en
= Inkscape Tutorial =

Written November 2019

Slides from tutorial are [[https://docs.google.com/presentation/d/1SjesukdY5NNaWGFDgrJMrNJo5hry6CnnXS1rzjlWfRw/edit?usp=sharing|here]].

== Concepts ==

[[https://inkscape.org/|Inkscape]] is a free vector graphics editor. It is incredibly useful for figure design and layout. In a sentence, this means that at its core, Inkscape is about manipulating objects, vectors, text, and curves, rather than pixels. There are good online resources for questions on specific tools and visual effects. This tutorial is meant to be a "quick start" guide for using Matlab or Python with Inkscape to make good quality scientific figures.

Inkscape's native file format is the SVG, which stands for Scalable Vector Graphics. Other "vector graphics" file formats include PDF, EPS, and AI (Adobe Illustrator). When importing one of these other file formats, it's good practice to convert to an SVG. Image formats like PNG, JPEG, GIF, TIFF, and others are just that – plain old grid-of-pixel images. Editing raw images like this can be done with Photoshop or Gimp. Photoshop is to Gimp as is Illustrator to Inkscape.

If on Linux or OSX, launching Inkscape will launch X11 or XQuartz in the background, which is just a non-native "windowing" application. Quitting Inkscape will leave X11 on in the background, but quitting X11 will kill Inkscape's host environment and destroy unsaved changes. You've been warned. Even on Mac, keyboard shortcuts in X11 use the CONTROL key instead of COMMAND, but should otherwise be familiar – CTRL+C, CTRL+V for copy-paste, CTRL+S for save, etc.

== Importing and Exporting ==

Matlab and Python (specifically matplotlib) can export in PDF or SVG formats. All subsequent advice will assume Matlab since that's what I use. In theory, exporting figures to SVG should be preferred, but in practice, I find there are sometimes issues. Specifically, my experience is that text will not always import nicely as an SVG, but objects (e.g. points on a scatter plot) are not colored or grouped well in a PDF. That said, sometimes Matlab --> PDF --> Inkscape --> SVG just seems to work better, and is something to try if the SVG is misbehaving.

Resizing things can be tedious sometimes, so it's good practice to programmatically export figures already sized at least close to your desired final dimensions. With a Matlab figure go to ''File > Export Setup''. 99% of the time I can get away with setting only the dimensions and font size before exporting, then doing the rest in Inkscape.

When a figure is opened in Inkscape, its components are '''grouped''', often two levels deep for whatever reason. SHIFT+CTRL+G will ungroup things. Alternatively, double-clicking into an object will move your scope down into the group. Likewise, PDF and SVG files can be imported into Inkscape using '''CTRL+I'''. I '''strongly''' recommend using the "Poppler" importer for PDFs.

Exporting from Inkscape to PDF is as simple as "save as" (SHIFT+CTRL+S). Get in the habit of closing the window so you don't accidentally edit the PDF after exporting. The SVG should remain the "master" file. '''Warning:''' transparencies in PDFs will not print well, even if they look fine on a screen. There's probably a better workaround, but currently, I always export figures that have transparencies as PNGs (SHIFT+CTRL+E to bring up the PNG exporter window); 300dpi is generally plenty of resolution.

== Common Commands ==

Here are some very useful commands and their keyboard shortcuts:
 * '''F1''' - object selection mode. This is nothing fancy, it just sets your cursor up to point-and-click objects
 * '''F2''' - node selection mode. Slightly fancier. Most lines in Inkscape are Bezier curves, meaning they have a series of "control" points and tangent vectors. Going into F2 mode lets you select and modify individual nodes on a curve.
 * '''SHIFT+CTRL+A''' - pull up the '''alignment''' window. Super useful for laying out multiple panels in a figure, aligning text to an object, creating equal-spaced grids, etc.
 * '''SHIFT+CTRL+F''' - pull up the '''fill and stroke''' window. This is where selecting fill colors, line widths, and line styles happens.
 * '''SHIFT+CTRL+D''' - AKA ''File > Document Properties''. The "resize page to drawing" button is always the last thing I do before exporting, often with 1mm margins.
 * '''CTRL+D''' - Duplicate object.
 * '''SHIFT+ARROWKEYS''' - Move object quickly (20 pixels at a time). The arrow keys by themselves nudge objects around slowly.
 * '''1,3,4,5''' - Zoom levels. '''1''' is "actual size",  '''3''' is "zoom to selection", '''4''' is "zoom to drawing" (all your graphics objects), '''5''' is "zoom to page".
 * '''CTRL+G/SHIFT+CTRL+G''' - Group and ungroup

Lots of work is also done with the mouse, of course. For instance:
 * '''CLICK [Color]/SHIFT+CLICK [Color]''' - when you click on a color from the color palette on the bottom of the screen, it applies that as a '''fill color''' to the selected object. SHIFT+CLICK applies it as the '''stroke color.''' The leftmost color (red "X") is "null" and makes things transparent. '''F7''' selects the "Color Picker" tool, which works by the same logic: CLICKing any pixel grabs its color for fill, or SHIFT+CLICKing grabs it for stroke.
 * '''CTRL+DRAG''' - aptly enough, holding CTRL while dragging results in more controlled movements. For example, dragging an object to move it, CTRL will snap the displacement to the horizontal or vertical axis. Or, rotating an object, CTRL rotates in increments of 15 degrees.
 * '''DOUBLE CLICK''' - If on an object, dives one level down into the object's group. If on blank space, "un-dives" up one level of grouping.
 * '''CLICK+DRAG''' - select objects that fall within (but don't intersect) the dragged rectangle. It works as expected: holding SHIFT adds to the current selection.
 * '''CLICK+DRAG+OPTION''' - if you hold the OPTION key after starting a CLICK+DRAG, it replaces the rectangular selection box with a red line trail thing. Anything the trail intersects will be selected.