======================================================================>
======================================================================>

The PP3 program for drawing celestial maps.
*******************************************

PP3 generates celestial charts of high (typo)graphical quality. It uses LaTeX + pstricks for this, so the end formats are EPS and PDF (in contrast to mere bitmaps).

The program automatically avoids labels that overlap, and you can change many parameters.  You can place arbitrary text on the map using the flexibility of the LaTeX language.

This manual is for PP3 (version 1.3.2), which is a celestial charts drawing tool.

Copyright © 2002--2004 Torsten Bronger <bronger@users.sourceforge.net>.

     This documentation is free software; you can redistribute it and/or modify it under the terms of the MIT licence.  Please see the COPYING file of the PP3 distribution for further information.

Introduction
************

What it is
==========

There are many programs that can create stellar maps.  But none of them reaches PP3's typographic and graphical quality.  In contrast to other programs PP3 produces vector images (e.g. PDFs) rather than mere bitmaps.  Therefore it is perfectly suited for creating illustrations for books or other print media.  But even converted to bitmaps for web pages, it exceeds usual quality.

PP3 is optimised for the semi-automatic generation of large sets of sky maps.  It has decent default behaviour, however it can be customised very flexibly.  It tries to take as much fine-tuning work away from you as possible.

What it is not
==============

But I must also point out what PP3 is not.  It cannot help you to professionally prepare your next observation night, nor is PP3 a visualisation tool for astronomical databases, with pop-up window information for every sky object on the screen.

In fact, PP3 not even has a graphical user interface.  So don't expect any windows at all, and your mouse will be useless.  Instead, PP3 reads from one file and writes to another file.  (This is done not only because its author was lazy but because it increases efficiency, too.)  So, the program itself is quite stinted, but its results are worth it!

Online resources
================

Further information about PP3 beyond this manual and downloads on the Internet:

http://pp3.sourceforge.net
     PP3's homepage.

http://sourceforge.net/projects/pp3
     PP3's project page with quick links to downloads.

Download area (http://sourceforge.net/project/showfiles.php?group_id=71469)
     List of all downloadable files, also for older versions.

Bug data base (http://sourceforge.net/tracker/?atid=531401&group_id=71469)
     Here you can see open bugs, make comments, and report new bugs that you've found.

Discussion forums (http://sourceforge.net/forum/?group_id=71469)
     Ask questions about PP3 here.

Feature requests (http://sourceforge.net/tracker/?atid=531404&group_id=71469)
     Suggest new features and improvements here.

Please login when you use one of the services on Sourceforge.  It makes responding easier.

Successful use of PP3
=====================

PP3 has been used in real life already and has proven its helpfulness.

Wikipedia
---------

PP3 has created the celestial maps of all 88 constellations on Wikipedia (http://www.wikipedia.org), the free encyclopedia.  Feel free to browse through a list of all constellations (http://wikipedia.org/w/wiki.phtml?title=List_of_constellations).

This is a web page, so you need bitmaps (as long as we don't have SVG), and a short Gimp (http://www.gimp.org) script (which is included into the distribution) helped me to convert PP3's EPS vector output to PNG bitmaps.  Additionally, this script creates smaller thumbnail version for all charts that exceed a certain width.

The result is that one can create all maps plus their thumbnails with one simple command call:

     make

Surely it can't become simpler.  You may retort ``Well, but creating the maps must have been the actual work''.  Of course it was, but first it took only 10--15 minutes per map, because much work is done by the default behaviour of PP3 itself.  And secondly:

French Wikipedia
----------------

Several months later the French division of Wikipedia (http://fr.wikipedia.org) wanted to translate the maps to French.  They wanted another background colour and French labels and constellation names. They provided me with a translation table.  It took me three hours to adjust the scripts, to run make again, and to upload the ZIP file with all the demanded bitmaps.  See for example the Scorpius entry (http://fr.wikipedia.org/wiki/Scorpion_(constellation)).

h2g2
----

Originally PP3 was written for a project on h2g2 (http://www.bbc.co.uk/h2g2/guide/), an edited Internet encyclopedia.  Unfortunately the BBC editors wanted very small bitmaps that would not have been helpful, and they were too lazy to include all the 88 bitmaps.  So the project died, but on a smaller scale (for ten constellations or so), it indeed motivated authors to contribute articles about constellations.  The maps were externally linked.

Installation
************

You can get the latest PP3 file releases from PP3's project page on Sourceforge (http://sourceforge.net/projects/pp3).  The main PP3 distribution comes as several files, namely

pp3-VERSION-win.zip
     is the complete Windows distribution.

pp3-VERSION-1tb.i386.rpm
     is the complete Linux RPM distribution.  (There is also the corresponding source RPM called pp3-VERSION-1tb.src.rpm.)

pp3-VERSION.tar.bz2
     is the complete source distribution.

pp3-VERSION-cripple.tar.gz
     is a partial source distribution.  Milky Way, Nebulae, and the CWEB source code are omitted.

Obviously you need only one of these files.

Installation on Windows
=======================

Although PP3 runs independently of other programs, it is not useful when it's alone.  It needs two external tools in order to work properly: TeX and Ghostscript.

You need not know how to use TeX and Ghostscript!

On most Unix/Linux systems TeX and Ghostscript are already installed. But on Windows, you have to install them yourself.  Fortunately this is not difficult, and both programs may be useful for other purposes, too.

Getting TeX
-----------

TeX is a mighty typesetter.  PP3 calls TeX in order to actually create the stellar map.  The result is a Postscript file.

There are two major TeX variants for Windows, namely MikTeX (http://www.miktex.org) and TeX Live (http://www.tug.org/texlive/).  Both are rather similar in their functionality, and both come with a nice installation tool.  Please assure that the PSTricks package as part of TeX is installed, however this is highly probable anyway.

Getting Ghostscript
-------------------

The best tool for dealing with Postscript files is Ghostscript (http://www.cs.wisc.edu/~ghost/doc/AFPL/get811.htm). In particular, if you've installed Ghostscript, PP3 is able to generate PDF files for you.  It is wise (although not necessary) to install GSView (http://www.cs.wisc.edu/~ghost/gsview/get45.htm), too.  It lets you view arbitrary Postscript files on screen.

Installation of PP3 itself
--------------------------

When TeX and Ghostscript are in the right place, you finish the installation by unpacking the PP3 ZIP file and copying its content in the proper directories:

 1. Copy pp3.exe to an arbitrary directory that is in your PATH.

 2. Copy all the other files to one single arbitrary directory.  Then set the environment variable PP3DATA to this directory.

For the sake of simplicity, I recommend to copy everything to C:\Programs\pp3 and to set your PATH environment variable to

     OLD PATH;C:\Programs\pp3

and to set the PP3DATA environment variable to C:\Programs\pp3.  That's it.

Installation on Linux
=====================

Before you install PP3, ensure that TeX and Ghostscript are installed.

RPM installation
----------------

You should consider to use the RPM file, because it is the simplest installation.  It works for SuSE Linux and probably also for RedHat.  Just enter (as root)

     rpm -i RPM-FILE-NAME

That's it.

Building from sources
---------------------

(Actually you can compile the sources on Windows, too (of course), but since most people who do compile are Linux users, I dare to put it in the Linux section.)

PP3 is written in CWEB.  This is special form of C++ and can be transformed to real C++ trivially.  You only need the CWEB programs (http://www-cs-faculty.stanford.edu/~knuth/cweb.html) installed.  For your convenience the C++ code of PP3 is included into the source distribution, so you need CWEB only if you want to modify the program.

There is no configure script.  Just call make and (as root) make install.  Before that, you may want to adjust some paths in the Makefile.

PP3 looks for its data files (all files with the .dat extension) in a special directory that is pre-compiled in the executable.  The Makefile assures that this is the correct one, but you can override that at runtime with the environment variable PP3DATA.

Increase TeX's memory
=====================

There is exactly one object that can need a lot of memory: the Milky Way.  Therefore it's switched off by default.  But if you want to see the Milky Way on your maps, you probably should set the main memory size of your TeX distribution to its maximal value.  This is very implementation specific.  With teTeX (Linux) you have to find the file texmf.cnf and set `main_memory.latex' to 7500000. Then call (as root)

     fmtutil --byfmt latex

With fpTeX/TeXLive (Windows) it's the same.

MikTeX however (Windows too) is different.  Look for a directory called localtexmf.  Then create the file (It may be necessary to create the sub directories, too.) localtexmf\miktex\config\miktex.ini and write

     mem_max=7500000

in it.

Alternatively (albeit not cleanly), look for an existing file called miktex.ini and change the line with mem_max to the above.

These are the most common TeX variants.  For others please have a look in the manual of your TeX distribution for definitive information.

Basic astronomical terms
************************

The following is a mere crash course.  It is supposed to enable you to use PP3 even if you didn't know how astronomers describe the sky.

Readers competent in astronomy may skip it, although Constellations and Catalogues contain minor program peculiarities, too.

Celestial coordinate system
===========================

On a sheet of paper, every point has an x and a y coordinate.  On planet Earth, every location has a longitude and a latitude.

With a very similar system astronomers give the coordinates of every point in the sky.  The sky longitude is called rectascension and the sky latitude is called declination.  There is a sky North Pole (near the Polar Star), a sky South Pole, and a sky equator.  You can make globes of the sky like of the Earth, with the only difference that you must imagine being inside the globe.

So, in a way, the rectascension is the x coordinate.  It is given in `hours' (h) from 0h to 24h.  Since the sky is circular, both 0h and 24h are the same rectascension, and 12h is the opposite to it.

Usually the fraction of the rectascension that is smaller than 1h is given in minutes and seconds, however in PP3 the rectascension is one decimal fraction number.

The declination corresponds to the y coordinate.  It is measured from -90^\circ (South Pole) over 0^\circ (equator) to +90^\circ (North Pole).

The system of magnitudes
========================

Theoretically you could measure the brightness of stars in candela like the brightness of a light bulb.  But this is rather awkward.  Instead, astronomers use the system of magnitudes (m).

The brighter a star, the smaller is its magnitude.  Sirius is the brightest star in the sky, and its brightness is -1.6m. Vega has a brightness of 0.0m, and Polaris, the Pole Star, of 2.0m.  The faintest stars that you can see with the naked eye in a very clear sky have 6m.

The faintest stars in the standard catalogue of PP3 are of approx. 7m, however extremely good terrestrial telescopes can see up to 22m.

Constellations
==============

Since the 1930s, the sky is officially divided into 88 constellations. At that time, the boundaries between the constellations were clearly defined, too: namely by the coordinates of sky points that, when connected with their respective neighbours, create the boundaries.

Every constellation has a Latin name and a three letter abbreviation. For example ``Orion -- Ori'', or ``Ursa Major -- UMa'' (Great Bear), or ``Hydrus -- Hyi'' (Male Water Snake).  This abbreviation plays a big role in PP3 because it's the only way to denote a constellation. You must use only uppercase letters in the abbreviation: ORI, UMA, HYI.

One constellation, the snake or ``Serpens'', is divided into two parts, ``Serpens Caput'' (Head) and ``Serpens Cauda'' (Tail).  They are abbreviated SER1 and SER2 in PP3.  If you say SER only, you mean both parts.

Catalogues: Flamsteed, Henry Draper, NGC/IC and Messier
=======================================================

When you use PP3 you have to tell the program e.g. which star you want to delete from the map or which nebula shall get a different label.  For this, every sky object must have a distinct name in PP3.

By and large there are two kinds of objects in the sky: stars and nebulae.  Astronomers have created many catalogues of them.  There are two star catalogues and three nebulae catalogues supported in PP3.

Denoting stars
--------------

The two star catalogues are the Flamsteed and the Henry Draper (HD) numbers.  Flamsteed gave numbers beginning with `1' to stars in each constellation.  The Flamsteed catalogue is small and doesn't contain the complete southern sky.  In contrast to that, the HD catalogue doesn't distinguish between constellations, it covers the whole sky, and also contains faint stars.  However the HD names are harder to read.

For example Rigel, \beta Ori, can be identified in PP3 with either

     ORI 19

where `ORI' is Rigel's constellation (Orion) and `19' the Flamsteed number; or with

     HD 34085

where `34085' is Rigel's Henry Draper catalogue number.  Both are totally equivalent.  The free program Celestia (http://www.shatters.net/celestia/) is very useful for finding Flamsteed or HD numbers.

Denoting nebulae
----------------

The two nebula catalogues NGC and IC are complementary, i.e. they don't have (well, shouldn't have) any nebulae in common.  For example, the North America Nebula is called `NGC 7000' and the Orion Nebula is 'NGC 1976'.  The IC catalogue usually contains fainter objects.

Parallel to that there is the much older and much smaller Messier catalogue, abbreviated `M'.  For example, the Orion Nebula can also be called 'M 42', whereas the North America Nebula isn't included in Messier's catalogue.

Pay attention to

  * the catalogue abbreviation in all uppercase and

  * the space between the catalogue abbreviation and the number.

Usage
*****

Starting PP3
============

Invoking PP3 is very straightforward.  Since it is a command line program you only have to call it somehow and give a so-called input script as the parameter, see Input scripts.  For example, entering

     pp3 orion.pp3

on the command line starts PP3 and lets it generate the file orion.pdf, which is a PDF file with a star map of Orion.  You can view this PDF with Acrobat Viewer, convert it to a bitmap, or you can embed it into a text of yours.

Actually there are three possible output formats.  By default, PP3 generates a LaTeX file in the current directory.  But most people cannot do much with it, therefore certain commands in the input script trigger EPS or PDF output, see Output control.

PP3 can't generate bitmaps.  If you need bitmaps you must use an appropriate program (e.g. GSView or the Gimp (http://www.gimp.org)) for converting the vector data to bitmaps.

Using pipes
===========

Especially on Unix it is very common to read from standard input and to write to standard output.  I don't think that this is sensible for PP3, but anyway, I included this facility.  If you give `-' as the only parameter, PP3 reads the input script from standard input, and if you don't give an output filename in the input script (see Input scripts), PP3 writes to standard output.

Writing input scripts
*********************

Input scripts are the most important part of PP3, at least for the user.  They contain some sort of wishlist about the map that you want PP3 to create.

Minimal example input script
============================

The minimal PP3 input script is -- well -- the empty file.  Then PP3's default values create a dark blue star map of Orion:

Constellation map of Orion

You can override these defaults step by step.  Let's do so: Write

     # Cygnus, the Swan

     filename output swan.tex
     switch pdf_output on

     set center_rectascension  19.95
     set center_declination    40.8

to the file swan.pp3 and call

     pp3 swan.pp3

The result of these only four lines of input is a file swan.pdf in the current directory with a star map of the Swan.

The lines of swan.pp3 are not difficult to explain:  The very first line is a comment.  Everything that starts with a # is a comment.  You can write descriptive text in them to make the file more readable.

The line

     filename output swan.tex

makes PP3 write the generated map to the file swan.tex. But such a file is rarely the desired output.  Therefore the next line

     switch pdf_output on

tells PP3 that we want to have a PDF file.  So PP3 does everything necessary for that.  And finally,

     set center_rectascension  19.95
     set center_declination    40.8

denotes the area of the sky that we want to be displayed.  Both values indicate the celestial point that we want to have in the centre of the map.  In this case, 19.95h rectascension and +40.8^\circ declination which is the centre of the constellation Swan.  See List of all constellations, for a complete list of all constellations, along with their coordinates and more.

More bells and wistles
======================

Let's continue with our Swan example of the previous section.

Normally the Milky Way is switched off, because it consumes a lot of memory, see Increase TeX's memory.  However it looks rather nice, so let's switch it on:

     switch milky_way on

Maybe you want to use the map in a book that is supposed to be printed in black and white.  Then the current colour scheme is disadvantageous. The following lines redefine it:

     color nebulae                 0    0    0
     color background              1    1    1
     color grid                    0.5  0.5  0.5
     color ecliptic                0.3  0.3  0.3
     color constellation_lines     0.7  0.7  0.7
     color labels                  0    0    0
     color boundaries              0.8  0.8  0.8
     color highlighted_boundaries  0    0    0
     color milky_way               0.5  0.5  0.5

Colours are given as red--green--blue values, for further information see Colours.  With these redefinitions, all elements on the map are printed either in black or in shades of grey.

A special problem are stars.  With

     color stars 0 0 0

stars are printed in black colour, one could think.  But this is not always true.  By default, stars get their `real' colour according to their B-V brightness.  For example, Saiph in Orion is a little bit blue, while Antares in Scorpius is known to be red.  Therefore PP3 ignores any `color' directive for stars, unless you also say

     switch colored_stars off

Last but not least you should change the highlighted constellation.  By default, it's Orion.  But we want to highlight the Swan, so we say

     set constellation CYG

because ``Cyg'' is the astronomical abbreviation of the Swan (``Cygnus'' in Latin).  Highlighting means that its borderline gets another colour.

This is the map that results from all this (I removed the Milky Way from this figure in order to keep the PDF manual small):

Constellation map of the Swan

Dimensions and scale
====================

When you include a map in a text of yours, usually you can scale the graphics to fit your needs.  The exact procedure depends on the program you use of course.  Such additional scaling is helpful, but actually it should be superfluous since PP3 can deliver the map with the desired size.

The parameters

     set box_width 10
     set box_height 5

set the width of the map to 15cm and the height to 10cm. (By the way, all dimensions are given in centimetres in PP3.) The only thing that's still missing is the scale of the map.  It is set with

     set grad_per_cm 6

which sets it to 6 degrees per centimetre.  With the current projection method (the equidistant azimuthal projection), the given scale is only exactly true for the centre of the map.  Towards the rim there is a slight magnification (and distortion).

Parameters and Commands
=======================

Every PP3 file can contain parameters and commands.  So far, we've had parameters only.  Both types of keywords must be neatly separated in the input script.  First come the parameters, then the special keyword

     objects_and_labels

and then the commands.  The purpose of the commands is adding and deleting objects and their labels, to reposition the labels, and to add arbitrary text on the map.  You can also change the contents of automatically generated labels.

Labels
======

My personal experience is that the most difficult part of writing input scripts is to fiddle about with labels.  Although PP3 does most of the labelling work on its own, it is not perfect (yet).  Thus you will value the features described in this section.

Please note how the texts themselves must be given: Either they don't contain any spaces or line breaks.  Then you can just enter them.  But if they do contain such white space, you must enclose them with quotes "...".  For example, you say

     set_label_text HD 128620 Toliman

but

     set_label_text HD 128620 "Rigil Kent"

If you (must) use quotes, and only then, you have to enter two symbols in a special way, namely the backslash \ and the quotes ":

     set_label_text HD 128620 "\\footnotesize Toliman"

prints Toliman with small letters, see LaTeX in labels. Quotes must be entered as \".

Changing label texts
--------------------

I change the label for Deneb, the alpha star in the Swan.  At the moment, its label is a simple `\alpha'.  But Deneb has a real name, and with

     set_label_text CYG 50 Deneb

I change the label text to ``Deneb''.  This `CYG 50' is the astronomical name for Deneb, see Denoting stars.

You can use that also for changing the label for a nebula:

     set_label_text NGC 7000 "N. America Neb."

As said, please note that you have to enclose the label text in quotation marks if it contains spaces.

Now we get (only the changed part printed):

Map of North America Nebula and Deneb

PP3 takes star names from a file.  PP3's standard file contains only the astronomical symbols for the stars (Bayer's Greek letters and Flamsteed numbers), so if you want to have real star names, you must use `set_text_label' as above.  Or you use another star data file with PP3, see Stars data file.

Deleting and adding labels
--------------------------

PP3 decides which labels are printed on the map by itself.  But, of course, you can configure this behaviour, and you can delete or add any label.

For example, the command

     delete_labels NGC 884  NGC 869  TAU 27 ;

deletes the labels for the nebulae NGC884 and NGC869, and for the star 27Tau from the map.  The nebulae and the star themselves remain on it of course. Correspondingly,

     add_labels CNC 65  CNC 47  CNC 43  CNC 48 ;

adds the currently set labels texts for the stars 65, 47, 43, and 48Cnc.  All of them are too faint to get their labels implicitly.

But you can also influence labels globally in the parameters section of the input script.  If you don't want to have any labels at all, simply say

     switch labels off

in the parameters section.  Another parameter keyword is

     set faintest_star_with_label_magnitude 2.0

which means that only stars of brightness of at least 2.0m get an implicit (automatic) label.

Reposition labels
-----------------

If you think that PP3 mispositioned a label you can change that with `reposition':

     reposition M 39  S ;

This puts the label for the nebula M39 below the nebula. `S' means `south'.  The following table shows all possible values, however you know it by and large from the windrose probably:

E
     prints the label to the right.

NE
     prints the label to the upper right.

N
     prints the label to the top.

NW
     prints the label to the upper left.

W
     prints the label to the left.

SW
     prints the label to the lower left.

S
     prints the label to the bottom.

SE
     prints the label to the lower right.

(see The keyword `towards', for a figure visualising these abbreviations.  But be careful since this figure is actually intended for the towards keyword.)

Using `reposition' is also necessary if PP3 has suppressed a label because it hadn't found a good place for it. `reposition' forces a label to be printed.

Text labels
-----------

Changing existing labels is a nice thing to do, however sometimes you want to add arbitrary text on the map, e.g. `Pleiades' or `Virgo galaxy cluster'.  For all user defined text there is the keyword `text'.  For example,

     text "Virgo galaxy cluster" at 12.7 10
       color 0.0 0.0 0.9333 towards SE ;

This places the text `Virgo galaxy cluster' at the celestial coordinates 12.7h rectascension and +10^\circ declination in blue colour.  See Colours, for how to denote colours in PP3.

The keyword `towards'
.....................

In a text label, after the keyword towards, you can say in which direction, seen from the celestial coordinates given after the at keyword, the label should be printed.  The following figure illustrates the ten possible values after towards:

Possible values for `reposition' and `towards'

The `X' marks the spot that lies exactly on the celestial coordinates given after the `at' keyword.  Actually there are two other possible values, namely `W_' and `E_' that can be seen only in the printed or HTML version of this manual.  They are like `W' and `E' except that the X lies on the text baseline rather than the centre of the vertical edge.

The default value for towards is NE, so if you don't use towards, PP3 places the text label to the upper right.  In particular, PP3 does not perform any algorithm for finding the best position for the label as it does with automatically generated labels.

For some nice tricks with text lables and towards, see LaTeX in labels.

Using flexes
------------

But the `text' keyword can do more.  When you include the keywords `along declination' the label becomes a flex. This is printed along a declination circle as a curved text.  It's especially nice for constellation names.  So let's try it out:

     text "\\bfseries Swan" at 20.05 49.8 along declination towards SW ;

This `\\bfseries' tells the typesetter to print it in bold face, see LaTeX in labels.  The result is the following:

Map of Swan with a flex label

Tic mark labels
---------------

But `text' can do even more.  With

     text "$#3$" at 0 20 along declination
                 tics rectascension 1 towards N ;
     text "$#5$" at 11 0 along declination
                 tics declination 10 towards S ;

you create automatic tic mark labels at the +20^\circ declination circle and the 11h rectascension circle.  See Tic mark labels, for more information about these placeholders like #3. Typically you will embed the placeholders in $...$, because this tells the underlying TeX typesetting engine to typeset the number as a formula.  This makes it look nicer.

Deleting and adding stars and nebulae
=====================================

Sometimes you have to remove stars or nebulae from the map, especially because they collide with other objects.  If you've already read how to change labels, this is very straightforward.  You remove sky objects with `delete' and add them with `add'.  Both commands take a list of objects that is ended with a semicolon ;:

     delete LEO 63  HD 97605 ;
     add NGC 6992 ;

The `add' command is useful mostly for nebulae, because by default, PP3 only includes all objects of the Messier catalogue, but only other objects with a minimal brightness, see Filtering by brightness.

Penalty scheme
==============

It is a tricky task to place labels on a dotty star map without creating to many overlaps, and especially overlaps with other labels are very annoying.  Therefore PP3 tries to avoid that.

It does so by using a penalty algorithm: It tests the eight windrose positions around the respective object, and calculates the resulting overlaps for each position.  The overlaps are counted as penalties.  The position with the smallest penalty value is chosen.  In very bad cases when the penalties exceed a certain threshold, the label is not printed at all.

All of this can be overruled by the user, but normally the standard behaviour is good enough.  So read this section only if you are really keen to know how it works.

Basics about penalties
----------------------

PP3 calculates overlaps with all objects on the map: stars, nebulae, constellation lines, boundary lines, and -- last but not least -- other labels.  All overlaps are weighted, and their sum is the penalty value.  You can influence the weighting.  By default, it's 1000 for all objects.  But with

     penalties stars 2000

you double the significance of stars.  Thus you make overlaps of labels with stars less probable.  In contrast,

     penalties boundaries 0

tells PP3 that printing a label on a boundary line isn't bad at all. (Avoid negative values, although PP3 doesn't reject
them.  They wouldn't make sense anyway.)

The rim
-------

Each label has a core area, which is the text area itself, and a rim, which is an area around the text area.  Both are rectangles, separated by a skip that is the same as the one that separates labels and their respective celestial object, see Other layout parameters.

Diagram of core and rim of a label

PP3 takes both rim and core into account.  The relative significance of the rim can be set with e.g.

     penalties rim 2000

which doubles the default value of 1000.  With

     penalties rim 0

the rim loses its effect completely.  Notice that PP3 adds rim penalties also for the whole core area, so that the core is always more significant than the rim, no matter how you set the penalty values.

What's the point in the rim?  The core avoids overlaps, but the rim is supposed to make approximations of labels with other things on the map less probable.

You may have noticed that the rim overlaps with the object (star or nebula) itself.  Usually this only adds some sort of bias to the penalty values of the diagonal positions, but this direct contact is particularly useful for double stars: There both components get ``their'' label on ``their'' side due to the small rim overlaps with the respectively other component.

Overlaps with line objects
--------------------------

``Line objects'' means constellation lines and boundary lines. PP3 treats both of them in a special way: When they collide with the rim of a label, it's less bad than for non-line objects.  The reason is that lines are so different from labels visually, that it's not fatal if they are rather close together.

The two new penalties that are used for the rim are constellation_lines_rim and boundaries_rim.  Their default value is 1000 as usual.  For example, with

     penalties boundaries_rim 0

you tell PP3 that a label directly next to a boundary line is totally okay for you.

Penalty threshold
-----------------

Sometimes a certain region of the map is so much crowded with stars, nebulae, labels, and more, that there simply is no space left for yet another label.  In this case the penalty value reaches a very high number.  If it exceeds a given threshold, PP3 suppresses that label.  You can still override this, see Reposition labels.

You can set this threshold with

     penalties threshold 3000

Again, 1000 is the default value.

Keywords reference
******************

On PP3's project page (http://sourceforge.net/projects/pp3) you can download a neat reference card.  If you fold it twice it is a handy zigzag.

General structure
=================

The outline of a PP3 input script is:

     # Some introductory comments,
     # i.e. what the file is about to do.

     SECTION I: PARAMETERS: OUTPUT FORMAT AND GLOBAL STYLE.

     objects_and_labels

     SECTION II: COMMANDS: DELETE/ADD/MODIFY OBJECTS AND/OR LABELS

Setting Parameters
==================

All keyword here are parameters.  This means that they are allowed only in the first part of an input script, i.e. before the objects_and_labels command (if there is one).

Essential parameters
--------------------

Map view, scale, and size
.........................

 -- Parameter: set center_rectascension rectascension
 -- Parameter: set center_declination declination
     Set the rectascension and declination of the centre of the map to RECTASCENSION (in hours) and DECLINATION (in degrees) respectively.

     Defaults: 5.8 (RECTASCENSION), 0.0 (DECLINATION)

 -- Parameter: set box_width width
 -- Parameter: set box_height height
     Set the width and height of the resulting map to WIDTH and HEIGHT (in centimetres) respectively.

     Defaults: 15 (WIDTH), 15 (HEIGHT)

 -- Parameter: set grad_per_cm scale
     Set the scale of the resulting map to SCALE (in degrees per centimetre).

     Default: 4.0

Setting what file should be created
...................................

 -- Parameter: filename output filename
     The resulting map will be written to the file FILENAME in LaTeX format.  It must have the file extension .tex.  If FILENAME is empty the map will be written to standard out.

     Default: "" (empty)

 -- Parameter: switch eps_output on/off
     If on, PP3 creates a PDF file.  (Additionally to the LaTeX and EPS files that you then can ignore.)

     Default: off

 -- Parameter: switch pdf_output on/off
     If on, PP3 creates an EPS file.  (Additionally to the LaTeX file that you then can ignore.)

     Default: off

The highlighted constellation
.............................

 -- Parameter: set constellation abbreviation
     Highlight the constellation that is given by ABBREVIATION (given with all-uppercase letters).  If you don't want to hightlight anything, set it to "" or to an invalid abbreviation.

     At the moment, highlighting means that the boundaries of the respective constellation get another colour, see Colours.

     Default: ORI

Switching things on or off
--------------------------

 -- Parameter: switch milky_way on/off
 -- Parameter: switch nebulae on/off
 -- Parameter: switch grid on/off
 -- Parameter: switch ecliptic on/off
 -- Parameter: switch boundaries on/off
 -- Parameter: switch constellation_lines on/off
 -- Parameter: switch labels on/off
     Print or don't print the respective (class of) object(s) on the map. `Grid' means the coordinate grid, `boundaries' are the borderlines of the constellations, and `constellation lines' denote the lines between the brightest stars that are supposed to help to see the shape of a constellation.

     Defaults: off (Milky Way), on (all others)

 -- Parameter: switch colored_stars on/off
     If switched on, all stars get a colour that represents their real colour according to their spectral class.  This may be unsuitable on a bright background since most stars are pretty white.

     If switched off, all stars get the colour given by `color stars', see Colours.

     Default: on

Filtering stars and nebulae by their brightness
-----------------------------------------------

 -- Parameter: set faintest_cluster_magnitude magnitude
     Don't print open star clusters that are fainter than MAGNITUDE.

     Default: 4.0

 -- Parameter: set faintest_diffuse_nebula_magnitude magnitude
     Don't print nebulae that are fainter than MAGNITUDE.  In this case, `nebulae' is meant in the narrower sense, i.e. no stellar clusters.

     Default: 8.0

 -- Parameter: set faintest_star_magnitude magnitude
     Don't print stars that are fainter than MAGNITUDE.

     Default: 7.0

 -- Parameter: set faintest_star_with_label_magnitude magnitude
     Only stars that have a brightness of at least MAGNITUDE get an automatically generated label.

     Default: 3.7

 -- Parameter: set faintest_star_disk_magnitude magnitude
     Only stars that have a brightness of at least MAGNITUDE will be printed as more than just dots.

     Default: 4.5

 -- Parameter: set minimal_star_radius radius
     Set the RADIUS (in centimetres) of the dots that are used for the faintest stars.

     Default: 0.015

Colour, line style, and other layout
------------------------------------

Colours
.......

In PP3, colours are given by their red--green--blue values (also called the RGB colour scheme).  Every value is between 0 and 1.  For example, `1 0 0' is red, `0 0 1' is blue, `0 0 0' is black and `1 1 1' is white.

For shades of grey all three values must be the same.  So a medium grey is `0.5 0.5 0.5'.  For further examples have a look at the following default values.

 -- Parameter: color background red green blue
     Set the background colour of the map to the given colour.

     Default: 0  0  0.4  (dark blue)

 -- Parameter: color grid red green blue
     Set the coordinate grid colour to the given colour.

     Default: 0  0.298  0.447  (dark blue-grey)

 -- Parameter: color ecliptic red green blue
     Set the ecliptic line colour to the given colour.

     Default: 1  0  0  (red)

 -- Parameter: color boundaries red green blue
     Set the ordinary constellation boundaries colour to the given colour.

     Default: 0.5  0.5  0  (dark yellow)

 -- Parameter: color highlighted_boundaries red green blue
     Set the highlighted constellation boundaries colour to the given colour. See Highlighted constellation.

     Default: 1  1  0  (yellow)

 -- Parameter: color constellation_lines red green blue
     Set the constellation lines colour to the given colour.

     Default: 0  1  0  (green)

 -- Parameter: color milky_way red green blue
     The Milky Way is printed in shades of different colour, representing its brightness.  The darkest areas of the Milky Way get the background colour, and the brightest the colour that you give here.

     The Milky way must be switched on of course in order to savour it, which is not the case by default, see Switching things on or off.

     Default: 0  0  1  (blue)

 -- Parameter: color nebulae red green blue
     Set the colour of the nebulae circles to the given colour.

     Default: 1  1  1  (white)

 -- Parameter: color stars red green blue
     Set the colour of all stars to the given colour.  Please note that this only has effect if the switch `colored_stars' is off, see Switching things on or off.

     Default: 1  1  1  (white)

 -- Parameter: color labels red green blue
     Set the colour of automatically generated labels to the given colour.

     Default: 0  1  1  (cyan)

 -- Parameter: color text_labels red green blue
     Set the colour of user defined labels to the given colour.

     Default: 1  1  0  (yellow)

Line styles and widths
......................

 -- Parameter: line_style grid style
 -- Parameter: line_style ecliptic style
 -- Parameter: line_style boundaries style
 -- Parameter: line_style highlighted_boundaries style
 -- Parameter: line_style nebulae style
 -- Parameter: line_style constellation_lines style
     Set the line style of the respective object to STYLE.  Possible values are none, solid, dashed, and dotted.

     Defaults: solid (grid, nebulae, constellation lines), dashed (ecliptic, boundaries)

 -- Parameter: line_width grid width
 -- Parameter: line_width ecliptic width
 -- Parameter: line_width nebulae width
 -- Parameter: line_width boundaries width
 -- Parameter: line_width highlighted_boundaries width
 -- Parameter: line_width constellation_lines width
     Set the line width of the respective object to WIDTH (in centimetres).

     Defaults: 0.025 (grid), 0.018 (ecliptic, nebulae), 0.035 (boundaries, constellation lines)

Other layout parameters
.......................

 -- Parameter: set shortest_constellation_line length
     Set the length of the shortest constellation line that is printed to LENGTH (in centimetres).  All constellation lines shorter than LENGTH are suppressed.

     Default: 0.1

 -- Parameter: set label_skip length
     Set the distance between the outer rim of the celestial object and its label to LENGTH (in centimetres).

     Default: 0.06

 -- Parameter: set minimal_nebula_radius radius
     All nebulae that would be smaller than RADIUS centimetres are printed with a radius of exactly RADIUScm.

     Default: 0.1

 -- Parameter: set star_scaling factor
     Make all star circles FACTOR times bigger than normal.

     Default: 1

 -- Parameter: set fontsize size
     Set the default font size to SIZEpt.  SIZE may be 10, 11, or 12.

     Default: 10

Implementing a global style
---------------------------

 -- Parameter: filename include filename
     If non-empty, the file FILENAME is interpreted as a PP3 input script and read before the keywords in the current script are interpreted.  This enables you to enforce global style parameters and other commands for all maps in a set of maps.  The included script must not include yet another file.

     Please note that PP3 looks for the included file in the current directory, and not in the directory where the main input script is.

     Default: "" (empty)

 -- Parameter: filename latex_preamble filename
     If non-empty, the contents of the file FILENAME is included at an appropriate position in the resulting LaTeX file.  This enables you to use arbitrary LaTeX macros to customise the map, see LaTeX preamble.

     Default: "" (empty)

Penalties
---------

 -- Parameter: penalties stars penalties
 -- Parameter: penalties labels penalties
 -- Parameter: penalties nebulae penalties
 -- Parameter: penalties boundaries penalties
 -- Parameter: penalties constellation_lines penalties
     Set the penalties for an overlap of a label with the respective object to PENALTIES.

     Defaults: 1000 (all)

 -- Parameter: penalties rim penalties
     Set the significance of an overlap with the label's rim relatively to the label's core to PENALTIES.

     Note that the rim can never become more significant than the core, because the rim penalties add to the core penalties while calculating the core.

     Default: 1000

 -- Parameter: penalties boundaries_rim penalties
 -- Parameter: penalties constellation_lines_rim penalties
     Set the penalties for an overlap of the label's rim with the respective object to PENALTIES.

     These two objects get their own rim penalties because approximation of a label with a line object is not so bad usually.

     Defaults: 1000 (all)

 -- Parameter: penalties threshold penalties
     If the penalties for a label exceed PENALTIES, the label is suppressed.

     Default: 1000

Filenames
---------

 -- Parameter: filename stars filename
 -- Parameter: filename nebulae filename
 -- Parameter: filename label_dimensions filename
 -- Parameter: filename constellation_lines filename
 -- Parameter: filename boundaries filename
 -- Parameter: filename milky_way filename
     This lets PP3 look for the respective data in the given file. The filenames must be full paths from the current directory.

     Defaults: stars.dat (stars), nebulae.dat (nebulae), labeldims.dat (label dimensions), lines.dat (constellation lines), boundaries.dat (boundaries), milkway.dat (Milky Way)

Setting or deleting celestial objects and their labels
======================================================

All keyword here are commands.

 -- Command: objects_and_labels
     This keyword splits the input script in two parts.  The first part must contain parameters only, whereas the second contains commands only.

     This keyword must occur either once or never in a PP3 input script.  If never, the whole script consists of parameters.

Adding and deleting stars and nebulae
-------------------------------------

 -- Command: add objects ... ;
     Add the OBJECTS to the map, even if PP3's implicit behaviour would have excluded them.  This is sensible for nebulae mostly.

 -- Command: delete objects ... ;

How to add, delete, and reposition labels
-----------------------------------------

 -- Command: add_labels objects ... ;

 -- Command: delete_labels objects ... ;

 -- Command: reposition object towards direction ;

 -- Command: set_label_text object "label-text"

How to place text on the map
----------------------------

 -- Command: text label-text at rectascension declination [color red green blue] [towards direction] ;

All user defines texts on the map are generated with the keyword `text'.  However there are two sub-variants, namely flexes and tic mark labels.  Note that they can have the color and towards keywords as well.

Flexes
......

 -- Command: text label-text at rectascension declination along declination ;
     Create a flex label at the given coordinates.  A flex label follows the respective declination circle.

For further options see Arbitrary text.

Tic mark labels
...............

 -- Command: text label-text at rectascension declination tics (rectascension | declination) step ;

With the keyword rectascension, one rectascension circle gets tic marks, analogously with declination.  The celestial position after `at' denotes the starting point of the labelling, and STEP is the step skip (in hours or degrees respectively) for the subsequent tic mark labels.

The label should contain one of the following special expressions:

#1
     Rectascension in hours.

#2
     Declination in degrees.

#3
     Rectascension in integer hours (truncated, not rounded).

#4
     Rectascension fraction of hour in minutes (truncated, not rounded).

#5
     Declination in rounded integer degrees.

For further options see Arbitrary text.  Tic mark labels can also be flexes, see Flexes.

PP3 and LaTeX
*************

We're entering now the phase of sophistication.  Here you learn how to customise the graphical appearance of all text on your sky map almost arbitrarily.  You also learn how to achieve special text effects using the LaTeX language.

I can't explain LaTeX itself though.  So I must assume that you've been taught the basics elsewhere.  On the other hand, the LaTeX snippets that I will give in this chapter may be enough for many purposes.

It is not necessary to use the features described here, so it's still true that you needn't know about LaTeX in order to use PP3.  However if you want to have full control, LaTeX competence is unavoidable.

Using LaTeX in labels
=====================

You can use all LaTeX macros in PP3 labels that are allowed in horizontal boxes (like \mbox{...}).  Additionally, you can use many commands from the PSTricks package (http://www.pstricks.de/docs.phtml).

The most important pitfall is the backslash \, because when using quotes as string delimiters, you have to write is as `\\'.

Let's have a look at a more complex example:

     text "\\small Wolf 359\\hskip0.3em
           \\psdots[dotstyle=+,dotangle=45](0,0)"
          at 10.902 7.32 color 0.3 0.3 0.9333 towards W_ ;

This prints an `x' at the position of the star Wolf 359 and prints the label `Wolf 359' at the top left next to it:

Constellation map Wolf 359 in Leo

The row of LaTeX macros consists of the following elements:

\small
     This prints the whole label in a small typeface.  Please note that such commands only apply to the current label, since the label will be typeset within a box.  In effect, the next label will be big again, unless you say `\small' there, too.

\hskip0.3em
     This adds a horizontal skip at its position.  Its width is 0.3em, where `em' is the width of the letter `M'.  In this case, it creates a little bit of space between the `Wolf 359' and the `x'.

\psdots[dotstyle=+,dotangle=45](0,0)
     This is a PSTricks command.  Normally it prints a dot at the current position on the text baseline.  However the `dotstyle=+' option makes it a `+', and the `dotangle=45' option turns it by 45 degree, which makes it an `x' effectively.

     The clever bit is the fact that this macro is the very last one in the row.  Since it says `towards W_' (towards left, on baseline) in the PP3 command, this means that the `x' lies exactly on the celestial coordinates given after the `at' option.

LaTeX preamble
==============

Providing a LaTeX preamble is the most elegant, mighty, but also -- if you know LaTeX -- the easiest way to adjust the map layout according to your taste and needs.  There is a default preamble that defines the standard map layout.  This you can override in a user preamble as much as you want.

Default preamble
----------------

By default, the LaTeX document that PP3 creates begins with

     01   \documentclass[10pt]{article}
     02
     03   \nofiles\usepackage[dvips]{color}
     04   \usepackage{pstricks,pst-text}
     05   \newcommand*{\DP}{.}
     06   \newcommand*{\TicMark}[1]{#1}
     07   \newcommand*{\Label}[1]{#1}
     08   \newcommand*{\TextLabel}[1]{#1}
     09   \newcommand*{\FlexLabel}[1]{#1}
     10   \newcommand*{\Starname}[1]{#1}
     11   \newcommand*{\Messier}[1]{M\,#1}
     12   \newcommand*{\NGC}[1]{NGC\,#1}
     13   \newcommand*{\IC}[1]{IC\,#1}
     14
     15   \usepackage{mathptmx}
     16   \usepackage{helvet}
     17   \AtBeginDocument{\sffamily}
     18
     19   [optional input of user provided file]

The above is not provided by you, it is the LaTeX code that PP3 generates every time.  If you don't look at its LaTeX output file, you never see it.  But it may be helpful to know what happens here, so let's skim through it line by line:

Line 1
     The 10pt in the first line defines the standard font size in points.  You can change that with the input script parameter

          set fontsize 12

     which changes it to 12pt.  Possible values are 10, 11, and 12.

Lines 5--13
     All the so-called hooks of PP3, see LaTeX hooks.

Lines 15--17
     They set the standard font for PP3's maps: The Helvetica for all the Latin letters, and the Symbol for all the Greek ones.

Line 19
     Here your own preamble is included, if you have provided one.

User preamble
-------------

You tell PP3 where your own preamble is with the filename parameter `latex_preamble' in the input script, for example:

     filename latex_preamble mypreamble.tex

The file mypreamble.tex contains your LaTeX preamble macros and must reside in the current directory, or in another directory where TeX looks for its files.

The following is the contents of the file wiki.tex of the PP3 distribution.  It is the original user LaTeX preamble that was used for the Wikipedia Project, see Successful use of PP3.

     01   \usepackage{amsmath}
     02   \usepackage[T1]{fontenc}
     03   \IfFileExists{eulervm.sty}{\usepackage{eulervm}}{}
     04   \usepackage{relsize}
     05   \IfFileExists{t1pmy.fd}{
     06     \renewcommand*{\sfdefault}{pmy}
     07   }{
     08     \renewcommand*{\sfdefault}{phv}
     09   }
     10   \renewcommand{\Messier}[1]{\footnotesize{\scriptsize M}\,#1}
     11   \renewcommand{\NGC}[1]{\footnotesize{\scriptsize NGC}\,#1}
     12   \renewcommand{\IC}[1]{\footnotesize{\scriptsize IC}\,#1}
     13   \renewcommand{\FlexLabel}[1]{{\bfseries #1}}
     14   \renewcommand{\TicMark}[1]{{\mdseries\scriptsize\mathversion{normal} #1}}
     15   \AtBeginDocument{\sffamily\boldmath}

And this is what it does:

Line 1
     includes the AMSMath package which provides additional macros that can be useful in text labels.  You can include almost arbitrary LaTeX packages.

Line 2
     activates the so-called T1 font encoding.  It's not important to know what this means, but it is recommended and doesn't do any harm.

Line 3
     activates nicer Greek letters.  Well, your taste may be different.  This \IfFileExists thing tests whether the package is available on the current computer.  The package is included only if it exists.

Line 4
     enables the macro \smaller which can be very useful in text labels.  It reduces the current font size.  For example I can say

          set_label_text LEO 32 "\\smaller Regulus"

Lines 5--9
     test whether the font Myriad is available on the current computer, and if it does, it makes it the new standard sans-serif font.  Else it uses Helvetica for that.

Lines 10--14
     re-defines various LaTeX hooks in order to have nicer looking automatic labels, see LaTeX hooks.

Line 15
     switches to sans-serif font (Myriad/Helvetica) with \sffamily and to bold Greek letters with \boldmath.

Please note that you have to delete the file labeldimens.dat in the current directory if you have changes the font setup with a new own LaTeX preamble.  This forces PP3 to recalculate the dimensions of all labels -- and since the fonts have changed, this is necessary.

LaTeX hooks
===========

First of all -- what is a hook?  A hook in general is a macro or command that can be re-defined by the user, and that is called implicitly. Thus, by re-defining a hook, the user can modify the behaviour of the program at certain points.

In PP3, hooks are called for printing text of various kinds.  For example, every implicit (i.e. automatically generated) star name is printed by \Starname as in \Starname{$\gamma$}.  By default, this macro does nothing more than printing its argument:

     \newcommand*{\Starname}[1]{#1}

But if you re-define it, you can make every (implicit!) star label a little bit larger:

     \renewcommand*{\Starname}[1]{\larger #1}

Notice that the macro \larger is provided by the `relsize' package that must be loaded before, see User preamble.  So, just write the lines

     \usepackage{relsize}
     \renewcommand*{\Starname}[1]{\larger #1}

in the file mypreamble.tex, say

     set latex_preamble mypreamble.tex

in the PP3 input script, and voilà -- all star labels are larger.

PP3 knows nine hard-wired LaTeX hooks:

\Label
     Argument: the label text.  It applies to all labels, before any specific hook of the following is applied.

\TextLabel
     Argument: the label text.  It applies to all labels that the user creates with text.

\FlexLabel
     Argument: the label text.  It applies to all flexes.

\Starname
     Argument: the star name.  It applies to all automatically generated star names, in particular not to user-defined names given by set_label_text.

\Messier
\NGC
\IC
     Argument: the respective catalogue number.  This generates the labels for nebulae.  Notice that you must provide the catalogue name, or you can leave it as well.  For example, many people prefer NGC numbers as plain numbers without an `NGC' before it.  You achieve this effect with

          \renewcommand*{\NGC}[1]{#1}

\TicMark
     Argument: the tic mark label text.  It applies to all tic mark labels, see Tic labels.

\DP
     No argument.  This generates the decimal point.  By default, it's a `.', however in many countries a `,' is used instead.  You get this with

          \renewcommand{\DP}{,}

Known problems
**************

The following issues are known to the maintainer of PP3.  If you find another one, please report it on PP3's project page (http://sourceforge.net/projects/pp3).

  * Unknown stars in constellation line data files (the default is the file lines.dat) result in an error message, which is good, but the error message may include another -- probably valid -- star name, which is bad.  Fortunately the actually wrong star and the printed star are within the same constellation line, the printed star coming first.

  * The usage of semicolons in PP3 input scripts is not consistent. For example, a `reposition' needs one, but a `set_label_text' not.

  * If you print a large portion of the sky, e.g. a hemisphere, and a pole-near region of the Milky Way (e.g. Southern Cross) is at the very rim of the map, the Milky Way dots are printed a little bit too coarsely, leaving tiny gaps between the dots.

  * The declination circles have slight kinks at 0h rectascension. Except for the \pm 80^\circ circles they are mostly invisible though.

  * Ecliptic and grid don't take part in PP3's penalty scheme yet.

  * Large nebulae are drawn as ellipses representing their approximative shape in the sky.  However, the algorithm doing that is mathematically flawed and doesn't work for polar-near regions.  Fortunately this only affects the Small Magellanic Cloud, the actual shape of which is, by a curious coincidence, rendered very well by that algorithm.

Wishlist
========

It would be nice to have the following things in PP3.  Please contact Torsten Bronger (mailto:bronger@users.sourceforge.net) if you want to contribute.

  * Very faint stars, i.e. stars fainter than faintest_star_disk_magnitude, should be removed from the map automatically, if they overlap with a label.  It shouldn't matter whether the label was implicitly created or user-defined.

  * An ephemerides module that allows to insert the Sun, the Moon, and the planets on the map, for a given date, time, and observation location on Earth.  By the way, the C++ module itself is already existing, but its integration into PP3 is not done yet.

  * More map projections, in particular a real isogonal one.

  * The resolution of the Milky Way should be determined in a way that TeX's memory doesn't overflow.  Maybe one should switch to contour plots instead of dot patterns for the Milky Way.

  * Create little bitmaps of all labels in order to determine kerning parameters for them.

  * PP3 should become able to deal with large data bases.

  * The star names list of Celestia (http://cvs.sourceforge.net/viewcvs.py/celestia/celestia/data/starnames.dat) or something like that should be used for identifying stars in input scripts.

Besides that, I'd like to re-structure the internals of PP3 because in some respect the code is not well maintainable and expandable.  For the long-term future it may be worth thinking about using Guile as the scripting language.

Data file formats
*****************

Maybe you want to use your own data bases with PP3.  If they are not too large (Unfortunately PP3 still has the
disadvantageous behaviour of reading the whole data base file.) you may well do so.  Of course, then you need to know the internal structure of the files.  Although they are so simple that reverse engineering should be almost trivial, you find here a complete description of all of them.

Additionally I will give information where the original data of PP3's standard distribution came from.

The last point, the ``label dimensions file'', isn't a real data base file, but an internal temporary file.  It is mentioned here just for completeness.

Stars data file
===============

This is a text file usually called stars.dat.  Four consecutive lines belong together and refer to one particular star.  There is no header.

Line 1
     A row with seven fields separated by whitespace:

      1. Henry Draper Catalogue number (`0' if unknown),

      2. BSC catalogue number (`0' if unknown),

      3. rectascension in hours,

      4. declination in degrees,

      5. visual brightness in magnitudes,

      6. B-V brightness in magnitudes (`99.0' if unknown), and

      7. Flamsteed number (`0' if unknown).

Line 2
     The label (astronomical name) for the star, as a LaTeX-ready string, e.g. ``$\alpha$'', ``$\phi^{2}$'', or simply ``$23$''.  May be the empty string.

Line 3
     The astronomical abbreviation of the constellation.  It must be all uppercase.

Line 4
     The spectral class.  It must start with the spectral class letter, followed by the fraction digit, followed by the luminosity class as a Roman number, e.g. ``F5III''.  Anything may follow as in ``K2-IIICa-1'', however the mandatory parts must not contain any whitespace.

Example
-------

     358 15 0.139805 29.0906 2.06 -0.11 21
     $\alpha$
     AND
     B8IVpMnHg
     11636 553 1.91067 20.8081 2.64 0.13 6
     $\beta$
     ARI
     A5V
     886 39 0.220611 15.1836 2.83 -0.23 88
     $\gamma$
     PEG
     B2IV

PP3's star data origin
----------------------

It's the Bright Stars Catalogue (BSC) as distributed with the program Cartes du Ciel (http://www.stargazing.net/astropc/).  It contains almost 10,000 stars.  I corrected minor mistakes and let all double stars collapse, i.e. their visual brightnesses were summed up and the respective minor partner was removed from the file.

Nebulae data file
=================

This is a text file usually called nebulae.dat.  There is no header.  The file is just a whitespace separated stream of numbers and constellation abbreviations.  In order to make it more readable though, the standard PP3 nebulae file has every nebula on one single line of its own.

Each dataset has the following eleven fields:

 1. NGC catalogue number (`0' if not listed there),

 2. IC catalogue number (`0' if not listed there),

 3. Messier Catalogue number (`0' if not listed there),

 4. The astronomical abbreviation of the constellation.  It must be all uppercase.

 5. rectascension in hours,

 6. declination in degrees,

 7. visual brightness in magnitudes,

 8. large diameter in degree minutes,

 9. small diameter in degree minutes (must be equal to the large diameter if unknown),

 10. the horizontal angle if the large diameter in degrees (`720.0' if unknown), and

 11. the type of the nebula: 0: unknown, 1: galaxy, 2: emission nebula, 3: reflection nebula, 4: open star cluster, and 5: globular star cluster.

Example
-------

     1 0 0 PEG 0.121083 27.7089 13.6 0.0283333 0.02 -30 1
     2 0 0 PEG 0.121417 27.6786 15 0.0166667 0.01 -22 1
     3 0 0 PSC 0.121333 8.30139 14.4 0.0183333 0.01 -21 1
     4 0 0 PSC 0.123472 8.37389 16.9 0.01 0.005 55 1
     5 0 0 AND 0.130222 35.3628 14.8 0.02 0.0116667 -25 1
     6 0 0 AND 0.159056 33.3089 14.1 0.0283333 0.0266667 -50 1

     1976 0 42 ORI 5.58808 -5.39028 4 1.08333 1 720 2
     3034 0 82 UMA 9.93167 69.6831 9.2 0.186667 0.0716667 25 1
     7000 0 0 CYG 20.9806 44.5167 4 2 1.66667 720 2

PP3's nebulae data origin
-------------------------

It's the NGC/IC catalogues as compiled by Wolfgang Steinicke (http://www.ngcic.com/steinicke/).

Constellation lines data file
=============================

This is a text file usually called lines.dat.  It has no header. You can define paths of constellation lines by lists of stars that are ended with a semicolon `;'.  You can insert superfluous whitespace as you wish, and comments after every `#'.

Stars are given in the usual way: Either by a pair of constellation abbreviation and Flamsteed number, as in

     ORI 19

(Rigel), or by `HD' and the Henry Draper catalogue number, as in

     HD 108248

(Acrux).

Example
-------

     # Orion

     ORI 19  ORI 34  ORI 24 ;
     ORI 53  ORI 50  ORI 46  ORI 34 ;
     ORI 50  ORI 58 ;

     # Southern Cross

     HD 111123  # beta Cru
     HD 106490 ; # delta Cru

     HD 108248  # alpha Cur
     HD 108903 ;  # gamma Cru

PP3's constellation lines origin
--------------------------------

I created the lines after my fancy.  The Atlas für Himmelsbeobachter (by Erich Karkoschka, in German; ISBN 3440074889) was an important source of inspiration though.

Boundaries data file
====================

It doesn't make much sense to use an own boundaries file, unless you want to use a different equinox, but anyway.  This is a text file usually called boundaries.dat.  It has no header.

The file is a sequence of elementary line segments.  Every segment is a whitespace separated sequence of entries.  The entries for each segment are:

 1. Number of points n_1 in the segment.

 2. Repeated n_1 times:

      1. rectascension of point in hours,

      2. declination of point in degrees.

 3. Number of constellations n_2 touching this border line (is always 2, however it hasn't always been due to flawed raw data).

 4. Repeated n_2 times: All uppercase astronomical abbreviation of the adjacent constellation. It may distinguish between SER1 and SER2 for Serpens Caput and Serpens Cauda.

Example
-------

     3 20.63865 2.43608 20.63929 1.43613 20.63992 0.43617 2 AQL AQR
     10 20.63992 0.43617 20.64055 -0.56377 20.64118 -1.56373
       20.64181 -2.56368 20.64245 -3.56364 20.64308 -4.56359 20.64372 -5.56355
       20.64435 -6.56350 20.64500 -7.56346 20.64564 -8.56341 2 AQL AQR
     9 17.71838 -67.57110 17.65152 -67.58319 17.58465 -67.59526
       17.51772 -67.60731 17.45076 -67.61933 17.38378 -67.63130 17.31676 -67.64324
       17.24970 -67.65515 17.21616 -67.66108 2 ARA APS

PP3's boundary data origin
--------------------------

It's the Catalogue of Constellation Boundary Data (ftp://cdsarc.u-strasbg.fr/cats/VI/49/) by Davenhall and Leggett.  I had to fix some bugs though, because the Ophiuchus/Serpens region was flawed. Additionally, the original data has peculiarities because it tries to be useful for bounded maps, e.g. in Mercator projection.  I removed the resulting spurious lines.

Milky Way data file
===================

This is a text file usually called milkyway.dat.

Its header is extremely simple: It consists of only one number which is the maximal (= equatorial) diagonal half distance of two pixels in degrees. This value is used as the radius for the milky way pixels.  Of course it must be the minimal radius for which there are no gaps between the pixels.

What follows are the Milky Way pixels themselves.  Each consists of tree entries, separated by white space:

 1. The rectascension in hours,

 2. the declination in degrees, and

 3. the grey value of the pixel from 1 to 255.  Zero is not used because zero-value pixels are not included into the data file anyway.

Example
-------

     0.212
     11.885 0.259 1
     11.962 0.295 5
     11.974 0.298 5

     17.982 -26.999 136
     17.982 -27.299 158
     17.982 -27.599 169
     17.982 -27.899 199
     17.981 -28.199 235

PP3's boundary data origin
--------------------------

I used the All-Sky Milky Way Panorama (http://home.arcor-online.de/axel.mellinger/) by Axel Mellinger.  His bitmap with the two hemispheres in equidistant azimuthal projection was greyscaled and smoothed with the Gimp, and then transformed to PP3's format with a small hand-written C program.

Label dimensions file
=====================

The default name of this file is labeldimens.dat.  This file is never user provided but generated by PP3 itself in order to store typographic dimensions of all labels.  Highly probably you needn't know its structure.

Every labels has two lines in the file:

Line 1
     The label itself in LaTeX form.

Line 2
     The typographic width, height, and depth of the label in centimetres, separated by whitespace.

Example
-------

     $10$~\footnotesize UMa
     0.97106 0.23043 0.00253
     $\omega$
     0.34197 0.17081 0.00000
     10 UMa
     1.11657 0.23389 0.00316
     47 Tuc
     0.94506 0.23389 0.00316
     Pleiades
     1.20865 0.24777 0.00316
     \FlexLabel{Andromeda}
     1.86061 0.25076 0.00316
     \FlexLabel{Antlia}
     0.93945 0.25076 0.00316

List of all constellations
**************************

first column
     Latin name

second column
     astronomical abbreviation, ready for being used -- in its all-uppercase form -- with set constellation

third column
     English name

fifth column
     rectascension of constellation centre, in hours, ready for being used with center_rectascension

sixth column
     declination of constellation centre, in degrees, ready for being used with center_declination

last column
     recommended scale for a 9cm x 9cm map, in degrees per centimetre, ready for being used with grad_per_cm

The values are taken from the input scripts used for the Wikipedia Project, see Successful use of PP3.

Latin   ab.   English
rec.   dec.   sc.
Andromeda   And   Andromeda                      1   +38   4
Antlia   Ant   Air Pump                          10.2   -35   3
Apus   Aps   Bird of Paradise                    16   -75   3
Aquarius   Aqr   Water Carrier                   22.3   -8   6
Aquila   Aql   Eagle                             19.7   +3   4
Ara   Ara   Altar                                17.5   -53   4
Aries   Ari   Ram                                2.8   +18.8   4
Auriga   Aur   Charioteer                        5.6   +38   4
Boötes   Boo   Herdsman                        14.7   +34   4
Caelum   Cae   Chisel                            4.8   -38   3
Camelopardalis   Cam   Giraffe                   5.5   +75   5
Cancer   Cnc   Crab                              8.7   +20   4
Canes Venatici   CVn   Hunting Dogs              13   +40   4
Canis Major   CMa   Big Dog                      6.5   -20   4
Canis Minor   CMi   Little Dog                   7.5   +12   4
Capricornus   Cap   Goat                         21   -16   4
Carina   Car   Keel                              8.5   -64   5
Cassiopeia   Cas   Cassiopeia                    0.5   +60.5   4
Centaurus   Cen   Centaur                        13.6   -45   5
Cepheus   Cep   Cepheus                          23   +75   4
Cetus   Cet   Whale                              1.7   -7   6
Chamaeleon   Cha   Chameleon                     11   -79   4
Circinus   Cir   Compasses                       14.8   -62   4
Columba   Col   Dove                             5.8   -35   4
Coma Berenices   Com   Berenice's Hair           12.4   +22.5   4
Corona Australis   CrA   Southern Crown          18.6   -42   3
Corona Borealis   CrB   Northern Crown           15.8   +33   4
Corvus   Crv   Crow                              12.4   -18   4
Crater   Crt   Cup                               11.4   -16   4
Crux   Cru   Southern Cross                      13.2   -60.8   4
Cygnus   Cyg   Swan                              19.95   +40.8   5
Delphinus   Del   Dolphin                        20.5   +12   3
Dorado   Dor   Goldfish                          5.1   -60   4
Draco   Dra   Dragon                             16.5   +72   5
Equuleus   Equ   Little Horse                    21.2   +8   3
Eridanus   Eri   River                           3.8   -30   6
Fornax   For   Furnace                           2.7   -32   4
Gemini   Gem   Twins                             7   +20   4
Grus   Gru   Crane                               22.5   -44   4
Hercules   Her   Hercules                        17.55   +30   5
Horologium   Hor   Clock                         3.3   -53   4
Hydra   Hya   Hydra (Sea Serpent)                11.15   -15   10
Hydrus   Hyi   Water Serpent (male)              2.5   -70   4
Indus   Ind   Indian                             21.5   -60   4
Lacerta   Lac   Lizard                           22.5   +46   4
Leo   Leo   Lion                                 10.8   +20   4
Leo Minor   LMi   Smaller Lion                   10.3   +32   4
Lepus   Lep   Hare                               5.6   -18   4
Libra   Lib   Balance                            15.2   -17   4
Lupus   Lup   Wolf                               15.3   -41   4
Lynx   Lyn   Lynx                                8.2   +47   4
Lyra   Lyr   Lyre                                18.8   +37   3
Mensa   Men   Table                              5.7   -77   4
Microscopium   Mic   Microscope                  21.15   -37   3
Monoceros   Mon   Unicorn                        6.7   -3.5   4
Musca   Mus   Fly                                12.6   -70   4
Norma   Nor   Square                             16   -50   4
Octans   Oct   Octant                            22   -85   4
Ophiucus   Oph   Serpent Holder                  17.3   -9   6
Orion   Ori   Orion                              5.8   +0   4
Pavo   Pav   Peacock                             19.5   -67   4
Pegasus   Peg   Winged Horse                     22.7   +20   6
Perseus   Per   Perseus                          3.6   +47   4
Phoenix   Phe   Phoenix                          0.7   -49   5
Pictor   Pic   Easel                             5.6   -54   4
Pisces   Psc   Fishes                            0.5   +14   6
Pisces Austrinus   PsA   Southern Fish           22.3   -31   4
Puppis   Pup   Stern                             7.6   -31   4
Pyxis   Pyx   Compass                            8.95   -30   4
Reticulum   Ret   Reticle                        3.9   -60   3
Sagitta   Sge   Arrow                            19.6   +15   4
Sagittarius   Sgr   Archer                       18.5   -27   4
Scorpius   Sco   Scorpion                        16.8   -30   4
Sculptor   Scl   Sculptor                        0.5   -32   5
Scutum   Sct   Shield                            18.7   -10   3
Serpens   Ser   Serpent                          17.1   +2   6.5
Sextans   Sex   Sextant                          10.2   -1   4
Taurus   Tau   Bull                              4.6   +18   4
Telescopium   Tel   Telescope                    19.3   -52   4
Triangulum   Tri   Triangle                      2.2   +33   4
Triangulum Australe   TrA   Southern Triangle    16   -65   3
Tucana   Tuc   Toucan                            23.7   -67   4
Ursa Major   UMa   Great Bear                    11.5   +55   6
Ursa Minor   UMi   Little Bear                   15   +78   4
Vela   Vel   Sails                               9.6   -48   4
Virgo   Vir   Virgin                             13   +3   5
Volans   Vol   Flying Fish                       7.8   -70   4
Vulpecula   Vul   Fox                            20.2   +25   4