finished up the essential documentation

building.rst

@@ -112,6 +112,8 @@ The following script (copied into your MCO source directory) should handle every
     # build MCO
     C_INCLUDE_PATH="`pwd`/Imaging-1.1.7/libImaging" python ./setup.py build
 
+.. _centos:
+
 CentOS
 ------
 Since CentOS has an older version of Python (2.4), there are some difficulties

design/designdoc.rst

@@ -15,6 +15,8 @@ Overviewer development.
 
 So let's get started!
 
+.. contents::
+
 Background Info
 ===============
 The Overviewer's task is to take Minecraft worlds and render them into a set of tiles that can be displayed with a Google Maps interface.
@@ -191,6 +193,9 @@ This is done at the end of :func:`textures._build_block`
 .. image:: pixelfix.png
     :alt: The 6 pixels manually added to each cube.
 
+Other Cube Types
+----------------
+
 Chunk Rendering
 ===============
 .. This goes over the rendering of a chunk

faq.rst

@@ -0,0 +1,22 @@
+==========================
+Frequently Asked Questions
+==========================
+
+**The full map doesn't display even when fully zoomed out!**
+    Are you using the `-z` or `--zoom` option on your commandline or in
+    settings.py? If so, try removing it, or increasing the value you set. It's
+    quite likely you don't need it at all.
+
+**You've added a few feature, but it's not showing up on my map!**
+    Some new features will only show up in newly-rendered areas. Use the
+    `--forcerender` option to update the entire map.
+
+**How do I use this on CentOS 5?**
+    CentOS 5 comes with Python 2.4, but the Overviewer needs 2.6 or higher. See
+    the special instructions at :ref:ref:`centos`
+
+**The background color of the map is black, and I don't like it!**
+    You can change this by using the ``--bg-color`` command line option, or
+    ``bg_color`` in settings.py. See the `Options <options.html>`_ page for more
+    details.
+

index.rst

@@ -54,6 +54,8 @@ Documentation Contents
    building
    installing
    running
+   options
+   faq
    design/designdoc
 
 

options.rst

@@ -0,0 +1,340 @@
+=======
+Options
+=======
+
+.. contents::
+    :local:
+
+Command line options
+====================
+
+.. cmdoption:: -h, --help
+
+    Shows the list of options and exits
+
+.. cmdoption:: --advanced-help
+
+    Display help - including advanced options
+
+Useful Options
+--------------
+.. cmdoption:: --rendermodes=MODE1[,MODE2,...]
+
+    Use this option to specify which render mode to use, such as lighting or
+    night. Use --list-rendermodes to get a list of available rendermodes, and
+    a short description of each. If you provide more than one mode (separated
+    by commas), Overviewer will render all of them at once, and provide a
+    toggle on the resulting map to switch between them.
+    
+    If for some reason commas do not work for your shell (like if you're using
+    Powershell on Windows), you can also use a colon ':' or a forward slash '/'
+    to separate the modes.
+
+    See the `Render Modes`_ section for more information.
+
+.. cmdoption:: --list-rendermodes
+
+    List the available render modes, and a short description of each.
+
+.. cmdoption:: --north-direction=NORTH_DIRECTION
+
+    Specifies which corner of the screen north will point to.
+    Valid options are: lower-left, upper-left, upper-right, lower-right.
+    If you do not specify this option, it will default to whatever direction
+    the existing map uses. For new maps, it defaults to lower-left for
+    historical reasons.
+
+.. cmdoption:: --settings=PATH
+
+    Use this option to load settings from a file. For more information see the
+    `Settings File`_ section below.
+
+Less Useful Options
+-------------------
+
+.. cmdoption:: -p PROCS, --processes=PROCS
+
+    Adding the "-p" option will utilize more cores during processing.  This
+    can speed up rendering quite a bit. The default is set to the same
+    number of cores in your computer, but you can adjust it.
+
+    Example to run 5 worker processes in parallel::
+
+        python overviewer.py -p 5 <Path to World> <Output Directory>
+
+.. cmdoption:: -d, --delete
+
+    This option changes the mode of execution. No tiles are rendered, and
+    instead, files are deleted.
+
+    *Note*: Currently only the overviewer.dat file is deleted when you run with
+    this option
+
+.. cmdoption:: --forcerender
+
+    Force re-rendering the entire map (or the given regionlist). This
+    is an easier way to completely re-render without deleting the map.
+
+.. cmdoption:: --regionlist=regionlist
+
+    Use this option to specify manually a list of regions to consider for
+    updating. Without this option, every chunk in every region is checked for
+    update and if necessary, re-rendered. If this option points to a file
+    containing, 1 per line, the path to a region data file, then only those
+    in the list will be considered for update.
+
+    It's up to you to build such a list. On Linux or Mac, try using the "find"
+    command. You could, for example, output all region files that are older than
+    a certain date. Or perhaps you can incrementally update your map by passing
+    in a subset of regions each time. It's up to you!
+
+
+
+Settings File
+=============
+
+You can optionally store settings in a file named settings.py (or really,
+anything you want).  It is a regular python script, so you can use any python
+functions or modules you want. To use a settings file, use the --settings
+command line option.
+
+For a sample settings file, look at 'sample.settings.py'. Note that this file
+is not meant to be used directly, but instead it should be used as a
+collection of examples to guide writing your own.
+
+Here's a (possibly incomplete) list of available settings, which are available
+in settings.py. Note that you can also set command-line options in a similar
+way.
+
+imgformat=FORMAT
+    Set the output image format used for the tiles. The default is 'png',
+    but 'jpg' is also supported.
+
+zoom=ZOOM
+    The Overviewer by default will detect how many zoom levels are required
+    to show your entire map. This option sets it manually.
+
+    *You do not normally need to set this option!*
+
+    This is equivalent to setting the dimensions of the highest zoom level. It
+    does not actually change how the map is rendered, but rather *how much of
+    the map is rendered.* Setting this option too low *will crop your map.*
+    (Calling this option "zoom" may be a bit misleading, I know)
+   
+    To be precise, it sets the width and height of the highest zoom level, in
+    tiles. A zoom level of z means the highest zoom level of your map will be
+    2^z by 2^z tiles.
+
+    This option map be useful if you have some outlier chunks causing your map
+    to be too large, or you want to render a smaller portion of your map,
+    instead of rendering everything.
+
+    Remember that each additional zoom level adds 4 times as many tiles as
+    the last. This can add up fast, zoom level 10 has over a million tiles.
+    Tiles with no content will not be rendered, but they still take a small
+    amount of time to process.
+
+web_assets_hook
+    This option lets you define a function to run after the web assets have
+    been copied into the output directory, but before any tile rendering takes
+    place. This is an ideal time to do any custom postprocessing for
+    markers.js or other web assets.
+    
+    This function should accept one argument: a QuadtreeGen object.
+
+web_assets_path
+    This option lets you provide alternative web assets to use when
+    rendering. The contents of this folder will be copied into the output folder
+    during render, and will overwrite any default files already copied by
+    Overviewer. See the web_assets folder included with Overviewer for the
+    default assets.
+
+textures_path
+    This is like web_assets_path, but instead it provides an alternative texture
+    source. Overviewer looks in here for terrain.png and other textures before
+    it looks anywhere else.
+
+north_direction
+    Specifies which corner of the screen north will point to.
+    Valid options are: lower-left, upper-left, upper-right, lower-right.
+
+Render Modes
+============
+
+.. _rendermode-options: https://github.com/agrif/Minecraft-Overviewer/tree/rendermode-options
+
+Rendermode options are a new way of changing how existing render modes
+work, by passing in values at startup. For example, you can change how
+dark the 'night' mode is, or enable lighting in 'cave' mode.
+
+Options and Rendermode Inheritance
+----------------------------------
+
+Each mode will accept its own options, as well as the options for
+parent modes; for example the 'night' mode will also accept options
+listed for 'lighting' and 'normal'. Also, if you set an option on a
+mode, all its children will also have that option set. So, setting the
+'edge_opacity' option on 'normal' will also set it on 'lighting' and
+'night'.
+
+Basically, each mode inherits available options and set options from
+its parent.
+
+Eventually the :option:`--list-rendermodes` option will show parent
+relationships. Right now, it looks something like this:
+
+* normal
+
+  * lighting
+
+    * night
+    * cave
+
+* overlay
+
+  * spawn
+  * mineral
+
+How to Set Options
+------------------
+
+Available options for each mode are listed below, but once you know
+what to set you'll have to edit *settings.py* to set them. Here's an
+example::
+
+    rendermode_options = {
+        'lighting': {
+            'edge_opacity': 0.5,
+        },
+
+        'cave': {
+            'lighting': True,
+            'depth_tinting': False,
+        },
+    }
+
+As you can see, each entry in ``rendermode_options`` starts with the mode name
+you want to apply the options to, then a dictionary containing each option. So
+in this example, 'lighting' mode has 'edge_opacity' set to 0.5, and 'cave' mode
+has 'lighting' turned on and 'depth_tinting' turned off.
+
+Defining Custom Rendermodes
+---------------------------
+
+Sometimes, you want to render two map layers with the same mode, but with two
+different sets of options. For example, you way want to render a cave mode with
+depth tinting, and another cave mode with lighting and no depth tinting. In this
+case, you will want to define a 'custom' render mode that inherits from 'cave'
+and uses the options you want. For example::
+
+    custom_rendermodes = {
+        'cave-lighting': {
+            'parent': 'cave',
+            'label': 'Lit Cave',
+            'description': 'cave mode, with lighting',
+            'options': {
+                'depth_tinting': False,
+                'lighting': True,
+            }
+        },
+    }
+
+    rendermode = ['cave', 'cave-lighting']
+
+Each entry in ``custom_rendermodes`` starts with the mode name, and is followed
+by a dictionary of mode information, such as the parent mode and description
+(for your reference), a label for use on the map, as well as the options to
+apply.
+
+Every custom rendermode you define is on exactly equal footing with the built-in
+modes: you can put them in the ``rendermode`` list to render them, you can
+inherit from them in other custom modes, and you can even add options to them
+with ``rendermode_options``, though that's a little redundant.
+
+Option Listing
+--------------
+
+Soon there should be a way to pull out supported options from Overviewer
+directly, but for right now, here's a reference of currently supported options.
+
+normal
+~~~~~~
+
+* **edge_opacity** - darkness of the edge lines, from 0.0 to 1.0 (default: 0.15)
+* **min_depth** - lowest level of blocks to render (default: 0)
+* **max_depth** - highest level of blocks to render (default: 127)
+* **height_fading** - darken or lighten blocks based on height (default: False)
+
+lighting
+~~~~~~~~
+
+all the options available in 'normal', and...
+
+* **shade_strength** - how dark to make the shadows, from 0.0 to 1.0 (default: 1.0)
+
+night
+~~~~~
+
+'night' mode has no options of its own, but it inherits options from
+'lighting'.
+
+cave
+~~~~
+
+all the options available in 'normal', and...
+
+* **depth_tinting** - tint caves based on how deep they are (default: True)
+* **only_lit** - only render lit caves (default: False)
+* **lighting** - render caves with lighting enabled (default: False)
+
+mineral
+~~~~~~~
+
+The mineral overlay supports one option, **minerals**, that has a fairly
+complicated format. **minerals** must be a list of ``(blockid, (r, g, b))``
+tuples that tell the mineral overlay what blocks to look for. Whenever a block
+with that block id is found underground, the surface is colored with the given
+color.
+
+See the *settings.py* example below for an example usage of **minerals**.
+
+Example *settings.py*
+---------------------
+
+This *settings.py* will render three layers: a normal 'lighting' layer, a 'cave'
+layer restricted to between levels 40 and 55 to show off a hypothetical subway
+system, and a 'mineral' layer that has been modified to show underground rail
+tracks instead of ore.
+
+::
+
+    rendermode = ['lighting', 'subway-cave', 'subway-overlay']
+
+    custom_rendermodes = {
+        'subway-cave' : {'parent' : 'cave', 
+                         'label' : 'Subway',
+                         'description' : 'a subway map, based on the cave rendermode',
+                         'options' : {
+                             'depth_tinting' : False,
+                             'lighting' : True,
+                             'only_lit' : True,
+                             'min_depth' : 40,
+                             'max_depth' : 55,
+                         }
+        },
+        'subway-overlay' : {'parent' : 'mineral',
+                            'label' : 'Subway Overlay',
+                            'description' : 'an overlay showing the location of minecart tracks',
+                            'options' : {'minerals' : [
+                                (27, (255, 234, 0)),
+                                (28, (255, 234, 0)),
+                                (66, (255, 234, 0)),
+                            ]}
+        },
+    }
+
+    rendermode_options = {
+        'lighting' : {'edge_opacity' : 0.5},
+    #    'night' : {'shade_strength' : 0.5},
+    #    'cave' : {'only_lit' : True, 'lighting' : True, 'depth_tinting' : False},
+    }

running.rst

@@ -5,20 +5,131 @@ Running the Overviewer
 Rendering your First Map
 ========================
 
-Overviewer is a command-line application, and so it needs to be run from the command line. If you installed Overviewer from a package manager, the command is ``overviewer.py``. If you downloaded it manually, open a terminal window and navigate to wherever you downloaded Overviewer. For pre-compiled Windows builds, the command is ``overviewer.exe``. For other systems, it's ``./overviewer.py``.
+Overviewer is a command-line application, and so it needs to be run from the
+command line. If you installed Overviewer from a package manager, the command is
+``overviewer.py``. If you downloaded it manually, open a terminal window and
+navigate to wherever you downloaded Overviewer. For pre-compiled Windows builds,
+the command is ``overviewer.exe``. For other systems, it's ``overviewer.py``.
 
-To generate your map, run::
+The basic usage for Windows is::
 
-    overviewer.exe WorldName path\to\output\                 # on windows, or
+    overviewer.exe [options] <World> <Output Dir>
-    ./overviewer.py WorldName path/to/output/                 # on other systems
 
-where ``WorldName`` is the name of the world you want to render, and
+And similarly for other systems::
-``path/to/output`` is the place where you want to store the rendered world. The
-first render can take a while, depending on the size of your world. You can, if
-you want to, provide a path to the world you want to render, instead of
-providing a world name and having Overviewer auto-discover the world path.
 
-When the render is done, open up *index.html* using your web-browser of choice. Pretty cool, huh? You can even upload this map to a web server to share with others! Simply upload the entire folder to a web server and point your users to index.html!
+    overviewer.py [options] <World> <Output Dir>
 
-Incremental updates are just as easy, and a lot faster. If you go and change something inside your world, run the command again and Overviewer will automatically rerender only what's needed.
+**World**
+    World can be one of several things.
 
+    1. The path to your Minecraft world on your hard drive
+    2. The name of a single player world on your current system. Note that if it
+       has spaces, you will need to put the world name in quotes.
+
+**Output Dir**
+    This is the directory you would like to put the rendered tiles and
+    supporting HTML and javascript files. You should use the same output
+    directory each time; the Overviewer will automatically re-render only the
+    tiles that need rendering on subsequent runs.
+
+**options**
+    See the `Options <options.html>`_ page for a list of options you can
+    specify.
+
+For example, on Windows if your Minecraft server runs out of ``c:\server\`` and you want
+to put the rendered map in ``c:\mcmap\``, run this::
+
+    overviewer.exe c:\server\world c:\mcmap
+
+For Mac or Linux builds from source, you would run something like this with the
+current directory in the top level of the source tree::
+
+    ./overviewer.py /opt/minecraft/server/world /opt/minecraft/mcmap
+
+The first render can take a while, depending on the size of your world.
+
+When the render is done, open up *index.html* using your web-browser of choice.
+Pretty cool, huh? You can even upload this map to a web server to share with
+others! Simply upload the entire folder to a web server and point your users to
+index.html!
+
+Incremental updates are just as easy, and a lot faster. If you go and change
+something inside your world, run the command again and Overviewer will
+automatically rerender only what's needed.
+
+Installing the Textures
+=======================
+If you're running on a machine without the Minecraft client installed, you will
+need to provide the terrain.png file manually for the Overviewer to use in
+rendering your world. This is common for servers.
+
+All Overviewer needs is a terrain.png file. If the Minecraft client is
+installed, it will use the terrain.png that comes with Minecraft. If the
+Minecraft client is not installed or you wish to use a different terrain.png,
+for example a custom texture pack, read on.
+
+You have several options:
+
+* If you have the Minecraft client installed, the Overviewer will automatically
+  use those textures. This is a good solution since the Minecraft Launcher will
+  always keep this file up-to-date and you don't have to do anything extra.
+
+  * If you're running the Overviewer on a server, you can still put the
+    minecraft.jar file (not the launcher) into the correct location and the
+    Overviewer will find and use it, even if the rest of the client files are
+    missing. On Linux, try a command like this::
+
+        wget -N http://s3.amazonaws.com/MinecraftDownload/minecraft.jar -P ~/.minecraft/bin/
+
+* You can manually extract the terrain.png from minecraft.jar or your favorite
+  texture pack. If you've built the Overviewer from source, simply place the
+  file in the same directory as overviewer.py or overviewer.exe. For
+  installations, you will need to specify the path... see the next bullet.
+
+* You can put a terrain.png file anywhere you want and point to its location
+  with the ``--textures-path`` option. This should point to the directory containing
+  the terrain.png, not to the file itself.
+
+Note: the ``--check-terrain`` option is useful for debugging terrain.png issues.
+For example::
+
+    $ ./overviewer.py --check-terrain
+    2011-09-26 21:51:46,494 [INFO] Found terrain.png in '/home/achin/.minecraft/bin/minecraft.jar'
+    2011-09-26 21:51:46,497 [INFO] Hash of terrain.png file is: `6d53f9e59d2ea8c6f574c9a366f3312cd87338a8` 
+
+::
+
+    $ ./overviewer.py --check-terrain --textures-path=/tmp
+    2011-09-26 21:52:52,143 [INFO] Found terrain.png in '/tmp/terrain.png'
+    2011-09-26 21:52:52,145 [INFO] Hash of terrain.png file is: `6d53f9e59d2ea8c6f574c9a366f3312cd87338a8`
+
+Running on a Live Map
+=====================
+If you're running the Overviewer on a live server or a single player world
+that's running, read this section.
+
+Minecraft doesn't really like it when other programs go snooping around in a
+live world, so running Overviewer on a live world usually creates a few errors,
+usually "corrupt chunk" errors. You *can* do this, but it's not a supported way
+of running Overviewer.
+
+To get around this, you can copy your live world somewhere else, and render the
+copied world instead. If you're already making backups of your world, you can
+use the backups to make the render. Many people even use their backups to run
+Overviewer on a different machine than the one running the Minecraft server.
+
+There used to be a few things to be careful about, but right now there's only
+one important thing left.
+
+Preserving Modification Times
+-----------------------------
+
+The important thing to be careful about when copying world files to another
+location is file modification times, which Overviewer uses to figure out what
+parts of the map need updating. If you do a straight copy, usually this will
+update the modification times on all the copied files, causing Overviewer to
+re-render the entire map. To copy files on Unix, while keeping these
+modification times intact, use ``cp -p``. For people who render from backups,
+GNU ``tar`` automatically handles modification times correctly. ``rsync -a``
+will handle this correctly as well. If you use some other tool, you'll have to
+figure out how to do this yourself.