Here are some C++ programs I wrote a little while ago for generating basic map projections.

Feel free to mail me with any comments, problems, complaints etc.

It all currently runs on Unix only, though could probably be ported to Windows without too much trouble (it will compile and run with the cygwin tools though). Use of the ImageMagick tools (available for Windows and Unix) is highly recommended. Interface is command line only; of course a little TCL front end would be nice.

You will also need some suitable image files to work with. Space Graphics have some excellent examples, which can be freely downloaded for non-commercial use (clearly they are very nice people at Space Graphics).

Images need to be converted to .ppm format, this is easily done using the ImageMagick mogrify utility, eg:

mogrify -format ppm earth.jpg

converts earth.jpg to earth.ppm.

PPM is a simple uncompressed format (which is why we use it), but the images can take up a lot of disk space. Space Graphics' excellent e43 shaded map for example, is a little over 100M as a PPM file (compared to about 5M as a JPEG). Smaller images (and images of Mars) are available from there. The software uses mmap to memory map the input files, so we don't have the overhead of reading in the entire file to project eg. just a small portion of it. There may be different versions of the ppm format, we expect version 6 (I think). Files should begin something like:

P6
2048 1024
255
...

First line of header is format identifier, followed by size in pixels and color depth, followed by packed data bytes, 3 bytes per pixel for as long as it takes.

To unpack and build the relevant executables:

$ tar xvzf mmps.tgz
$ cd mmps
$ make

Additionally:

make ppms

converts any .jpg images in the images subdirectory to ppm format.

If compilation has gone smoothly,

make test

will try an example projection, displaying the result with the ImageMagick display utility. The test target assumes there is file called earth.ppm in your images subdirectory.

make startest

tests the starmap projection feature.

General options for Stars and Project

Currently MMPS supports the following projections, specified as a command line parameter:

• latlong - unprojected, or Plate Carree
• equalarea - cylindridal.
• sinusoidal.
• sinusoidal2 - sinusoidal with a flat bit in the middle.
• mollweide - projecting into an ellipse.
• mercator - conformal cylindrical.
• azimuthal - polar, radial distance equal to angle.
• orthographic - polar, projection from infinity.
• rectilinear - same as orthographic.
• stereographic - conformal polar, projection from "south pole".
• gnomonic - polar, projection from globe centre.
• perspective - perspective view.
• bonne - a rather nice heart-shaped projection.

Most of the maths for the projection is home grown, so I may well have got some things wrong. The Bonne equations, as well as some other things, are taken from the splendid MathWorld site, so are more likely to be correct. Mathworld is an excellent source of general information about map projections and all kinds of other wonderful stuff.

Other general parameters:

• -bg r:g:b Background color to use. r,g,b are integers, 0-255
• -grid, -gridx, -gridy Draw a grid on the map. Gridx and gridy specify the spacing (in degrees) between the grid lines.
• -gridcolor r:g:b Specify the color of the grid lines.
• -scale A scaling factor to apply to the image - larger scale factor means larger image.
• -w Output image width in pixels.
• -h Output image height in pixels.
• -p Reference parallel for projections that can use it: equalarea, sinusoidal, mollweide.
• -adjust Adjust the image size to take into account projection dimensions. Effect depends on projection.

Project

Usage: project [-bg r:g:b][-w n][-h n][-adjust]
    [-f filename][-out filename][-back filename]
    [-tilt x][-turn x][-lat x][-long x]
    [-scale x][-x x][-y x][-z x][-ox x][-oy x][-oz x]
    [-a x][-date x][-time x][-p x][-aw x]
    [-conic x][-conicr x][-xoff x][-yoff x][-sun]
    [-grid][-gridx x][-gridy y][-gridcolor r:g:b]
    latlong|equalarea|sinusoidal|sinusoidal2|
    mollweide|mercator|azimuthal|rectilinear|
    orthographic|stereographic|gnomonic|
    perspective|bonne <infile>

Using the data in the image specified by the -f option (or images/earth.ppm if no file specified), generate a projected image in PPM format and write to standard output.

Not all options are covered here.

Latitude and longitude of the central point of the map are specified with the -lat and -long parameters, in degrees, longitude measured to the east. The -tilt specifies a rotation about the centre point and the -turn parameter specifies a vertical rotation of the image.

-f specifies the input file to use. As described above, this should be a ppm file, for correct result in Plate Carree projection (ie. x is longitude, y is latitude). Default is images/earth.ppm.

Examples

project equalarea -p 45 -adjust -grid | display

Equal area cylindrical projection. Reference parallel at 45 degrees. Adjust image size so as to fit. This is the so-called Peters projection.

project gnomonic -scale 2 -lat 50 -long -50 -grid | display

Gnomonic projection, centred on North Atlantic. Note how projection turns great circles in to straight lines.

Perspective

The -x, -y and -z parameters specify the viewing position, measured in planet radii. Illumination from the sun may be simulated with the -sun parameter, in which case the -date and -time parameters are relevant. Date is days from the spring equinox and time is GMT (or UTC, the precise timescale probably doesn't matter at this scale) hours from midnight, in decimal hours (so 4.5 is half past four in the morning). The equation of time, angular radius of the sun etc. is taken in to account, so I hope that the terminator position is fairly accurate (this is why sunrise isn't precisely at 6-00 on the spring equinox).

Oblateness may be changed with the -ox, -oy and -oz parameters, in case you want a picture of Jupiter or just a mildly amusing view of earth:

project perspective -lat 40 -long 30 -x 8 -sun -date 88 -time 3.83 -oz 0.8 | display

Inverse mapping

In order to generate a lat-long map from a projected image or photograph, the -i option may be used:

project -i <options> -f <file1> > <file2>

which should project the image in file1 to file2, just as if file2 had been projected from file1 with:

project <options> -f <file2> > <file1>

(apart from rounding errors and the incompleteness of some projections). See Generating maps from images with MMPS and Generating maps from images with MMPS, Part II for further details.

Stars

Usage: stars [-bg r:g:b][-w n][-h n][-adjust]
    [-f filename][-out filename][-back filename]
    [-year x][-magfact x][-topmag x][-bv][-bvfact x]
    [-tilt x][-turn x][-dec x][-ra x]
    [-scale x][-x x][-y x][-z x]
    [-a x][-date x][-time x][-p x][-aw x]
    [-conic x][-conicr x][-xoff x][-yoff x]
    [-grid][-gridx x][-gridy y][-gridcolor r:g:b]
    latlong|equalarea|sinusoidal|sinusoidal2|
    mollweide|mercator|azimuthal|rectilinear|
    orthographic|stereographic|gnomonic|
    perspective|bonne

Using the data in the starlist on standard input, generate a projection image in PPM format and write to standard output.

Not all options are covered here.

The stars executable projects an image of the stars using the chosen projection. For star projection Right Ascension (-ra)and Declination (-dec) are used to determine the centre of the image. RA measured in decimal hours to the west and declination in decimal degrees. The star data (in starlist) is taken from the Bright Star Catalogue mangled in to a more easily readable (by scanf) form. The format is more or less:

• Magnitude.
• BV Colour Value.
• RA, decimal hours.
• Declination, decimal degrees.
• RA proper motion, arcsecs per year.
• Declination proper motion, arcsecs per year.
• Comment string with catalogue number and abbreviated name.

The program reads the starlist from standard input, so we can do, for example:

cat starlist | grep Ori | stars stereographic -ra 5.5 -dec 0 -scale 5 | display

to just display the stars in Orion.

A slightly naff attempt to show star colour based on the BV value can be switched on with the -bv option.

The code

The code implements both forward and backwards projection - the former for drawing grid lines and stars, the latter for projecting maps. The marvellous comments in the code might provide some help as to how it all works.

Key files are:

• project.cpp: the main driver program for map projection
• stars.cpp: the main driver program for star projection
• transform.h, transform.cpp: the details of the projections
• equations.h, equations.cpp: various mathematical and astronomical utilities.
• image.h, image.cpp: image manipulation.
• matrix.h, matrix.cpp: 3 x 3 matrix manipulation.
• utils.h, utils.cpp: option and error handling.

Legal stuff

Usual disclaimers; you'll be lucky if this software doesn't make your hard disk explode etc. GPL applies. I wrote this stuff for fun and will be happy if anyone finds it useful. Needless to say, commercial use without permission will be frowned upon, but to be honest I'm unlikely to actually do anything about it (and maybe secretly flattered).