From e29731fef3f32dfd0b9acd03ec72c584baf15fc0 Mon Sep 17 00:00:00 2001 From: Andrew Brown Date: Mon, 24 Oct 2011 16:36:19 -0400 Subject: [PATCH] Stripped README of redundant info, added some to docs index --- README.rst | 306 +++++-------------------------------------------- docs/index.rst | 38 +++++- 2 files changed, 64 insertions(+), 280 deletions(-) diff --git a/README.rst b/README.rst index 3e22ea1..e46c711 100644 --- a/README.rst +++ b/README.rst @@ -3,63 +3,41 @@ Minecraft Overviewer ==================== By Andrew Brown and contributors (see CONTRIBUTORS.rst). -http://github.com/overviewer/Minecraft-Overviewer +Documentation: + http://docs.overviewer.org -Generates large resolution images of a Minecraft map. +Github code repository: + http://github.com/overviewer/Minecraft-Overviewer -In short, this program reads in Minecraft world files and renders very large -resolution images that can be viewed through a Google Maps interface. 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/overviewer/Minecraft-Overviewer/wiki/Map-examples +The Minecraft Overviewer is a command-line tool for rendering high-resolution +maps of Minecraft worlds. It generates a set of static html and image files and +uses the Google Maps API to display a nice interactive map. -Further documentation may be found at -https://github.com/overviewer/Minecraft-Overviewer/wiki/Documentation +The Overviewer has been in active development for over a year and has many +features, including day and night lighting, cave rendering, mineral overlays, +and many plugins for even more features! It is written mostly in Python with +critical sections in C as an extension module. -To contact the developers and other users, go to the site at the top of this -README, or go to #overviewer on irc.freenode.net. +Getting Started +--------------- +All documentation has been consolidated at our documentation site. For +information on downloading, compiling, installing, and running The Overviewer, +visit the docs site. -Features -======== +http://docs.overviewer.org -* Renders large resolution images of your world, such that you can zoom in and - see details +A few helpful tips are below, but everyone is going to want to visit the +documentation site for the most up-to-date and complete set of instructions! -* Customizable textures! Pulls textures straight from your installed texture - pack! +Alternatively, the docs are also in the docs/ directory of the source download. +Look in there if you can't access the docs site. -* Outputs a Google Map powered interface that is memory efficient, both in - generating and viewing. +Examples +-------- +See examples of The Overviewer in action! -* Renders efficiently in parallel, using as many simultaneous processes as you - want! - -* Utilizes 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 -* PIL (Python Imaging Library) -* Numpy -* Either the Minecraft client installed, or a terrain.png file. See the - `Textures`_ section below. -* A C compiler. - -If you download a binary package, then some or all of these may not be required. - -Using the Overviewer -==================== - -For a quick-start guide, see -https://github.com/overviewer/Minecraft-Overviewer/wiki/Quick-Start-Guide +https://github.com/overviewer/Minecraft-Overviewer/wiki/Map-examples Disclaimers ----------- @@ -78,204 +56,6 @@ 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. -Textures --------- -The Overviewer uses actual textures to render your world. However, I don't -include textures in the package. You will need to do one of two things before -you can use the Overviewer: - -* Make sure the Minecraft client is installed. The Overviewer will find the - installed minecraft.jar and extract the textures from it. - -* Install a texture file yourself. This file is called "terrain.png" and is - normally found in your minecraft.jar file (not "Minecraft.jar", the launcher, - but rather the file that's downloaded by the launcher and installed into a - hidden directory). You can also get this file from any of the third party - texture packs out there. - -Biome Tinting -------------- -With the Halloween update, biomes were added to Minecraft. In order to get -biome-accurate tinting, the Overviewer can use biome data produced by the -Minecraft Biome Extractor tool. This tool can be downloaded from: -http://www.minecraftforum.net/viewtopic.php?f=25&t=80902 - -If the "biomes" folder is present in the world directory, then the Overviewer -will use the biome data to tint grass and leaves automatically -- there is no -command line option to turn this feature on. If this folder does not exist, -then the Overviewer will use a static tinting for grass and leaves. - -Compiling the C Extension -------------------------- -The C Extension for Overviewer is no longer optional. In addition to -providing a higher quality image compositing function that looks better on -maps with lighting enabled, it now does the bulk of the rendering. - -If you downloaded Overviewer as a binary package, this extension will already -be compiled for you. - -If you have a C compiler and the Python development libraries set up, you can -compile this extension like this:: - - python setup.py build - -Note that you need the development headers for your version of Python installed, -look for a package named 'python-dev', 'python-devel' or similar. Also, some -Python distributions do not install "Imaging.h" and "ImPlatform.h" properly. If -you get errors complaining about them, you can get them from the PIL source, or -at . Just put them in -the same directory as "overviewer.py". - -For more detailed instructions, check the wiki: -https://github.com/overviewer/Minecraft-Overviewer/wiki/Build-Instructions - -Running -------- -To generate a set of Google Map tiles, use the overviewer.py script like this:: - - python overviewer.py [OPTIONS] - -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. - - -Options -------- - --h, --help - Shows the list of options and exits - ---advanced-help - Display help - including advanced options - --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 - --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 - ---forcerender - Force re-rendering the entire map (or the given regionlist). This - is an easier way to completely re-render without deleting the map. - ---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! - ---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. - ---list-rendermodes - List the available render modes, and a short description of each. - ---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. - ---settings=PATH - Use this option to load settings from a file. The format of this file is - given below. - - -Settings --------- - -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. - Viewing the Results ------------------- Within the output directory you will find two things: an index.html file, and a @@ -290,44 +70,12 @@ however, bound by the Google Maps API terms of service. http://code.google.com/apis/maps/terms.html -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 {} \; - -Or if you prefer a more parallel solution, try something like this:: - - find /path/to/destination -print0 | xargs -0 -n 1 -P sh -c 'pngcrush $0 temp.$$ && mv temp.$$ $0' - -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/overviewer/Minecraft-Overviewer/issues +https://github.com/overviewer/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 do soon is: - -* Improve efficiency - -* Some kind of graphical interface. +important to you. diff --git a/docs/index.rst b/docs/index.rst index 956e68c..57b1663 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,9 +21,45 @@ For a simple example of what your renders will look like, head over to `The "Exmaple" Map `_. For more user-contributed examples, see `The Example Wiki Page `_. -Download +Features ======== +* Renders large resolution images of your world, such that you can zoom in and + see details + +* Customizable textures! Pulls textures straight from your installed texture + pack! + +* 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 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 is a quick list of what's required to run The Overviewer. It runs on +Windows, Mac, and Linux as long as you have these software packages installed: + +* Python 2.6 or 2.7 + +* PIL (Python Imaging Library) + +* Numpy + +* Either a Minecraft Client installed or a terrain.png for the textures. + +There are additional requirements for compiling it. More details are available +in either the :doc:`Building ` or :doc:`Installing ` pages. + +Getting Started +=============== + The Overviewer works with Linux, Mac, and Windows! We provide Windows and Debian built executables for your convenience. Find them as well as the full sources on our `Github Homepage`_.