diff --git a/README.rst b/README.rst index df6984f..93e8132 100644 --- a/README.rst +++ b/README.rst @@ -9,13 +9,11 @@ Generates large resolution images of a Minecraft map. In short, this program reads in Minecraft world files and renders very large resolution images. It performs a similar function to the existing Minecraft -Cartographer program. - -I wrote this with an additional goal in mind: to generate large images that I -could zoom in and see details. +Cartographer program but with a slightly different goal in mind: to generate +large resolution images such that one can zoom in and see details. **New**: gmap.py generates tiles for a Google Map interface, so that people -with large worlds can still benefit! +with large worlds and/or limited computer memory can still view their worlds! Requirements ============ @@ -36,37 +34,74 @@ Disclaimers ----------- Before you dive into using this, let it be known that there are a few minor problems. First, it's slow. If your map is really large, this could take at -least half an hour, and for really large maps, several hours. Second, there's -no progress bar. You can watch the tiles get generated, but the program gives -no feedback at this time on how far it is. +least half an hour, and for really large maps, several hours (Subsequent runs +will be quicker since it only re-renders tiles that have changed). Second, +there's no progress bar. You can watch the tiles get generated, but the program +gives no feedback at this time on how far it is. There are probably some other minor glitches along the way, hopefully they will be fixed soon. See the `Bugs`_ section below. Running ------- -To generate a set of Google Map tiles, use the gmap.py script like this: +To generate a set of Google Map tiles, use the gmap.py script like this:: python gmap.py -The output directory must already exist. This will generate a set of image -tiles for your world. When it's done, it will put an index.html file in the -same directory that you can use to view it. +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, +it will put an index.html file in the same directory that you can use to view +it. Note that this program renders each chunk of your world as an intermediate step and stores the images in your world directory as a cache. You usually don't need to worry about this, but if you want to delete them, see the section below about `Deleting the Cache`_. +Also note that this program outputs hash files alongside the tile images in the +output directory. These files are used to quickly determine if a tile needs to +be re-generated on subsequent runs of the program on the same world. This +greatly speeds up the rendering. + +Using more Cores +---------------- +Adding the "-p" option will utilize more cores to generate the chunk files. +This can speed up rendering quite a bit. However, the tile generation routine +is currently serial and not written to take advantage of multiple cores. This +option will only affect the chunk generation (which is around half the process) + +Example:: + + python gmap.py -p 5 + +Crushing the Output Tiles +------------------------- +Image files taking too much disk space? Try using pngcrush. On Linux and +probably Mac, if you have pngcrush installed, this command will go and crush +all your images in the given destination. This took the total disk usage of my +world from 85M to 67M. + +:: + + find /path/to/destination -name "*.png" -exec pngcrush {} {}.crush \; -exec mv {}.crush {} \; + +Windows users, you're on your own, but there's probably a way to do this. (If +someone figures it out, let me know I'll update this README) + Using the Large Image Renderer ============================== The Large Image Renderer creates one large image of your world. This was -originally the only option, but would crash and use too much memory for very -large worlds. You may still find a use for it though. +originally the only option, but uses a large amount of memory and generates +unwieldy large images. It is still included in this package in case someone +finds it useful, but the preferred method is the Google Map tile generator. -Right now there's only a console interface. Here's how to use it: +Be warned: For even moderately large worlds this may eat up all your memory, +take a long time, or even just outright crash. It allocates an image large +enough to accommodate your entire world and then draws each block on it. It +would not be surprising to need gigabytes of memory for extremely large +worlds. -To render a world, run the renderer.py script like this: +To render a world, run the renderer.py script like this:: python renderer.py @@ -78,7 +113,7 @@ Cave mode renders all blocks that have no sunlight hitting them. Additionally, blocks are given a colored tint according to how deep they are. Red are closest to bedrock, green is close to sea level, and blue is close to the sky. -Cave mode is like normal mode, but give it the "-c" flag. Like this: +Cave mode is like normal mode, but give it the "-c" flag. Like this:: python renderer.py -c @@ -88,12 +123,14 @@ The Overviewer keeps a cache of each world chunk it renders stored within your world directory. When you generate a new image of the same world, it will only re-render chunks that have changed, speeding things up a lot. -If you want to delete these images, run the renderer.py script with the -d flag: +If you want to delete these images, run the renderer.py script with the -d flag:: python renderer.py -d To delete the cave mode images, run it with -d and -c +:: + python renderer.py -d -c You may want to do this for example to save space. Or perhaps you've changed @@ -105,7 +142,7 @@ The Overviewer will render each chunk separately in parallel. You can tell it how many processes to start with the -p option. This is set to a default of 2, which will use 2 processes to render chunks, and 1 to render the final image. -To bump that up to 3 processes, use a command in this form: +To bump that up to 3 processes, use a command in this form:: python renderer.py -p 3 @@ -132,7 +169,8 @@ An incomplete list of things I want to fix soon is: * Add lighting -* Speed up the tile rendering. I can parallelize that process, and add more - caches to the tiles so subsequent renderings go faster. +* Speed up the tile rendering. I can parallelize that process. * I want to add some indication of progress to the tile generation. + +* Some kind of graphical interface.