DESCRIPTION
===========

Earthview is a X11 program which can be used to produce a view or an 
image file output of an arbitrary region of the Earth, showing the 
elevation of lands and depth of oceans across the globe. Earthview 
also supports other data types such as the population density.

In order to provide samples to test with, the package contains a
4320x2160 data set for the world population, and low resolution 
1440x720 grid of topographic/bathymetric data.

Earthview is capable of exploiting much higher resolutions,
especially the topographic GTOPO30 data (43200x21600 grid, with arc 
resolution = 30", i.e. better than 1km), as well as the 
topographic/bathymetric ETOPO2 (2' arc resolution) or ETOPO5 
(5' resolution). 

It should be noticed, though, that the uncompressed GTOPO30 data
expand to more than 2 GBytes of hard disk. For this reason, highly
compressed formats (*.az2 and *.pz2) have been introduced.  All above
(GTOPO30, ETOPO2/5) data then fit in a single 480 MBytes .az2
file. The actual structure of the file is a concatenation of bzip2
compressed chunks (typically 720x360 rectangles), preceded with a
header indexing the chunks. In this way, the data can still be
accessed very quickly -- possibly sometimes quicker than would have 
been the uncompressed data. Earthview includes conversion routines 
for those various formats.  Check the DATA FORMAT section for more
details.

Earthview itself only supports PPM output for the images. A conversion
utility, e.g. the ImageMagick package, is needed if you wish to convert 
the PPM image into other image formats such as JPEG or PNG, but it is not 
otherwise needed. 


QUICK INSTALL AND TEST
======================

Compiling Earthview requires the standard X11 libraries and the
libz, libbz2  libraries, together with their header files 'zlib.h' and 
'bzlib.h'.

Edit the top of the Makefile to set the BINPATH and DATAPATH directories,
then type 'make' and (as root) 'make install'

Just type './earthview' to view the included low resolution Earth map.

Type 'make alt' to produce 'altitude.jpg' and 'make pop' to produce
'population.jpg' (ImageMagick is neaded). You can then use any JPEG
capable image viewer to check the output. Since our other program
sunclock (ftp://ftp.ac-grenoble.fr/ge/geosciences/sunclock) can 
be fed with jpeg Earth images, we also provide 'make sun' to view 
the images with sunclock.


USING EARTHVIEW
===============

Earthview will possibly be included in a more sophisticated GIS viewer
at some point in the future. However, it is already possible to use
earthview as a standalone (albeit rather basic) Earth explorer. 
By default
  earthview
(with no option) shows the topographic data in conventional colors, and
  earthview -population
produces a representation of the density of population -- only 
rectangular (longitude, latitude) coordinates are supported in version 1.0
of Earthview.

By default, Earthview ouputs data in a X11 window. The keyboard and mouse
can then be used to navigate on the Earth:

+ - keys: enlarge/reduce the zoom factor.
= key: reset the map to full size
arrow keys: move position
back key: return to previous position
1...9: change the color scheme (to one of the predefined schemes)
C key: commute between topography/population data
D key: darker colors
L key: lighter colors

mouse : - select a rectangular sub area
        - click without moving : move position and translate

The size of the main window can be changed interactively. All actions
take place immediately, even if the previous map is not complete.


COMMAND LINE OPTIONS
====================

The full set of options is 

Usage: earthview [-help] [-verbose] [-population]
         [-nointerp] [-noaspect] [-listheader] [-oceanbit]
         [-w width] [-h height] [-wdata width] [-hdata height]
         [-lon val1 val2] [-lat val1 val2]
         [-londata val1 val2] [-latdata val1 val2]
         [-scheme num] [-range i1,color1,i2,color2...]
         [-data {pop|alt|az2|pz2|gtopo30|gtopo30+}]
         [-endian {data+|data-|out+|out-}]
         [-header {data+|data-|out+|out-}]
         [-output {xwin|raw|ppm|stat}]
         [-pack num1 num2] [-gamma value(0.0...2.0)]
         [-datadir directory] [-file filename] [> outfile.xxx]

The first three options are obvious or already described.

"-nointerp" disables interpolation when the zoom exceeds the available
maximal resolution of the data.

"-noaspect" disables the correction of the distortion occuring at high
latitudes.

"-w width", "-h height" set the size of the output (X11 window or image file)

"-lon val1 val2" "lat val1 val2" sets the Earth rectangle to be displayed.

"-wdata width" "-hdata height" sets the size of the data grid. This is 
superfluous if the data set has a suitable header

"-londata val1 val2" "-latdata val1 val2" sets to which Earth rectangle 
the data set is associated. By default this is
   -londata -180.0 180.0 -lat -90.0 90.0
(full Earth). These options should be used only when viewing partial data of
the Earth.

"-listheader" shows the header of the file (if any), and then exits Earthview

"-oceanbit" enables setting a special bit indicating oceanic points (when
earthview is used as a conversion utility)

"-scheme num" selects the color scheme. There are 4 predefined color 
schemes for topographic data, and 2 schemes for the density of population.
Color specifications should be in the RGB hexadecimal form 0xUVWXYZ
The color range is meant to specify density colors for
i=-12000,...i=+12000, indices i1,i2,... should therefore be in
that interval.

"-range i1,color1,i2,color2..." defines a new color scheme may possibly
extend the predefined ones. Indices i1,i2,...,iN are supposed to be in 
the interval -12000..12000 and written in increasing order. Earthview 
then computes a piecewise linear interpolation of the colors for the 
remaining indices.

"-data {pop|alt|pz2|gtopo30|gtopo30+}" selects the data type. Useful
only when reading raw data containing no headers.

"-endian {data+|data-|out+|out-}" sets the (+ bigendian, - smallendian) 
nature of the input data and of the output. Default is smallendian (-).

"-header {data+|data-|out+|out-}" indicates if the data or output
should have (+) or not have (-) headers.

"-output {xwin|raw|ppm|stat}" determines the nature of the output.
xwin is meant for viewing (X Window) and is the default. Otherwise,
earthview operates as a conversion utility. "raw" stand for
raw binary data, "ppm" for an image in .ppm format (RGB values), "stat"
for statistics only (lowest, highest altitude, lowest, highest
population density, etc).

"-pack num1 num2" indicates that Earthview should convert the output into 
packed bzip2 (num1 x num2) chunks.

"-gamma value" changes the gamma value. 0 means very dark (black), 2.0 
very light (white); 1.0 means normal colors.

"-datadir directory" sets the directory where the default 
topography/* population/* data sets should be found

"-file filename" sets the name of the file data 
($DATAPATH/topography/topography.cps by default). The "-file" switch is 
needed only if filename starts with a "-" and could be confused with an 
option.


DATA FORMATS
============

The available formats for input/output are:

1)  ALT (altitude data, each point value is a 2 byte integer)
2)  POP (population density data, each point value is a 3 byte integer)
1') AZ2 (packed bzip2 compressed chunks of altitude data)
2') PZ2 (packed bzip2 compressed chunks of population data)
3)  GTOPO30  (GTOP30 DEM files)
3') GTOPO30+ (GTOP30 DEM files coupled with ETOPO2 for bathymetry)

(3 and 3' can be used only for input)

ALT and POP formats are raw binary data, possibly preceded by a ASCII 
header, according to a simple syntax delailed below. In case no header
is present, Earthview expects command line options of the form
   -data ?  -wdata ?  -hdata ?  -londata ? ?  -latdata ? ?
to specify tthe type of data, width-height of data (number of rows and 
columns), corresponding region of Earth (full Earth if unspecified)

Syntax of POP/ALT headers
-------------------------

There is first a header with a magic string and some lon/lat and size
information:

@#!POP
source: countraw.ppm
lon/lat: -180.0 180.0 -90.0 90.0
size: 4320 2160

This means that the Earth is divided in 5'x5' cells to form a 
4320x2160 grid. For each cell, the number of inhabitants is encoded as 
an integer n, which is then split in three 8-bit characters
  c1 = high byte(n),  c2 = medium byte(n),  c3 = low byte(n)
("smallendian" ordering by default), up to a total of 
4320 x 2160 x 3 = 27993600 bytes uncompressed.

The syntax is similar for altitude data (the magic string is then @#!ALT).

Syntax of AZ2/PZ2 headers
-------------------------

@#!AZ2
source: 43200x21600,  gtopo30:etopo2
lon/lat: -180.0000 180.0000 -90.0000 90.0000
size: 21600 10800
pack: 30 30

This means here that the file has been produced from a combination of 
the GTOPO30/ETOPO2 source (which have an intrinsic resolution 43200x21600).
The full Earth is covered in lon/lat, but the initial resolution has been 
scaled down to a 21600x10800 grid (1' arc resolution). The data are
arranged in 30x30 = 900 chunks of size 720x360 (notice that 720=21600/30, 
360=10800/30). Each of the 900 chunks has been compressed by the bzip2 
compressor, and these have been concatenated together with an address 
table of 901 4-byte integers (in binary, non readable form), immediately 
before the bz2 chunks start.


DATA SOURCES
============
The original data sets can be obtained from

http://infoserver.ciesin.org/datasets/gpw/ftpgrid.html  (population counts)
http://www.ngdc.noaa.gov/mgg/global/seltopo.html        (ETOPO5)
http://dss.ucar.edu/datasets/ds759.3/data/              (ETOPO2)
http://edcdaac.usgs.gov/gtopo30/gtopo30.html            (GTOPO30)

They are in "raw" form, earthview is able to read them only when called with
the adequate command line options. (Moreover, the original population 
counts are in bigendian order, all other data are smallendian).

Reformatted/compressed data can be obtained from:

ftp://ftp.ac-grenoble.fr/ge/geosciences/earthview_data

QUICK INSTALL
=============

Type 
  'make install'
to install earthview in default INSTALL directory (/usr/X11R6/bin)
and data file in default DATA directory (/usr/share/earthview)
  'make help'
to get a brief help on Earthview, 
  'make alt'
to produce a jpeg output image of altitude/topography data, 
  'make pop'
to produce a jpeg output image of population data, 
  'make sun'
to display the jpeg files with sunclock.

To view the population data, just type
  './earthview -data population.gz'

The 'convert' utility from the ImageMagick package is needed for converting
the PPM files to JPG format. (It could be replaced by any other suitable 
routines for this purpose).


CONVERSION OF DATA
==================

From original sources
---------------------
If you wish to produce by yourself the preferred data format .az2/.pz2
needed by Earthview, download the data sources above.

1) High resolution requires GTOPO30/ETOPO2

Use the included 'tools/expandg30' utility to expand the GTOPO30 data. 
The compressed high resolution '43200x21600-60x60.az2' file is created by
issuing the command

  ./earthview -data gtopo30+ -file <gtopo30_dir>:<etopo2_file> \
              -w 43200 -h 21600 -pack 60 60 -oceanbit -verbose

For '21600x10800-30x30.az2' (1' arc resolution), use 

  ./earthview -data gtopo30+ -file <gtopo30_dir>:<etopo2_file> \
              -w 21600 -h 10800 -pack 30 30 -oceanbit -verbose

2) Medium resolution ETOPO2 is suitable for resolutions 10800x5400 and
below. 

  ./earthview -data alt -file etopo2 -wdata 10800 -hdata 5400 \
              -w 5400 -h 2700 -header data- -pack 10 10 -oceanbit -verbose

will produce '5400x2700-10x10.az2'

3) Low resolution ETOPO5 is suitable for resolutions 4320x2160 and below.

  ./earthview -data alt -file etopo5 -wdata 4320 -hdata 2160 \
              -w 2160 -h 1080 -header data- -pack 3 3 -oceanbit -verbose

will produce '2160x1080-3x3.az2'.


From already formatted data
---------------------------

The basic data from which everything can be reconstructed are :

Topography data:
A1) 43200x21600-60x60.az2    (464 MBytes)
A2) 10800x5400-15x15.az2     (48 MBytes)
A3) 4320x2160-6x6.az2        (7.2 MBytes)

Population data:
P) 4320x2160-6x6.pz2        (801 KBytes)

Of course, if you want to content yourself with 2' arc resolution, A2) is
enough, and for 5' arc resolution A3) is enough. Earthview would run
with, say, A1) alone, but at the expense of being very slow when viewing 
the full Earth, since it would need to uncompress the full data set for 
producing only a very low resolution image. In order to accomodate this, 
it is  recommended to build several intermediate resolutions down to e.g. 
1440x720 or 720x360. This increases the hard disk usage by 50%, up to 
772 MBytes, still only 1/3 of the size of uncompressed data.

The 'tools/fullbuild' included utility can be used to produce the 
intermediate steps. The 'tools/mediumbuild' produces smaller data 
(with the same accuracy but slightly larger loading time) that
still fit on a single CD-Rom. The full build may take hours or more,
depending on your CPU clock, typically 4-5 hours with a 800Mhz 
PentiumIII.

If you want to reconstruct ETOPO2 or ETOPO5 from compressed data, use

  ./earthview -file 10800x5400-15x15.az2 -w 10800 -h 5400 \
              -output raw -header out- -verbose > etopo2

  ./earthview -file 4320x2160-6x6.az2 -w 4320 -h 2160 \
              -output raw -header out- -verbose > etopo5


DOWNLOAD
========
The latest release should be available from
ftp://ftp.ac-grenoble.fr/ge/geosciences/earthview-*.tgz

You may wish also to download the data, available from
ftp://ftp.ac-grenoble.fr/ge/geosciences/earthview_data
or its mirrors.


COPYRIGHT
=========

Earthview is released under the LGPL


AUTHOR
======

Jean-Pierre Demailly <demailly@ujf-grenoble.fr>
July 31, 2002

