181 lines
6.4 KiB
ReStructuredText
181 lines
6.4 KiB
ReStructuredText
====================
|
|
Minecraft Overviewer
|
|
====================
|
|
By Andrew Brown and contributors
|
|
|
|
http://github.com/brownan/Minecraft-Overviewer
|
|
|
|
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 but with a slightly different goal in mind: to generate
|
|
large resolution images such that one can zoom in and see details.
|
|
|
|
See some examples here!
|
|
http://github.com/brownan/Minecraft-Overviewer/wiki/Map-examples
|
|
|
|
(To contact me, send me a message on Github)
|
|
|
|
Features
|
|
========
|
|
|
|
* Renders large resolution images of your world, such that you can zoom in and
|
|
see details
|
|
|
|
* Outputs a Google Map powered interface that is memory efficient, both in
|
|
generating and viewing.
|
|
|
|
* Renders efficiently in parallel, using as many simultaneous processes as you
|
|
want!
|
|
|
|
* Utilizes 2 levels of caching to speed up subsequent renderings of your world.
|
|
|
|
* Throw the output directory up on a web server to share your Minecraft world
|
|
with everyone!
|
|
|
|
Requirements
|
|
============
|
|
This program requires:
|
|
|
|
* Python 2.6 or 2.7 <http://python.org/download/>
|
|
* PIL (Python Imaging Library) <http://www.pythonware.com/products/pil/>
|
|
* Numpy <http://scipy.org/Download>
|
|
|
|
I develop and test this on Linux, but need help testing it on Windows and Mac.
|
|
If something doesn't work, let me know.
|
|
|
|
Using the Overviewer
|
|
====================
|
|
|
|
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
|
|
maps are practically infinite, the maximum time this could take is also
|
|
infinite!)
|
|
|
|
If you press ctrl-C, it will stop. The next run will pick up where it left off.
|
|
|
|
Once your initial render is done, subsequent renderings will be MUCH faster due
|
|
to all the caching that happens behind the scenes. Just use the same output
|
|
directory and it will only update the tiles it needs to.
|
|
|
|
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::
|
|
|
|
python gmap.py <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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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 the
|
|
render for my world from 85M to 67M.
|
|
|
|
::
|
|
|
|
find /path/to/destination -name "*.png" -exec pngcrush {} {}.crush \; -exec mv {}.crush {} \;
|
|
|
|
If you're on Windows, I've gotten word that this command line snippet works
|
|
provided pngout is installed and on your path. Note that the % symbols will
|
|
need to be doubled up if this is in a batch file.
|
|
|
|
::
|
|
|
|
FOR /R c:\path\to\tiles\folder %v IN (*.png) DO pngout %v /y
|
|
|
|
Bugs
|
|
====
|
|
This program has bugs. They are mostly minor things, I wouldn't have released a
|
|
completely useless program. However, there are a number of things that I want
|
|
to fix or improve.
|
|
|
|
For a current list of issues, visit
|
|
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:
|
|
|
|
* 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
|
|
rendered as if they were a cube, so it looks funny.
|
|
|
|
* Add lighting
|
|
|
|
* Some kind of graphical interface.
|
|
|
|
* A Windows exe for easier access for Windows users.
|