Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Preparing documentation for release v0.19.0 #198

Merged
merged 6 commits into from
Nov 18, 2015
Merged

Preparing documentation for release v0.19.0 #198

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
47c7720
doc: remove options from the README
ftomassetti Nov 16, 2015
c50d5a9
doc: document options in the manual
ftomassetti Nov 16, 2015
54401ff
doc: remove reference to pickle and add reference to hdf5
ftomassetti Nov 16, 2015
32196a7
README: minor
ftomassetti Nov 16, 2015
4dda5e8
README: remove requirements section
ftomassetti Nov 16, 2015
7145804
manual: addressing several comments from tcld
ftomassetti Nov 17, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 7 additions & 46 deletions README.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
WorldEngine - the best open-source world generator
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about "an open-source world generator"?^^

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps we can try to be bold :D

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the change you made further down, going from "is intended to be the best open-source world generator" to "has the goal to be the best open-source world generator", it just sounds more humble. I would vote against boldness for the headline.^^

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, the headline has to be shorter than "is intended to be the best open-source world generator".
I also searched many, many, many, many times for open-source world generator and I could not find any that is comparable to WorldEngine. If I can find one I would change the headline :D

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about this:

WorldEngine - the best open-source world generator*
...
*= Until proven otherwise. :P

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah ah ah, it seems a disclaimer like you see in advertisement :)

==================================================

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