Map SVG Format

There is a more recent, simplified & more precise guide for this process. You can find it here

This wiki will describe the format of YAPms SVGs, and how to make them from scratch.

Tools required (both PC exclusive):

• Some sort of SVG graphics editor, the preferred program is Inkscape, and both YAPms developers use it to make maps.

• Some sort of source-code editor, the preferred program is VSCode.

Part 1: Have an SVG file at hand

There are 2 ways to get an SVG:

1. Downloading one online, most often from Wikipedia (this should be your first choice whenever possible)

2. Making one yourself

Part 0 (Option 1): Downloading

Well, downloading one is obviously easier overall, just go to the Wikimedia page of an SVG that you want to download and click on "save/download link" or something of that type, or go to the website which has the SVG you want to download, which will probably have a pretty big download button on it somewhere, and that should give you a perfectly fine SVG. The only thing you might need to do before opening up VSCode is selecting all the subdivisions in your map and click “compress” under “Path”, in case your SVG has the nodes from different regions extremely close to eachother and your states have nearly invisible borders:

With this, as the SVG is already done, you can already go straight to coding.

Part 0 (Option 2): Making an SVG yourself

Well, sometimes the map you want to download may not have an SVG file available to download anywhere, so you'll have to make one yourself. How? To do that, you'll open the (png/jpg/tiff/some bitmap) image on Inkscape and choose the "trace bitmap" button, which will open up a few options for you. The way I know of turning a PNG to an SVG is using a brightness filter in the tool, which, before anything else, means that whatever map image you're downloading need to have 3 things:

Clear/High-contrast and fairly dark or bright subdivision boundaries that are at least a few pixels thick (though I think just upscaling the image usually works well enough).

The subdivisions themselves can't be very colorful, or at least they can't be very dark or bright or else the brightness filter will only working within a narrow range, or none at all.

No text overlapping said boundaries.

Here's a good image to use. Although it is pretty colorful, the subdivision boundaries are thick and pretty much black, so it contrasts clearly with the states.

(Disclaimer: The Russian Empire's 1917 electoral divisions which this map depicts do have svg files available to use, so use those instead. I didn’t know this and had to do things the long way.)

Anyway, having found your image you'll move the brightness (I’m Brazilian, mine says “limiar”) cutoff slider around until only the borders you want to turn into an SVG are visible, and click the OK/Apply/Confirm/Whatever button, and Inkscape should give you something like this:

(Make sure to drag the first slider down or it might not separate all the provinces properly, though Inkscape has a helpful preview for this stuff down there where it says “pre-visualization”. The other 2 aren’t so important but I find more suave/smooth lines look prettier to me so I turn it up.)

It looks almost the same, just colorless. Well, this is actually an SVG pathway now, no longer composed of pixels but of vectors. To turn this into a bunch of blobs fit for for YAPMS, you’re going to click “Separate/Split/Divide” (the third-to last icon in this image) under “Pathway”:

And here’s your result. After removing the old path, your map which topologically resembled a sponge or Swiss Cheese should now look like a bunch of subdivision-shaped blobs instead, like this:

Awesome. You can now go to part 2 and edit the source code of your file. If you want to add text and boxes like the ones the default map has for states like Maryland, you can just do that within Inkscape using it’s respective box and text icons.

Troubleshooting and Edge cases

However, when I did this for the first time, some parts of the country didn’t turn black. If this happens to your map, it's because there were some holes/gaps in the borders of your image that the SVG inherited:

…How annoying. If you find yourself in this situation, you need to go edit the nodes directly by clicking on an icon immediately below a mouse icon in the far-left:

You then need to break the bond between the 2 neighboring nodes (they happen to be rendered as diamonds here) in both sides using the grey button with multiple dots, and when the 2 nodes start being rendered as if they were together, merge them:

After all that, it’s important that you make sure all the islands are joined together to the mainland unless you know those islands are their own separate subdivisions. Multi-select in Inkscape works with the Shift key and you just click “Union ” or “Join ” under pathway after clicking all the islands.

Finally, in this map Moscow is inside a district, which is also inside the whole map. This basically means that it will be hidden behind the district that surrounds it, and you won’t be able to see or click it. Fortunately, it’s visible in Inkscape if you click on “layers” or “objects”, then “layers and objects” and use the alt key they become visible:

Then you need to select the larger of the 2 dots, use Shift to simultaneously select the blob surrounding it, click on “Exclude” and inkscape will drill a hole in the wider province and make the city accessible:

Part 2: Coding and Customizing

(If any of this stuff ends up being complicated/unintuitive, just try to emulate Yapms’s 2024 Presidential USA map here.)

Now, you're going to take your SVG and copy it, and perhaps move it to some YAPMS-related folder. Then, you’re gonna open the copy:

That’s a lot of stuff but most of it is unimportant for YAPMS. For our own convenience let’s just make it so all the tags/elements (code that looks like is a tag or element) aren’t clumped up like this by using that search icon over there, typing “><” or “/><” into the top box, clicking the arrow to the left of it and typing “><” again and pressing shift+enter to separate all the tags from eachother:

Looks much better now. Now you’re gonna remove the width and height of the SVG. Don’t worry, the viewbox will take care of it, and YAPMS doesn’t even have a recognizable border in the first place, you can just zoom out and zoom into a distant spot with nothing in it. Then, you’re going to add in this chunk of code in this same region where you just deleted the width and height:

  candidates="[
    {"id":"0", "name":"Joe Biden", "margins": [{ "color": "#000055" }, { "color": "#000099" }, { "color": "#0000ff" }]},
    {"id":"1", "name":"Donald Trump", "margins": [{ "color": "#550000" }, { "color": "#990000" }, { "color": "#ff0000" }]}
  ]"

(Unless you want the candidates to be Democrat and Republican, because that's the default setting.)

If you look at the stuff in this you’ll see Joe Biden and Donald Trump, because this code basically takes care of the candidates and margin (Safe, likely, lean, whatever) colors that show up by default. Here you can basically add as many colors and candidates as you want, just remember to give all your candidates their own IDs while copy-pasting and keeping track of the colons and parentheses if you want to order them nicely and end up needing to move these blocks of code up and down.

Part 2.1: Editing the path

Well, now you're gonna get to the meat of this whole operation. First, you’re gonna add or replace a with the regions attribute (this attribute can have any value, Inkscape will not let you use an empty value (ex. )). (If you downloaded an SVG with multiple groups or especially one of those really intricate ones that also have groups inside groups, the specific group you’re looking for is the one that contains all of the countries/states/subdivisions in it. To find out which group is that, click on “layer” and then “Layers and objects”.) Then you're gonna use the search and replace function on all the <path tags/elements and add a region (like the path ID inkscape gives, but for YAPMS), short name, long name and value (Long-name is if you use delegate edit while I think short-name and value are so the acronyms and EV count are added, if you choose to create the groups associated with them, that’s at the end of this tutorial) variables:

To be clear, YAPMS SVGs need to follow this format:

Format

<svg id="testing-map">
<g map-type="regions">
  <path region="al" short-name="al" long-name="Alabama" value="9" />
</g>
<g map-type="region-texts">
  <text for-region="oh" />
</g>
</svg>

And these variables mean:

map-type="regions"

This group contains the shape data for all regions. The properties for a region are as follows:

• region: Used to track the region. Analoguous to an ID. You may just give the regions numbers for IDs but if you plan to add text, it's best to make these IDs actually name-like, like in the example above.
• short-name: Displayed by the YAPms interface. Specifically in the region tooltip.
• long-name: Displayed by the YAPms interface. (In edit and split mode)
• value: The point value that the region will add to a candidate, in the US it's basically the. May also be displayed in the YAPMS interface

map-type="region-texts"

This group contains text that should be displayed over a region or region button. These will not be clickable, and all click actions will go through the text.

• for-region: The for property must match the region property of the region the text is for.

Part 2.1 (continued)

Then you will need to type in region IDs, short names, full names and the amount of EV/Seat/Deputy/MP/Whatever for each subdivision you have, one by one. This step is unfortunately entirely manual unless you’re actually good enough at this to figure out some mass-editing scheme yourself or know a program that does it for you. (Talk to Flizzy on the Discord if you need some code snippets to help w/ this)

Doing all that assigning isn't too irritating if you’re under ~30 or so states but I imagine this can genuinely take 2 or 3 hours in bigger maps. But your map is already fully usable in YAPMS! Good job reading through this whole damn thing, it’s way larger than I expected it to be, and that’s because that image and map of Russia are cursed, lol. Because I thought the idea of a Democratic Russian Empire was cool and they actually held a large, modern election IRL in 1917 I learned pretty much everything you read in this text, LMAO.

That being said, there’s still one important thing left to explain, but it’s completely optional:

Part 2.2: Adding Names and EV counts to the SVG

To add the text to the YAPMS-SVG like in the US map that YAPMS made first you needed to add the text in the original SVG before copying immediately before troubleshooting and edge-cases. (BTW, from my experience I’ve learned Inkscape can open YAPMS-custom SVGs just fine but if you make an edit and save it Inkscape can screw around with all the custom stuff this part is about, so don’t resort to this too often.)

Then, you need to create a new group for the text with a region-texts attribute, and inside this group will be all the text in your map.

Then, for each text tag, you need to specify the region it applies to and which of the 2 t-spans within the text tag displays the name (does not need an additional attribute) and which one displays the value you gave the region (needs the value-text attribute).

Lastly, you need to add fill="currentColor" to the region-texts group in your file so YAPMS changes the color of the text depending on if the candidate/party you selected is dark or bright. Here’s a finished example:

Dark fill	Light fill