To review key information on designing icons, see Icons.
Once you've settled on the design or concept for your icons, you'll need to generate .svg
files for each one to be saved in the icons directory. Icons should be created as 100x100 pixel graphics that are clear when viewing at 100%.
To generate .svg
icons for Mapeo, there is an online Mapeo Icons Generator tool accessible here.
We have also documented two workflows to generate Mapeo-compatible .svg
files using software, one using a commercial product (Adobe Illustrator) and another using a open-source product (Inkscape).
Icons need to be read by MAPEO in two sizes: 100 pixels and 24 pixels. For that reason there is a specific file naming convention:
icon-name-100px.svg
icon-name-24px.svg
Each icon can be duplicated and renamed so that there is one of each size. They are opened and read by the .json
files in the presets folder. Verify that name
is correctly entered where needed (more on this in the next section). The build script will process the pixel size suffix.
Adobe Illustrator is a vector graphics editor and design program developed by Adobe Inc. Although it is a commercial, licensed product, it is very commonly used to put together vector graphics, and many users utilize this tool for creating icons for Mapeo as well.
.svg
files with the right propertiesWhen you're ready to export a vector graphic file into a Mapeo-compatible .svg
file format, the process is as follows:
On the Adobe Illustrator top menu, click on File and then select Export, followed by Export As.
Ensure that Use Artboards is checked.
Save your .svg
file in the correct directory (icons
for Mapeo configurations) and with your desired filename, and click Export.
In the following window, ensure that the following properties are set, and then click OK:
Your .svg
file should now be ready to be used by Mapeo. See #naming-icon-files for more information on how to name the files and where to place them in the configuration directory.
Inkscape is a free and open-source vector graphics editor used to create vector images, primarily in Scalable Vector Graphics (.svg
) format. Inkscape is an alternative to the commercial software Adobe Illustrator, and can be used to generate .svg
files that work in Mapeo.
A common workflow for generating Mapeo icons is to find photos or other raster images, and turn them into vector images, simplifying them until they will render well at a small size. In Adobe Illustrator, this can be done using the Image Trace
tool.
In Inkscape, this can be done using the Trace Bitmap
tool found in the Path menu. There are some options to manipulate like Smoothing corners, Optimizing corners, and setting the number of colors.
.svg
files with the right size and Viewbox in Document PropertiesOnce you have a vector image that is to your satisfaction (and in a square format), you need to set the correct width & height and Viewbox size before saving the .svg
file. You can do this in Document Properties
(File menu).
First, set the Display units
to pixels (px). This dropdown is located at the very top of the Document Properties menu.
Locate the "Custom Size" and "Scale" boxes in Document Properties.
First, you may need to set the unit of measurement for the Custom size, if it is not in pixels. If Units
is in a format like milimeters (mm), change this to px.
Set the Width
and Height
to 100 each.
Next, the Viewbox needs to be set to 100 as well. The easiest way to do this — once you've set the Display units and Custom size units to pixels — is to set the Scale x
to 1. It should copy over the Width and Height values from the Custom Size to the Viewbox. If that didn't do the trick, manually enter 100 for both Width
and Height
here.
Once you've done this, you may need to resize the art to match the full size of the Viewbox:
The easiest way to do this is to use the sizing and placement parameters right above the Viewbox, as shown in the screenshot above. Set W
and H
to 100 (px), and make sure X
and Y
are set to 0 (px). The image will then fill the entire Viewbox:
You can now save the .svg
file by going to File → Save / Save As / Save A Copy.
Your .svg
file should now be ready to be used by Mapeo. See #naming-icon-files for more information on how to name the files and where to place them in the configuration directory.
If you want to verify that the parameters in your .svg
file are correct, open it in a text editor like Visual Studio Code or Notepad++.
It should have an initial <svg>
tag with width and height set to 100, and viewBox set to "0 0 100 100."
After some tags like <defs>
, <sodipodi:namedview>
, <metadata>
, which don't matter for the purposes of creating icons for Mapeo, you should see tags like <g>
with layer properties, and a series of <path>
with vertices and style properties, which constitute your vectors.
If your .svg
file looks like this, the Mapeo configurations builder script should process your icons just fine.