library/.

RealSky Support

RealSky® Support Files for SkyMap Pro 5 to 9

IF YOU ARE USING SKYMAP PRO 10 OR LATER YOU DO NOT NEED THESE FILES - THEY ARE SUPPLIED WITH THE PROGRAM!

RealSky® is a set of CD-ROMs published by the Astronomical Society of the Pacific, containing highly compressed digitized images from the Palomar Sky Survey (a photographic survey of the northern sky carried out in the 1950s). RealSky South is a second set of CD-ROMs containing images of the southern sky; RealSky and RealSky South together cover the entire sky, showing stars and deep sky objects as faint as magnitude 20.

SkyMap Pro has the ability to extract images from the RealSky CD-ROMs, and use those images as the background to the map, allowing you to see what deep sky objects actually look like, with the usual SkyMap Pro object labels, coordinate grids, etc, superimposed on top of the image.

In order to use RealSky images with SkyMap Pro 5 or later, you must download and install a set of support files:

Click here to download dss.exe (531kb)

Run the downloaded file, and an installation program will guide you through the process of installing the required support files into the SkyMap Pro installation directory. Once these files have been installed, the "Background Images" chapter of the SkyMap Pro manual describes how to use this new facility.

These support files make use of a library called get_dss, originally developed by Bill Gray of Project Pluto for use with his Guide star charting software, and used in SkyMap Pro with his kind permission. The following description is largely based on the description of the get_dss library on the Project Pluto web site at http://www.projectpluto.com/get_dss.htm.

Release history:

24-FEB-99: New version of "dss.exe" uploaded to fix a bug affecting the area of sky covered by the RealSky plate "XE524". Attempting to display a background image for this part of the sky would result in the program crashing.

What is GET_DSS 1.0?

If you have a copy of the RealSky CDs, you may have noticed that one CD contains a "software" directory, with a copy of the GETIMAGE code created by STScI. This source code, for VAX machines and certain flavors of Unix, provides a way to extract images from RealSky and DSS CD-ROMs, in either FITS or GEIS formats. GET_DSS is essentially a port of certain portions of this code, with much of the code rewritten completely in order to (a) port it to ANSI C/C++; (b) separate user interface code from underlying functionality (essential to real portability); and (c) add certain capabilities that are either essential in the PC world or that are just useful to anybody, on any system.

GET_DSS will work with both RealSky and DSS CDs. (The differences are that the arrangement of plates on CDs is different, and the DSS data is not as severely compressed as the RealSky data. But throughout the code and discussion, you'll see "DSS" and "RealSky" used almost interchangeably.)

What operating systems does it work under?

Click here to download the get_dss.zip source code archive (367kb)

The GET_DSS.ZIP file, as originally written by Bill Gray for use in Guide, contains a makefile for WATCOM C/C++, version 11.0. This will enable you to compile the code under DOS and link it to make an example program, GET_DSS.EXE. As you'll see, there is a pretty clean break between "underlying functions" and "user interface". The "underlying functions" are essentially in ANSI C.

Chris Marriott ported the code to a 32-bit Windows DLL for use in SkyMap Pro. Contained in the zip file is a Microsoft Developer Studio project file GET_DSS.DSP which will build the DLL. Most of the source code is common between the two versions; only the files IMAGE.H and MAIN_DLL.CPP are added specifically for the Windows DLL code.

On the DOS side, you have the Watcom make file MAKEFILE (which ought to move to other make utilities without trouble), and the source code GET_DSS.CPP to show how the code is used. (Or, if you're uninterested in how the code is used, you can just use it as a DOS version of GETIMAGE.)

You could rename all .CPP files to .C without trouble; the underlying code uses no C++ specific techniques. (Both the Watcom and Microsoft compilers do some extra error checking on C++ files; that's really the main reason the code has a .CPP extension.)

This code could probably be recompiled with any ANSI C compiler, without any real trouble. If you do this, please let us know. The one area to worry about might be byte order; the code has been running this on Wintel; we've been pretty careful not to break anything involving byte order, but can't swear we've caught everything.

How does it all work?

In general, you should be able to follow the example code in GET_DSS.CPP without having to concern yourself greatly with the details of how the underlying code works. We've done our best to make it possible to use it as a "black box". If you're curious, or are engaged in some project where knowledge of DSS and/or RealSky internals is important, read on.

RealSky and DSS are organized as plates (of course) that were scanned in to be 14,000 by 13,999 pixels each. (One row of pixels in the final row is dropped.) These were then broken up into 500x500 pixel "tiles", with 28x28 = 784 tiles for each plate. (The missing row at the bottom of the plate creates 500x499 pixel tiles.) Each plate, such as "XX005", gets its own directory, with 784 files (one for each tile) in it.

The logic to be used in extracting an image for a given area works as follows. First, figure out what plates cover that area (there is considerable overlap). The code to do this is in PLATELST.CPP; it returns an array of structures, sorted in order of preference ("best" plate first). By default, both GET_DSS and STScI's GETIMAGE will prefer the plate that puts your desired area farthest from a plate edge. The plate edges tend to be a bit dodgy, so that's not an unreasonable idea. But there are still cases where you might want to override the selection. (In GET_DSS.CPP, you can see how the '-t' option is used to accomplish just that.)

Once you've figured out what plate you're going to use (and what CD has that plate), you can then figure out what 500x500 pixel tile(s) cover your image area, and extract them from the CD to build your image. The code that figures out what tiles are needed is in GETPIECE.CPP; this code also assembles the resulting data into an output image.

Actually decompressing a tile is a somewhat convoluted matter, and is the only code that remains (in admittedly severely altered form) from STScI's GETIMAGE. The data is Huffman-encoded, so the first step is to de-Huffman-encode it; that code is in QTREEDEC.CPP. The result of that decompression is not the original pixel data, though; instead, you get a set of coefficients for an H-transform, which is a close relative of the DCT (Discrete Cosine Transform) and FFT (Fast Fourier Transform). The code for reversing the H-transform is in HINV.CPP.

What restrictions are there on its use?

The original goal of this project was to simply port STScI's GETIMAGE 2.0, but we gave up in frustration. Of the original STScI files, only QTREEDEC.C, HINV.C, and DODECODE.C remain in anything resembling their original form. You'll notice that these three have copyright notices in them. (Do not be confused, as we were, by the fact that this software was produced under a NASA grant. This is a very odd case, in that STScI is a private non-profit organization. Under certain circumstances, and given NASA permission, it is indeed possible for them to claim a copyright on this code.)

Everything else was written or rewritten by Bill Gray (with minor contributions by Chris Marriott), and can be used freely in non-commercial applications. STScI still has some legal concerns about the remaining code, and will probably want certain changes in the language describing their liability for problems in the code and conditions under which it can be used. We're fairly confident that this will be resolved soon (the concerns expressed so far are not particularly unreasonable ones). Watch this space.

In the meantime, it should be noted that the copyright notices in the three files in question are mostly a matter of giving credit where credit is due. The files have been sufficiently modified that holding STScI responsible for their content, in any manner whatsoever, would not be particularly sensible, in either a technical or legal sense. Any problems with them, at this point, would really be my fault. This is expressed in suitably legal language below:

The program, data, documentation, and other items and services (hereafter referred to as "products") provided with the Get_DSS source code are provided on an "as is" basis. PROJECT PLUTO AND ITS LICENSOR MAKE NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING THIS PRODUCT OR ITS USE AND OPERATION FOR ANY PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED IN SOME JURISDICTIONS. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU.

IN NO EVENT WILL PROJECT PLUTO, ITS LICENSOR, OR THEIR OFFICERS, EMPLOYEES, OR AGENTS (COLLECTIVELY, PROJECT PLUTO AND ITS LICENSOR) BE LIABLE TO YOU FOR ANY CONSEQUENTIAL, INCIDENTAL, OR INDIRECT DAMAGES ARISING OUT OF OR IN CONNECTION WITH THE USE OF THIS SOFTWARE, EVEN IF PROJECT PLUTO OR ITS LICENSOR HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. BECAUSE SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL DAMAGES, THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU.

The liability of Project Pluto or its licensor to you for actual damages from any cause whatsoever