pigmap is a Minecraft map renderer, designed to be fast enough for very large worlds (like
the Aporkalypse Now server, hence the name).  It was inspired by Minecraft Overviewer and does
essentially the same thing, just faster and with fewer fancy options.  Features include:

-isometric projection; level of detail on max zoom is user-settable
-Google Maps tile output
-custom tilesets (supply your own terrain.png)
-ability to manually edit the isometric block images generated from terrain.png,
  for further beautification
-incremental map updates, but you must supply your own list of modified chunks (most
  likely via rsync or something similar)
-multithreading

pigmap is free under the GPL (please see the file COPYING).  I probably won't add too many
more features beyond whatever the Aporkalypse might need in the future, but hopefully it will
be useful to someone.

Michael J. Nelson, [email protected] ("equalpants" in Minecraft)

The files template.html and style.css contain code from Minecraft Overviewer (copyright
Andrew Brown and contributors).

---------------------------------------------------------------------------------------------------

Change log (important stuff only):

0.6.1
-support for HD texture packs

0.6
-new block types for Minecraft Beta 1.2: lapis, cake, etc.
-remaining undrawn blocks from previous versions now drawn: fire, buttons, levers, ascending
  cart tracks
-fire.png added; must be placed in images directory alongside terrain.png
-some block image offsets changed; see note below if you have manually edited your blocks-B.png
-some drawing improvements; may want to redo all block images from terrain.png

0.5.1
-speed improvements
-previously, we would abort if the world was too absurdly large to deal with--i.e. if there were
  some chunks whose coordinates were well into the billions--but apparently there is a Minecraft
  bug that can create such chunks way off in space, even if the world is normally-sized, so now
  we just ignore any chunks that are too far out to handle

0.5
-initial version

---------------------------------------------------------------------------------------------------

Supported platforms are Linux and cygwin.  (But porting to Windows native or OSX should be easy.)

Use supplied makefile to build with g++.  Depending on the system, it might need to be modified to
link in some more libraries.  Dependencies are zlib, libpng, pthreads, and some very basic system
stuff: getopt, mkdir, dirent.h.

---------------------------------------------------------------------------------------------------

Usage examples:

full render:

pigmap -B 6 -T 1 -Z 10 -i input/World1 -o output/World1 -g images -h 3

...builds a map with parameters B = 6, T = 1, baseZoom = 10, reading world data from the path
"input/World1", writing tiles out to the path "output/World1", reading terrain images from the path
"images", and using 3 threads.

incremental update:

pigmap -i input/World1 -o output/World1 -c chunklist -h 3 -x

...updates an existing map by redrawing any tiles touched by chunks listed in the file "chunklist",
with the input and output dirs as before.  Terrain images are read from the path ".", and 3 threads
are used.  Map parameters are read from the existing map, and if the existing baseZoom is too small,
it will be incremented.

---------------------------------------------------------------------------------------------------

Error messages are written to stderr; normal output to stdout.  There isn't much (read: any) of a
progress indicator at the moment, but there are some statistics upon completion.

---------------------------------------------------------------------------------------------------

Explanation of command-line options:


1. Params for both full renders and incremental updates:

a. input path, output path (-i, -o)

The chunk input path should be the top directory of the world data (i.e. where level.dat is).  The tile
output path should be the top of the Google Maps directory structure (i.e. where base.png is).  Tile
images will be written to the output path, along with a file "pigmap.params" which remembers what
parameters the map was drawn with.  For incremental updates, the output path must exist already, and
must contain the pigmap.params file.

b. [optional] HTML source path (-m)

This is where pigmap expects to find the files "template.html" and "style.css", which it will
use to construct a bare-bones HTML page for viewing the map.  The default HTML source path is "."

The map-viewing page is called "pigmap-default.html" and is written to the output path.  It doesn't have
any fancy capabilities (just plain old markers); it's meant only to demonstrate the JavaScript for
converting Minecraft coords to Google Maps latitude/longitude.  This file is rewritten with every
incremental update; make a copy if you need to add fancier abilities to it.

c. [optional] image path (-g)

This is where pigmap expects to find either a copy of terrain.png, or a copy of blocks-B.png
(substituting the actual numeric value of B; see below for definition of B), a pigmap-generated file
that contains the isometric renderings of each block.  The default image path is ".".  Each
blocks-B.png comes with a corresponding blocks-B.version, which remembers how many block images are
stored in blocks-B.png.  (As more blocks are added to the game, the version will change.)

The file fire.png, included with pigmap, must also be placed in the image path, alongside
terrain.png.  (fire.png contains the image used to draw fire blocks; terrain.png does not have a
tile for fire.)

The selection of block images works thusly:

-If blocks-B.png does not exist, then terrain.png will be used to create it.
-If blocks-B.png exists but has an old version, terrain.png will be used to fill in any missing
  (i.e. new) blocks, but the existing portions of blocks-B.png will be preserved.
-If blocks-B.png exists and is up-to-date, its block images will be used.

This means that pigmap will need terrain.png the first time it runs, so it can generate blocks-B.png;
subsequent runs will use the existing blocks-B.png, which can be manually edited if insufficiently
pretty, or for special effects, etc.

The textures in terrain.png (and fire.png) can be any size, as long as they remain square.

d. [optional] number of threads (-h)

Defaults to 1.  Each thread requires around 250-300 MB of RAM (they work in different areas of the
map and keep separate caches of chunk data).  Returns from extra threads may diminish quickly as the
disk becomes a bottleneck.


2. Params for full renders only:

a. map parameters B, T, [optional] baseZoom (-B, -T, -Z):

B is an integer >= 2 which controls the size (in pixels) of the blocks in the base zoom level.  The
map projection lays out blocks on a hexagonal grid generated from the distances [+/-2B, +/-B] and
[0, +/-2B], and each individual block's bounding box is 4B x 4B.

T is the tile multiplier, an integer >= 1 which controls how many chunks wide a tile is.

The size of each generated tile is 64BT x 64BT.

(To match Minecraft Overviewer's highest zoom level, use B=6 and T=1, for a tile size of 384 x 384.
To match its second-highest zoom, use B=3 and T=2.)

baseZoom is the Google Maps zoom level that the base tiles should be placed on.  This is important
because Google Maps allows only 2^Z by 2^Z tiles for each zoom level Z; if baseZoom is not high enough,
some tiles will not fit on the Google Map.  (Out-of-bounds tiles will be noticed at the start of a
render, and the render aborted.)

If baseZoom is omitted, it will be set to the lowest value that can fit all the required tiles.


3. Params for incremental updates only:

a. chunklist file (-c)

The name of a text file containing the filenames of chunks that should be updated, one per line.
Supplied filenames can have a relative or absolute path or can just be the file name; only the name
will be examined.

b. [optional] expand map if necessary (-x)

This is useful for frequently-updated maps: eventually, as the world expands outwards, it will become
too large for the current baseZoom, and an incremental update will fail.  If -x has been passed, then
if an incremental update fails due to out-of-bounds tiles, the map's baseZoom will be increased by
1, and the update retried.  (The baseZoom increase is *not* undone if the second attempt also fails.)

Note that increasing a map's baseZoom is quick: all the tiles are simply moved one level deeper in
the hierarchy, and the top two zoom levels redrawn.

---------------------------------------------------------------------------------------------------

What happens in a full render: the world data is scanned, and every chunk that exists on disk is noted.
All tiles that include any chunks are rendered and saved; any tiles that might exist already in the
output path are overwritten.

What happens in an incremental update: the chunklist is read and its chunks are considered "required";
the world data is not scanned.  (However, the input path must still contain the non-required chunks;
that is, you can't just use a partial copy of a world.  This is because each tile touches multiple
chunks; to render a required chunk, data from its non-required neighbors may be necessary.)  All tiles
that include required chunks are rendered and saved.  Base tiles that exist already in the output path
are overwritten, but those at lower zoom levels are merely modified--only the changed portions
are redrawn.

---------------------------------------------------------------------------------------------------

Special note for those who choose to manually edit blocks-B.png:

When new block types are introduced, their block images are added on to the end of blocks-B.png,
and the existing contents are preserved, so you don't need to worry about previous modifications
getting destroyed.  However, sometimes it may be necessary to remove existing block images and
replace them with new versions; when this happens, the old block image offset will no longer be
used, and a new block image will be added to the end of the file.

Example: prior to pigmap 0.6, the furnace block images were located at offsets 68, 69, and 149-152.
Starting with 0.6, they are instead located at 183-188.  (This is because the furnace graphics
were changed in Minecraft Beta 1.2.)  So if you modified the furnace block images while using a
pre-0.6 version of pigmap, your modified images can still be found at their old locations in your
blocks-B.png, but they must be copied to the new locations.

Complete list of block image moves:

--- pigmap 0.6 ---
furnaces: 68->183, 69->186, 149->184, 150->185, 151->187, 152->188
fire: 48->189
buttons: 123->190, 124->191, 125->192, 126->193
levers: 104->194, 105->195, 106->196, 107->197, 108->198, 109->199
ascending tracks: 88->200, 89->201, 90->202, 91->203