Documentation for version 0.1.
EarthView is a set of images and include files for POV-Ray for rendering high-quality images of the Earth's surface. You can use it on any computer that runs POV-Ray, which is just about every computer you might come across. (Windows, Macintosh, Unix, Linux, plus countless more exotic machines.)
First of all, you will need a copy of POV-Ray. You can download it at www.povray.org. The EarthView documentation is written for a POV novice, though it doesn't serve as a replacement for POV documentation. For now, you just need to learn enough about POV to render their sample scenes. It will also be helpful to browse the introductory tutorial in the POV documentation.
Next, render one of the sample EarthView files. You will need to include the EarthView Include directory. Check your POV documentation for instructions on how to do this. Or copy the EarthView files into POV's include directory. This isn't recommended, since it will make it harder to cleanly update POV and EarthView.
Many users will never need to do more than take one of those files and tinker with it. So take the time to play with these files.
Let's take a look at a very simple scene which shows western Europe as seen from directly above London. It includes three mandatory items: the include of earthView.inc, the camera, and the light source. It also draws the Earth and places pins in Berlin and Paris. The scene is shown below and is followed by the text which produces it.
![[The scene image]](images/tutorial.png)
#include "earthView.inc"
#include "worldLocations.inc"
camera {
perspective
location geocentricToCartesian(London_UK+300*z)
look_at geocentricToCartesian(Berlin_DE)
}
light_source {
geocentricToCartesian(Rome_IT+10000*z)
White
}
Earth()
PinMarker(Berlin_DE, texture { pigment { Yellow } }, 1)
PinMarker(Paris_FR, T_Silver_2E, 1)
#include "earthView.inc" #include "worldLocations.inc"
The first two lines tells POV to read the basic EarthView include file, earthView.inc, as well as a file which includes the locations of many major cities. Note that on many systems, proper case is important-- EarthView.inc or earthview.inc won't work. In general POV is case sensitive.
camera {
perspective
location geocentricToCartesian(London_UK+300*z)
look_at geocentricToCartesian(Berlin_DE)
}
The second part describes where the camera is located and where it is pointed. The camera block starts at camera { and ends with the corresponding end-bracket. The inside of the camera block doesn't need to be indented, but indenting makes it easier to read. This is a standard POV-Ray camera, except that it uses cities to define positions.
There are three parts to this camera description: the keyword perspective which describes the kind of camera (this is similar to choosing a camera's lens), the location-- positioning the camera 300 units above London, and the look_at-- pointing it at Berlin.
Later on we'll describe how these coordinates are entered in detail. For now, geocentricToCartesian converts latitude and longitude coordinates into cartesian <X,Y,Z> coordinates, and the +300*z elevates the point by 300 units. The Earth has a radius of 1000 units, so one unit is 6.378 km or 3.963 miles.
light_source {
geocentricToCartesian(Rome_IT+10000*z)
White
}
The next item is the light source. This is your basic POV-Ray light source; it includes a position and a color. It is located 10,000 units above Rome.
Earth()
This line draws the Earth. Omit it and you'll have a picture of pins floating in blank space. The Earth is drawn at <0,0,0> in <X,Y,Z> space. It has a radius of 1000 units. This means that anything you draw less than 1000 units away from <0,0,0> will be buried inside the Earth.
A few rules of thumb to keep you from getting lost in space:
look_at point is, the more of the picture is taken up by the Earth.
If you get a black picture, you've probably violated one of these rules, but it's also possible that the light is directly opposite the camera, rendering the Earth completely black. If you get lost, try adding more light sources, have the camera look_at <0,0,0> (Earth's center), and make sure the camera is well over 1000 units away from <0,0,0>.
PinMarker(Berlin_DE, texture { pigment { Yellow } }, 1)
PinMarker(Paris_FR, T_Silver_2E, 1)
Pictures of the planet are fine, but you probably want to make your mark. There are three built-in markers: PinMarker, TextMarker, and SaturnMarker. In addition, you can draw an arc between two points or place your own POV-Ray object on the Earth.
To place a PinMarker or SaturnMarker, you enter a location, a POV-Ray texture, and a size. A TextMarker additionally requires the text and a rotation value.
Look at the sample file usa.pov for examples of all of these.
Pov-Ray uses Cartesian <X, Y, Z> coordinates. Planetary features are better described using geocentric <Latitude, Longitude, Altitude above sea level> coordinates. Since the Earth is rendered as a perfect sphere, it doesn't make much difference that the altitude is above sea level. The top of Mt. Everest is 1.39 units high, so don't worry about terestrial altitudes. The pins in the scene above are 20 units (79 miles) high.
If you search for latitudes and longitudes on the web, you will find some sites which define positions in degrees and minutes (or even degrees, minutes, and seconds) and others that use decimal degrees. EarthView uses decimal degress. The conversion is simple: 60 minutes to a degree, and 60 seconds per minute. North and East are positive, South and West are negative. EarthView includes a macro which does the conversion for you; writing decimalDegrees(69,12,"S") is equivalent to writing -69.2.
Take a look at afghanistan.pov for examples of decimalDegrees. Its camera's look_at is equivalent to look_at geocentricToCartesian(<0.5167, -69.2, -500>). decimalDegrees doesn't convert seconds; minutes are typically high enough resolution. If you do need seconds, just write your minutes as minutes+(seconds/60).
Let's take a look at a few examples. The sample file tutorial.pov contains the line:
look_at geocentricToCartesian(Berlin_DE)
Using the definition of Berlin_DE in worldLocations.inc, POV converts this line into:
look_at geocentricToCartesian(<52.53, 13.42, 0>)
Next, geocentricToCartesian is resolved, yielding
look_at <-222.169, 793.672, 793.672>
We now have the look_at statement in POV-Ray's native Cartesian coordinates. Let's look at another example, this time from afghanistan.pov. Below is the original statement.
location geocentricToCartesian(<decimalDegrees(36,16,"N"),
decimalDegrees(59,34,"E"), 500>)
The statement then goes through the following changes.
location geocentricToCartesian(<36.267, 59.567, 0>)
location <-1117.886 887.316 887.316>
To summarize:
decimalDegrees(degrees, minutes, "direction").
geocentricToCartesian(geocentric).
The file earthLocations.inc has coordinates for the two poles and lots of cities. Read through the file for a complete listing.
EARTH_ROTATION -- The rotation of the Earth, in degrees of longitude. The default is 0, whereby the X axis is over the Prime Meridian.
This affects everything which uses geocentric coordinates.
Example: #declare EARTH_ROTATION= -98; (with a semicolon at the end of the line) will set the X axis on the equator below the United States.
EARTH_HEIGHT_IMAGE -- The file name of the height map used for the Earth with earthWithHeight(). By default it is a map created by James Hastings-Trew. If you don't like the Earth, you can replace it with an image of Mars or the moon or whatever. Or you can change it in the middle of a POV file (with the appropriate translations) to render multiple planets.
Example: #declare EARTH_HEIGHT_IMAGE= "my_image.png" (with no semicolon) will use an image named "my_image.png".
EARTH_IMAGE -- The file name of the image used for the Earth. By default it is a map created by James Hastings-Trew, orignally found at http://apollo.spaceports.com/~jhasting/images/earthmaps/earthmap2k.jpg. In the past few days, that link hasn't worked. This is the highest resolution free map I know of. If you don't like the Earth, you can replace it with an image of Mars or the moon or whatever. Or you can change it in the middle of a POV file (with the appropriate translations) to render multiple planets.
EARTH_SIZE -- The radius of the sphere used to render the Earth, set at 1000. If you change it things should still work, but all the built-in objects treat it as a constant. Note that the real Earth isn't spherical, rather it bulges at the equator.
KM -- One kilometer, or 6.397 units. Use this for altitude or cartesian coordinates, but not for latitude, longitude, or marker sizes.
Example: PinMarker(Paris_FR+10*KM*z, T_Silver_2E, 1) draws a pin 10km above Paris.
MILE -- One mile, or 3.963 units. Use this for altitude or cartesian coordinates, but not for latitude, longitude, or marker sizes.
Example: PinMarker(Paris_FR+10*MILE*z, T_Silver_2E, 1) draws a pin 10 miles above Paris.
object Arc(gecentric a, gecentric b, float maxHeight, texture theTexture, float theSize) -- Draws a circular arc between points a and b with peak altitude maxHeight and thickness theSize. Actually, it draws a torus with an outer edge passing through a, b, and a center point halfway in between. The center point has altitude maxHeight. The underground portions of the torus are not drawn. Because it is really a torus, it has the following peculiarities.
a and b is less than maxHeight, more than half the torus is above ground, which makes it look less like an arc and more like a wheel.a and b are directly opposite each other on the globe, a "divide by zero" error results, since it cannot calculate a proper center point altitude. Moving one of the starting points by a tiny amount will fix this problem as well as give you control over which way the arc goes around.A and b should both have altitude 0 and maxHeight should be positive. If not, the arc will still do its best to line up with a, b, and the center point, but the result may look strange.
float decimalDegrees(float intDegrees, float minutes, string cardinalDirection) -- Returns a decimal degree for the degrees, minutes, and direction. Only the first character of the direction is used, and it may be upper or lower case. If you do need seconds, just write your minutes as minutes+(seconds/60).
object Earth() -- Draws the globe centered at <0,0,0>. See the description of EARTH_IMAGE for information on changing the picture.
object EarthWithHeight(float height) -- Draws the globe centered at <0,0,0>, using a bump map to elevate the hills and mountains. A height of 1 is the most realistic, but the difference from a flat Earth is unnoticable under all but the most extreme circumstances. Try a value of 10 or more to see any difference. Note that bump maps only affects how light reacts to the surface, not the actual shape of the surface. Thus, the planet will still look spherical at the horizon, and objects will intersect it at sea level. For really funky data visualizations, change the height image to be a map of some data, such as population or light pollution. See the description of EARTH_IMAGE for information on changing the picture.
cartesian geocentricToCartesian( geocentric g ) -- Returns the corresponding cartesian vector for the geocentric vector.
object PinMarker(geocentric g, texture theTexture, vector theSize) -- Draws a pin at location g with a spherical head of texture theTexture. The shaft is silver. A size of 1 (which POV treats as <1,1,1>) is the most common value in the examples.
transformation putOnEarth(geocentric g) -- Returns the transformations required to place an object at location g and facing up.
object SaturnMarker(geocentric g, texture theTexture, vector theSize) -- Draws a sphere with a ring at location g with texture theTexture. Useful when you get tired of pins. A size of 1 (which POV treats as <1,1,1>) is the most common value in the examples.
object TextMarker(geocentric g, texture theTexture, vector theSize, string theText, vector theRotation) -- draws text with g at its lower left-hand corner and with texture theTexture. The text is most legible from directly above and reads from west to east with theRotation=0. Change theRotation's z value to 90 to make it legible from points on the Earth. The text is flat, rather than following the curve of the globe, and with altitude 0 is initially half buried. With a size of 1, strings of a few words will look fine but longer strings will end noticably higher than their beginnings.
EarthView is a work in progress, and you can help out. The easiest thing to do is send me email (david@leppik.net) with comments, ideas, or just to let me know how you use it. I won't continue to improve this if nobody tells me that it's getting used! Also, what features I add will reflect what comments I get back. Features useful to someone using it for Linux-based web log visualization may not be useful to high school geography students running Microsoft Windows.
Because this is open source, you can also make your modifications and share them with anyone you like. If you share them with me, there's a good chance they'll end up in a future release. Here are a few ideas for things you could do to improve EarthView.
EarthView uses images created by James Hastings-Trew, orignally found at http://apollo.spaceports.com/~jhasting/images/earthmaps. This URL went dead a week before the initial release of EarthView. The images listed below are all at least 2000 pixels wide.