User:Xymph/Map views

This page discusses aspects of, and improvements for,. Having dabbled in PostScript map printing in the (distant) past, I have a soft spot for this topic. :) This page aims to tie together all available info that's fragmented in various talk pages (or even only hidden in some contributor's heads), and document the bits I figured out for myself. And sometimes it's little more than a brain dump.

Crispness
Two tools are commonly used to create map images for this wiki: the Omgifol drawmaps.py script and SLADE 3. Other tools appear to have been sporadically used to generate map views, e.g. MAP22-castle-of-grief.svg, No_Rest_for_the_Living_Map01.png and Lost_episodes_of_doom_e1m3.png, but it's unknown what and where they are, and they don't seem to be in active use anymore, so they are not covered here.

Omgifol‎ drawmaps.py exists in three versions. These test images illustrate the differences:

omgifol images are generated via the command-line: python omg/demo/drawmaps.py doom2.wad MAP01 999 PNG python omg/demo/drawmaps.py doom2.wad MAP01 1079 slade3 images are generated via the following GUI steps: See also the built-in Documentation -> Tutorials -> How to Create Map Images page.
 * 1) image 1 & 2:
 * 1) image 3:
 * 1) Open dialog tab Edit -> Preferences -> Interface -> Colours & Theme
 * 2) In section "Map Image Export", set Background 'White' (default) & Opacity 255 (non-transparent)
 * 3) Switch to dialog tab Advanced
 * 4) Find the map_image_* entries, and set _thickness to 3
 * 5) For the test image, set _height to 1079 and _width to 999
 * 6) Load doom2.wad
 * 7) From the WAD directory, preview MAP01
 * 8) Use the Save Map Image button, to the left just above the preview, and Save

Differences
Looking closely at the full-size images, there are three visible differences. In image 1, the end points of many (gray) 2-sided linedefs appear on top of the (black) 1-sided linedefs they connect to. See for example where the diagonal steps in the starting room meet the walls. This gives a ragged look to the overall map.

In images 2 and 3, this problem is solved by drawing the black lines after all the gray ones, thanks to this sorting statement: # draw 1s lines after 2s lines so 1s lines are never obscured edit.linedefs.sort(lambda a, b: cmp(not a.two_sided, not b.two_sided)) The result is a clean and crisp map image.

Image 1 is part of the very first batches of map uploads by Fredrik (author of Omgifol‎) for the UDoom, Doom2, Evilution & Plutonia IWADs in January 2005 (some superseded by Ryan W, see below). Source code of that pre-0.2 version of omgifol is not available, but most likely the sorting statement was not yet present then. It's unknown how many maps have been uploaded using this version, but assuming that v0.2 was the first public version (released in May 2005), any maps uploaded by anyone since then will likely be crisp.

Image 4, however, has the same ragged look as image 1, and therefore SLADE 3 probably does not sort the linedefs before drawing.

IMO the map pages of the official IWADs serve as "reference" for how all map pages could (eventually) look. Therefore they should have crisp map images, with the added benefit of distinguishing Doom Wiki more from its Wikia origin. Caveat is that the E1M*, E2M1-E2M5, E2M9 & E4M1 images use walkthrough spots added by Ryan W, so let's defer those for now. This is related to the marked spots discussion and maptabs RFC; see its demonstration.

TO DO:
 * 1) Recreate and upload all IWAD maps. I will do this soon unless someone objects.
 * 2) Contact Simon Judd to request improvement of map image generation. Implemented in v3.1.1.2.
 * 3) Revive the maptabs RFC and see if progress can be made towards adding spotted images (with walkthrough text to match) to all IWAD map pages.

Bottom line: until SLADE 3's map images are improved, the preferred wiki maps are those by omgifol (v0.2 or later)‎, IMHO. Given that it does not have a GUI, and not all regular map contributors will even read this here discussion, chances are that ragged map images will continue to be uploaded. Such is life in wiki-land. ;)

Edit: As of the v3.1.1.2 release of SLADE 3, its map images look similarly crisp as omgifol's thanks to linedef sorting, and all map contributors using SLADE 3 are advised to upgrade.

Scaling
The second visible difference, between the omgifol versions, is that some lines change very subtly. The scaling computations changed from v0.2 to the improved version, probably resulting in small rounding differences in placing the vertexes. And the original images were likely done on a 32-bit platform while my test images are done on 64-bit, also resulting in rounding differences.

The third difference, between omgifol and slade3 images, is that the former reserves a 4-pixel border while in the latter this is about 25-26 pixels. That's a matter of style. Neither difference is very interesting, so enough about these.

More relevant is the question of what a useful scale for a wiki-suitable map image is, in relation to the map's overall size.

File sizes
First, however, the file size itself depends on the tool: the above omgifol test images (since v0.2) are 17 KB, the slade3 one is 68 KB. Even accounting for omgifol using 24-bit PNG without alpha channel (transparency) and slade3 32-bit with alpha, this factor 4.0 increase seems steep. For bigger maps and images, the difference is likely proportional.

Image file size matters in general, both for websites serving them (traffic costs, server load) and for users downloading them (time), so omgifol images are clearly preferable, IMHO. But to Doom Wiki, it is of no consequence.

Controlling scale
Omgifol drawmaps through v0.2 takes its pixel-size parameter to be the required width, and the height is calculated proportionally. That's why portrait-oriented maps (e.g. MAP32, 1.8M px2) can end up being significantly larger than landscape ones (e.g. MAP03, 0.67M px2) at identical width. The improved omgifol version applies its pixel-size parameter to the largest of either width or height, making for smaller, narrower landscape images (e.g. MM2_MAP20). This is why in the above command-line for image 3, 1079 was used to arrive at the same dimensions as images 1 & 2.

SLADE 3 allows separate definitions of width and height in pixels (positive numbers), shown in step #5 above to match omgifol's test image dimensions, while negative values are taken to be the scale between map units and image dimensions. E.g. setting both to -4 for MAP01 produces a 844x912 px image. That's flexible and useful, although carelessly setting fixed dimensions without regard for the map's orientation can result in excess whitespace (e.g. D2TWID_MAP33), as does setting width and height to different scale values. Also, SLADE 3 does allow changing line thickness, while Omgifol does not.

Factors influencing the appearance of map images are:
 * map dimensions versus image dimensions, i.e. the scale
 * overall image dimensions (which affects file size, preferably kept below 250 KB)
 * line thickness versus map dimensions
 * level of detail in the map (e.g. large numbers of 2-sided linedefs)
 * whether monster caches & control sectors are edited out before generating an image

A large image of a small map like Fava_Beans_E1M1 seems excessive but is otherwise nice and clean. Conversely however, small images of big maps (e.g. 50shades_MAP06 & Breach) are, frankly, useless as many lines simply blur together. It's impossible to find one's way around them in tandem with a textual walkthrough. A large image helps a lot to understand the lay of the land (e.g. E1M8B), or compare Sunlust_MAP10 versus Sunlust_MAP10 (talk).

Line thickness should be more than 1 pixel or some lines will disappear when the map is scaled down to a thumb image next to a walkthrough. Omgifol always uses 3-pixel lines while the SLADE 3 default is 1, hence the adjustment in step #4 above, and while some experimentation with other values can be interesting, 3 is usually fine.

Lastly, editing out parts of the map that cannot be accessed by the player, such as monster caches and control sectors, affects the scale and dimensions with which the image is subsequently generated. For example, the 1000x917 px image of the edited Cchest3_MAP23 becomes a 1258x917 px image (trust me) of the original map when adjusting for the same height. The visual appearance is indeed different, but this isn't problematic unless the trimmed sectors are way outside the regular map area. And map editing is, of course, time consuming if all one wants is a quick map. :)

Useful scale
With all that covered, back to the original question: what is a useful scale, especially for a multi-map series? If all maps in series (e.g. an IWAD) are rendered at the same scale, the viewer immediately gets a good idea of the size differences between those maps. While SLADE 3 allows setting scales, it is not convenient to generate an entire batch of map images via the GUI. So I updated the Omgifol drawmaps script to accept an optional scale parameter as well, and apply that to all generated maps.

After some experimentation the value 4.0 gives acceptable results for the four official IWADs. A factor of 4.5 would also work, but SLADE 3 accepts only integer scale values, so let's stick to that. However, a fixed scale like that can result in impractically large images for really expansive maps, such as the outdoor levels in the IWADs, and modern maps for limit-removing ports (e.g. Plasmaplant).

To get a feel for this problem, I generated the four IWADs' maps with scale 4.0:

In today's era of large monitors, an image with a maximum dimension (height and/or, especially, width) of 1600 pixels seems (IMHO) of acceptable size for displaying in a browser without excessive scrolling around at 100% scaling. As indicated by italics in the table, only a few maps in most IWADs exceed that dimension. TNT: Evilution is notable however for almost half its maps being (very) expansive. And a modern level like the aforementioned Plasmaplant would be 2801 x 3399 pixels at scale 4.0, too. As rendered, its 2060 x 2500 dimensions correspond to scale 5.44 instead, but an even larger scale factor to bring its height (closer) to 1600 would blur together too many of the 2-sided linedefs.

So a mechanism is needed to keep large maps down to acceptable image dimensions. That's actually simple: fall back on the already specified maximum dimension for the largest of width and height. Limiting the above expansive maps to 1600 pixels results in the following new dimensions, with the effective scale added in italics:

Most of the new scale factors are not significantly larger than the default, with the exception of Evilution's MAP20, MAP21 and MAP27.

Conclusions
Scale 4.0 (for Omgifol drawmaps) or -4 (for SLADE 3) is the best scale to render the vast majority of regularly-sized maps, and especially useful when generating a series of maps so the viewer gets a good feel of the size differences between them.

Limiting the largest dimension (width and/or height) to 1600 pixels for larger maps is an acceptable compromise. With Omgifol that's handled automatically, but setting a fixed pixel limit for one dimension in SLADE 3 requires adjusting the other dimension such that little excess whitespace results, which can take some experimentation.

For modern, expansive maps with a great level of architectural detail, a larger dimension limit such as 2000-2500 pixels may need to be chosen to prevent lines blurring together. Line thickness should be 3 (in SLADE 3, already default in Omgifol).

The drawmaps commands to generate the IWADs' maps thus become: python omg/demo/drawmaps.py DOOM.WAD E?M? 1600 4.0 python omg/demo/drawmaps.py DOOM2.WAD MAP* 1600 4.0 The current drawmaps script with scale support can be downloaded from my homepage. This version also offers verbose logging of the actual scale and dimensions used for each map if the option is specified. This feature provided the data for the above tables.
 * 1) same for TNT.WAD & PLUTONIA.WAD

Lastly, if no scale is specified and multiple maps are generated, then verbose logging will include the average scale used to draw those maps within the specified (or default) size.