Skip to content

Commit

Permalink
Merge pull request #198 from Mindwerks/documentation_v0_19
Browse files Browse the repository at this point in the history 
Preparing documentation for release v0.19.0
  • Loading branch information
@ftomassetti
ftomassetti committed Nov 18, 2015
2 parents 7a062f7 + 7145804 commit 187e720
Show file tree
Hide file tree
Showing 3 changed files with 106 additions and 49 deletions.
53 changes: 7 additions & 46 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Interoperability (Python, Java)

We would love to see WorldEngine used together with other tools. Worlds generated by WorldEngine can be loaded into python applications using WorldEngine itself as a library. Java applications can instead use [WorldEngine-Java](https://github.com/Mindwerks/worldengine-java), a java library to load WorldEngine files.

Worlds can be saved using pickle or protobuf format, for which there are libraries in several languages. We keep working on supporting more formats and always interested in ways to improve interoperability.
Worlds can be saved using the protobuf format or hdf5, for which there are libraries in several languages. We keep working on supporting more formats and always interested in ways to improve interoperability.

Binary packages
===============
Expand Down Expand Up @@ -104,50 +104,16 @@ The program produces a binary format with all the data of the generated world an

![](https://raw.githubusercontent.com/Mindwerks/worldengine-data/master/images/examples/world_seed_1_ocean.png)

There are several optional outputs and many options to control the result. The [manual](http://worldengine.readthedocs.org/en/latest/) is your friend!

Usage
=====

```
worldengine [options] [world|plates|ancient_map|info]
```
_Note that options were changed in version 0.5.3_

### General options

| Short | Long | Description |
|-----------|------|-------------|
| -o DIR | --output-dir=DIR | generate files in DIR default = '.' |
| -n STR | --worldname=STR | set world name to STR |
| -b | --protocol-buffer | save world using protocol buffer format (smaller file) |
| -s N | --seed=N | use SEED to initialize the pseudo-random generation |
| -t STR | --step=STR | use STEP to specify how far to proceed in the world generation process. Valid values are: plates precipitations full |
| -x N | --width=N | WIDTH of the world to be generated |
| -y N | --height=N | HEIGHT of the world to be generated |
| -q N | --number-of-plates=N | number of plates |
| | --recursion-limit=N | you need that just if you encounter an error while generating very large maps |
| -v | --verbose | Enable verbose messages |
| --bw | --black-and-white | Draw maps in black and white |

### Options valid only for generate

| Short | Long | Description |
|-----------|------|-------------|
| -r FILE | --rivers=FILE | produce a map of rivers, after the option it expects the name of the file where to generate the map |
| --gs | --grayscale-heightmap | produce a grayscale heightmap |
| | --ocean_level=N | elevation cut off for sea level (default = 1.0) |
| | --temps #/#/#/#/#/#| Provide alternate ranges for temperatures. [default = .126/.235/.406/.561/.634/.876] |
| | --humidity #/#/#/#/#/#/# | Provide alternate ranges for humidities. [default = .059/.222/.493/.764/.927/.986/.998] |
| -gv N | --gamma-value N | N = Gamma value for temperature/precipitation gamma correction curve. [default = 1.25] |
| -go N | --gamma-offset N | N = Adjustment value for temperature/precipitation gamma correction curve. [default = .2] |
| | ---not-fade-borders | avoid fading borders |

### Options valid only for ancient map operations

| Short | Long | Description |
|-----------|------|-------------|
| -w FILE | --worldfile=FILE | WORLD_FILE to be loaded |
| -g FILE | --generatedfile=FILE | name of the GENERATED_FILE |
| -f N | --resize-factor=N | resize factor |

For details about all the possible options please refer to the [manual](http://worldengine.readthedocs.org/en/latest/).

For example these commands:

Expand Down Expand Up @@ -307,11 +273,6 @@ You can write us at:
* psi29a _at_ gmail _dot_ com
Thank you, all the feedback is precious for us!

Requirements
============

Libjpeg, libtiff and zlib are required by Pillow

Projects using WorldEngine
==========================

Expand All @@ -324,10 +285,10 @@ If you are using WorldEngine please let us know!
Contributors
============

The merged project is maintained by [Bret Curtis](https://github.com/psi29a) and [Federico Tomassetti](https://github.com/ftomassetti).
This project is maintained by [Bret Curtis](https://github.com/psi29a) and [Federico Tomassetti](https://github.com/ftomassetti).

All contributions, questions, ideas are more than welcome!
Feel free to open an issue or write in our [google group](https://groups.google.com/forum/?hl=en#!forum/lands_worldsynth).
Feel free to open an issue or write in our [google group](https://groups.google.com/forum/?hl=en#!forum/worldengine).

We would like to thank you great people who helped us while working on WorldEngine and the projects from which it was derived:

Expand Down
98 changes: 97 additions & 1 deletion manual/cli.rst
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,100 @@
Command line interface
======================

Using the command line you can issue one single command and let WorldEngine generate a world for you.
Using the command line you can issue one single command and let WorldEngine generate a world for you.

worldengine [options] [world|plates|ancient_map|info]


General options
~~~~~~~~~~~~~~~

+------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------+
| Short | Long | Description |
+============+======================+===============================================================================================================================+
| -o DIR | --output-dir=DIR | generate files in DIR default = '.' |
+------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------+
| -n STR | --worldname=STR | set world name to STR |
+------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------+
| | --hdf5 | save world using protocol buffer format [default: protocol buffer format ] |
+------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------+
| -s N | --seed=N | use SEED to initialize the pseudo-random generation |
+------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------+
| -t STR | --step=STR | use STEP to specify how far to proceed in the world generation process. Valid values are: plates precipitations full |
+------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------+
| -x N | --width=N | WIDTH of the world to be generated |
+------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------+
| -y N | --height=N | HEIGHT of the world to be generated |
+------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------+
| -q N | --number-of-plates=N | number of plates |
+------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------+
| | --recursion-limit=N | you need that just if you encounter an error while generating very large maps |
+------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------+
| -v | --verbose | Enable verbose messages |
+------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------+
| | --version | Display version information |
+------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------+
| --bw | --black-and-white | Draw maps in black and white (currently affects only the precipitation and temperature maps) |
+------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------+


Options valid only for generate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+-----------+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| Short | Long | Description |
+===========+============================+================================================================================================================================================+
| -r FILE | --rivers=FILE | Produce a map of rivers, after the option it expects the name of the file where to generate the map |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| --gs | --grayscale-heightmap | Produce a grayscale heightmap |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| | --ocean_level=N | Elevation cut off for sea level [default = 1.0] |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| | --temps #/#/#/#/#/# | Specify the quantiles used to identify the temperature levels. It should contains values in [0,1]. [default = .126/.235/.406/.561/.634/.876] |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| | --humidity #/#/#/#/#/#/# | Specify the quantiles used to identify the humidity levels. It should contains values in [0,1]. [default = .059/.222/.493/.764/.927/.986/.998] |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| -gv N | --gamma-value N | N = Gamma value for temperature/precipitation gamma correction curve. [default = 1.25] |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| -go N | --gamma-offset N | N = Adjustment value for temperature/precipitation gamma correction curve. [default = .2] |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| | ---not-fade-borders | Avoid fading borders |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| | --scatter | Generate temperature vs. humidity scatter plot |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+
| | --sat | Generate satellite map |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------------------------------------------------+

Options valid only for ancient map operations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+-----------+----------------------------+------------------------------------------------------------------------------------------------------+
| Short | Long | Description |
+===========+============================+======================================================================================================+
| -w FILE | --worldfile=FILE | WORLD_FILE to be loaded |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------+
| -g FILE | --generatedfile=FILE | name of the GENERATED_FILE |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------+
| -f N | --resize-factor=N | resize factor |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------+
| | --sea_color | help="string for color [blue|brown], [default = brown] |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------+
| | --not-draw-biome | Not draw biome |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------+
| | --not-draw-mountains | Not draw mountains |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------+
| | --not-draw-rivers | Not draw rivers |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------+
| | --draw-outer-border | Draw outer land border |
+-----------+----------------------------+------------------------------------------------------------------------------------------------------+

Export options
~~~~~~~~~~~~~~

+-----------+----------------------------+--------------------------------------------------------------------------------------------------------------------------------+
| Short | Long | Description |
+===========+============================+================================================================================================================================+
| | --export-format=FORMAT | Export to a specific format such as BMP or PNG. See http://www.gdal.org/formats_list.html for possible formats [default = PNG] |
+-----------+----------------------------+--------------------------------------------------------------------------------------------------------------------------------+
| | --export-datatype=TYPE | Type of stored data, e.g. uint16, int32, float32 etc. [default = uint16] |
+-----------+----------------------------+--------------------------------------------------------------------------------------------------------------------------------+
4 changes: 2 additions & 2 deletions manual/index.rst
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
WorldEngine - the best open-source world generator
==================================================

WorldEngine is intended to be the best open-source world generator available. It is based on the simulation of several physical phenomens.
WorldEngine has the goal to be the best open-source world generator available. It is based on the simulation of several physical phenomens.

Our philosophy is to build a tool very flexibile, which can be used from the command line, in a GUI or as a component inside other programs.

WorldEngine can be very easy to use: you click a button and you get a nice world generated for you.

It can also be very complex: do you want to set specific temperature or humidity ranges for your world? Specify a strange ratio for your map? You can.

We think a great that most advanced users could want to use WorldEngine as a part of larger tool-chain: you give some draft of your world to WorldEngine, it performs some extra simulations for you, making your world more realistic, and then you feed the result from WorldEngine into another tool of yours or perhaps you refine manually your results.
We think that most advanced users could want to use WorldEngine as a part of larger tool-chain: you give some draft of your world to WorldEngine, it performs some extra simulations for you, making your world more realistic, and then you feed the result from WorldEngine into another tool of yours or perhaps you refine manually your results.

So WorldEngine can be used in different ways. Let's see how.

Expand Down

0 comments on commit 187e720

Please sign in to comment.