CreateCloudMap
==============
.. image:: https://img.shields.io/pypi/v/CreateCloudMap.svg
:target: https://pypi.python.org/pypi/createcloudmap
.. image:: https://img.shields.io/pypi/pyversions/CreateCloudMap.svg
:target: https://pypi.python.org/pypi/createcloudmap
.. image:: https://img.shields.io/pypi/l/CreateCloudMap.svg
:target: https://pypi.python.org/pypi/createcloudmap
.. image:: https://travis-ci.org/jmozmoz/cloudmap.svg?branch=master
:target: https://travis-ci.org/jmozmoz/cloudmap
Python script to create a cloud map for xplanet using satellite images from the
`Dundee Satellite Receiving Station, Dundee University, UK <http://www.sat.dundee.ac.uk/>`_.
This script can also be installed by pip from `pypi <https://pypi.python.org/pypi/CreateCloudMap>`_.
`xplanet <http://xplanet.sourceforge.net/>`_ can use a cloud map to make the earth look more pretty.
There is a free service which create one such cloud map per day. Due to a temporary unavailability
of that service this script `create_map` was developed to automatically download the necessary geostationary images
from the `Dundee Satellite Receiving Station, Dundee University, UK <http://www.sat.dundee.ac.uk/>`_.
To use this service you need an account there (which is free). Also a new cloud map can be created every three hours.
Set your login information in the configuration file (default name for UNIX-like systems: ``$HOME/.CreateCloudMap/CreateCloudMap.ini``, for Windows: ``%HOME%\.CreateCloudMap\CreateCloudMap.ini``)::
[Download]
username = user
password = secret
tempdir = images
# Use one of the following for resolution: low, medium, high
resolution = medium
purge = false
[xplanet]
destinationdir = xplanet/images
destinationfile = clouds_2048.jpg
width = 2048
height = 1024
[processing]
nprocs = 1
# use either pyresample or cartopy
projection = pyresample
If the configuration file already exists, a new version is copied to ``CreateCloudMap.ini.new`` to not overwrite the login data.
The old config file should work after an update, because default values are used for
newly introduced options.
``tempdir`` specifies the directory where the downloaded images (and if enabled by the command line
switch ``--debug`` or ``-d``) intermediate debug images are stored. ``destinationdir`` specifies the directory where
the output ``destinationfile`` is saved.
``resolution`` can be set to ``low``, ``medium`` or ``high`` to determine the resolution
of the downloaded satellite images.
If ``purge`` is set to true old satellite images will be deleted which are not
used to draw the current cloud map.
``width`` and ``height`` set the dimensions of the cloud map in ``destinationfile``.
``nprocs`` specifies the number of processors to be used for the processing of the
satellite images. If this number is larger than 1 the multiprocessing library
will be used to create separate processes communicating sending back their
results by queues.
``projection`` specifies the Python library used for projecting the geostationary
images onto a flat map. Possible values are ``pyresample`` and ``cartopy``.
``pyresample`` is the standard value and this library is set as dependency, so
it is installed during the installation of ``CreateCloudMap`` (if pip is used to
install it). If ``cartopy`` is used, this library must be installed manually.
``cartopy`` is (currently much) slower than ``pyresample``.
To see all command line options of the script use ``--help``::
$ create_map --help
usage: create_map [-h] [-d] [-c FILE] [-m MAX_AGE] [-f]
optional arguments:
-h, --help show this help message and exit
-d, --debug store intermediate results
-c FILE, --conf_file FILE
Specify config file
-m MAX_AGE, --max_age MAX_AGE
Maximal age of satellite images to download
-f, --force Force to recreate cloud map
Dependencies
............
To automatically install ``cartopy`` use the following command line for pip::
pip install CreateCloudMap[cartopy]
For the debug output to work with the ``pyresample`` projection the
libraries matplotlib and basemap have to be installed. This can be done either
manually or by giving the extra requirement option ``[debug_pyresample]``
when using pip::
pip install CreateCloudMap[debug_pyresample]
For the debug output to work with the ``cartopy`` projection the
library matplotlib is necessary. It can be automatically installed by using
pip::
pip install CreateCloudMap[cartopy,debug_cartopy]
(So if no extra dependency is given the pyresample library will be installed
(if it has not been already installed) and no debug output is possible)
References
..........
A nice description of the concepts forming the basis of this program can be found
at `this blog post <https://apollo.open-resource.org/mission:log:2014:06:17:new-fresh-global-cloudmap-distribution-service-xplanet>`_.