overhauled options descriptions in readme

README.rst

@@ -52,7 +52,7 @@ Disclaimers
 -----------
 Before you dive into using this, just be aware that, for large maps, there is a
 *lot* of data to parse through and process. If your world is very large, expect
-the initial render to take at least an hour, possibly more. (Since minecraft
+the initial render to take at least an hour, possibly more. (Since Minecraft
 maps are practically infinite, the maximum time this could take is also
 infinite!)
 
@@ -69,72 +69,102 @@ Running
 -------
 To generate a set of Google Map tiles, use the gmap.py script like this::
 
-    python gmap.py <Path to World> <Output Directory>
+    python gmap.py [OPTIONS] <World Number / Path to World> <Output Directory>
 
 The output directory will be created if it doesn't exist. This will generate a
 set of image tiles for your world in the directory you choose. When it's done,
 you will find an index.html file in the same directory that you can use to view
 it.
 
-Using more Cores
-----------------
-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.
+**Important note about Caches**
+
+The Overviewer will put a cached image for every chunk *directly in your world
+directory by default*. If you do not like this behavior, you can specify
+another location with the --chunkdir option. See below for details.
+
+Options
+-------
+
+-h, --help
+    Shows the list of options and exits
+
+--cachedir=CACHEDIR
+    By default, the Overviewer will save in your world directory one image
+    file for every chunk in your world. If you do backups of your world,
+    you may not want these images in your world directory.
+
+    Use this option to specify an alternate location to put the rendered
+    chunk images. You must specify this same directory each rendering so
+    that it doesn't have to render every chunk from scratch every time.
+
+    Example::
+
+        python gmap.py --cachedir=<chunk cache dir> <world> <output dir>
+
+-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 gmap.py -p 5 <Path to World> <Output Directory>
 
-Specifying the Zoom Level
--------------------------
-The -z option will set the zoom level manually. Without this option, the
-Overviewer will detect the smallest number of zoom levels needed to render your
-entire map.
+-z ZOOM, --zoom=ZOOM
+    The Overviewer by default will detect how many zoom levels are required
+    to show your entire map. This is equivilant to the dimensions 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.
 
-Maybe that's too much though, or maybe you have some outlier chunks that are
-very far off making your map too large to render. That's where this option
-comes in handy.
+    The -z option will set the zoom level manually. This could be useful if
+    you have some outlier chunks causing your map to be too large.
 
     This will render your map with 7 zoom levels::
 
         python gmap.py -z 7 <Path to World> <Output Directory>
 
-The zoom level specifies the number of tiles at the highest zoom level. A zoom
-level of z will generate up to 4^z tiles (2^z by 2^z in a square). This means
-each additional zoom level covers 4 times as much area as the last one. Tiles
-with no content will not be rendered, but they still take a small amount of
-time to process.
+    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.
+
+-d, --delete
+    This option changes the mode of execution. No tiles are rendered, and
+    instead, cache files are deleted.
+
+    Explanation: The Overviewer keeps two levels of cache: it saves each
+    chunk rendered as a png, and it keeps a hash file along side each tile
+    in your output directory. Using these cache files allows the Overviewer
+    to skip rendering of any tile image that has not changed.
+
+    By default, the chunk images are saved in your world directory. This
+    example will remove them::
+    
+        python gmap.py -d <World # / Path to World / Path to cache dir>
+
+    You can also delete the tile cache as well. This will force a full
+    re-render, useful if you've changed texture packs and want your world
+    to look uniform. Here's an example::
+
+        python gmap.py -d <# / path> <Tile Directory>
+
+    Be warned, this will cause the next rendering of your map to take
+    significantly longer, since it is having to re-generate the files you just
+    deleted.
 
 Viewing the Results
 -------------------
-The output is two things: an index.html file, and a directory hierarchy full of
-images. To view your world, simply open index.html in a web browser. Internet
-access is required to load the Google Maps API files, but you otherwise don't
-need anything else.
+Within the output directory you will find two things: an index.html file, and a
+directory hierarchy full of images. To view your world, simply open index.html
+in a web browser. Internet access is required to load the Google Maps API
+files, but you otherwise don't need anything else.
 
 You can throw these files up to a web server to let others view your map. You
 do *not* need a Google Maps API key (as was the case with older versions of the
-API), so just copying the directory to your web server should suffice.
+API), so just copying the directory to your web server should suffice. You are,
+however, bound by the Google Maps API terms of service.
 
-Clearing the Cache
-------------------
-The Overviewer keeps two levels of cache: it saves each chunk rendered
-individually along side your chunk files in your saved world directory, and it
-keeps a hash file along side each tile in your output directory. Using these
-cache files it will not re-render any image that has not changed.
-
-If you want to clear the cache and re-render everything, run gmap.py with the
--d option::
-
-    python gmap.py -d <Path to World> <Output Directory>
-
-The next time your map is rendered, it will re-render every chunk. This is
-useful if you've changed texture packs or want to save disk space, but
-otherwise not too useful.
-
-This is probably *not* a good idea for very large worlds, since it will take
-much longer to render the next time you do so.
+http://code.google.com/apis/maps/terms.html
 
 Crushing the Output Tiles
 -------------------------
@@ -167,7 +197,9 @@ http://github.com/brownan/Minecraft-Overviewer/issues
 Feel free to comment on issues, report new issues, and vote on issues that are
 important to you, so I can prioritize accordingly.
 
-An incomplete list of things I want to fix soon is:
+An incomplete list of things I want to do soon is:
+
+* Improve efficiency
 
 * Rendering non-cube blocks, such as torches, flowers, mine tracks, fences,
   doors, and the like. Right now they are either not rendered at all, or

gmap.py

@@ -29,6 +29,7 @@ import quadtree
 
 helptext = """
 %prog [OPTIONS] <World # / Path to World> <tiles dest dir>
+%prog -d <World # / Path to World / Path to cache dir> [tiles dest dir]
 """
 
 def main():
@@ -37,7 +38,7 @@ def main():
     except NotImplementedError:
         cpus = 1
     parser = OptionParser(usage=helptext)
-    parser.add_option("-p", "--processes", dest="procs", help="How many chunks to render in parallel. A good number for this is the number of cores in your computer. Default %s" % cpus, default=cpus, action="store", type="int")
+    parser.add_option("-p", "--processes", dest="procs", help="How many worker processes to start. Default %s" % cpus, default=cpus, action="store", type="int")
     parser.add_option("-z", "--zoom", dest="zoom", help="Sets the zoom level manually instead of calculating it. This can be useful if you have outlier chunks that make your world too big. This value will make the highest zoom level contain (2**ZOOM)^2 tiles", action="store", type="int")
     parser.add_option("-d", "--delete", dest="delete", help="Clear all caches. Next time you render your world, it will have to start completely over again. This is probably not a good idea for large worlds. Use this if you change texture packs and want to re-render everything.", action="store_true")
     parser.add_option("--cachedir", dest="cachedir", help="Sets the directory where the Overviewer will save chunk images, which is an intermediate step before the tiles are generated. You must use the same directory each time to gain any benefit from the cache. If not set, this defaults to your world directory.")
@@ -69,6 +70,7 @@ def main():
         if options.delete:
             return delete_all(cachedir, None)
         parser.error("Where do you want to save the tiles?")
+
     destdir = args[1]
 
     if options.delete:

world.py

@@ -75,6 +75,7 @@ class WorldRenderer(object):
 
         # Translate chunks to our diagonal coordinate system
         mincol, maxcol, minrow, maxrow, chunks = _convert_coords(raw_chunks)
+        del raw_chunks # Free some memory
 
         self.chunkmap = self._render_chunks_async(chunks, procs)