2016/01/28
OPEN STAR README FILE
-------------- DISCLAIMER -------------
THIS PROGRAM IS IN ALPHA DEVELOPMENT AND IS NOT YET READY FOR GENERAL USE.
1. Quick start
1.1. Getting it running
- Ensure java 1.7 or better is installed.
- For conversion of files to ppm format, ensure dcraw is installed
and can be found from the "PATH" environmental variable.
- Unzip the open star (ost) program directory structure to some place
we'll refer to as:
${app_dir} = <some_path>/open_star
- To run the example, go to
${app_dir}/open_star_data/ost_example_projects/example1, modify the
appropriate shell script for the correct java path, then run the shell
script.
- To run the program in general, go to ${app_dir}, modify the
appropriate shell script for the correct java path, then run the shell
script.
2. Introduction
Open Star interactively reads multiple images of a fixed star field
from a designated directory structure, aligns and sums them, rescales
the sum, and displays it. This has the affect of maintaining the objects
in fixed positions ( stars ) in the summed image, while averaging away
sensor noise and transient objects ( planes, satellites, UFOs, etc ).
The program also supports normalizing hot pixels by subtracting out
a dark field image.
3. Requirements
The following are required to run Open Star:
- Required: Java virtual machine - see discussion below
- Optional: dcraw
4. To install
4.1. Java virtual machine (jvm)
The program runs under jvm 1.7 or later, which must be installed
separately. The jvm is distributed as part of a package called a java
runtime environment (jre). There are 2 common jre's. The original
Sun/Oracle jre is not open source but is freely downloadable.
Sun/Oracle and others are reworking the Sun jre into a fully open
source jre under something called "OpenJDK", which is slowly replacing
the Sun/Oracle jre.
Open Star has been tested in on the Sun jvm in Fedora Linux and in
Windows 7.
In Windows for Sun jvm look for:
C:\Program Files\Java\jre1.something\bin\java
In Linux do: which java
In Linux Fedora without java in the executable search path look for:
/usr/java/latest/bin/java - for Sun jvm
/usr/lib/jvm/java-something-openjdk-something/jre/bin/java
- for open source jvm
In other OS's: Your guess is as good as mine
To check which java version you have do: java -version
4.2. Open Star
Since the program runs under a Java virtual machine (jvm), the
program "executable" is identical for Linux and Windows and
(probably but untested) Apple.
Since the program is not targeted to a particular operating
system, no attempt has been made to support any operating system
specific installs. The general philosophy is to unzip it, put it
somewhere, and write/modify a few shell scripts to run it.
- download the zipped application <open_star_download>.zip
- unzip <open_star_download>.zip -> top output dir will be
"open_star"
- move "open_star" directory to final resting place which will be
referred to as ${app_dir}
4.3. Dcraw - optional
This seems to be the go to program for converting various camera
image formats into the ppm format that Open Star uses.
( see http://www.cybercom.net/~dcoffin/dcraw )
Dcraw must be installed separately. If Open Star can find this
"C" version of dcraw it will use that version to do camera
image translations.
A preliminary attempt to translate Dcraw into Java is included
in this distribution. At present it has been tested only on
Cannon images.
5. Program layout
5.1. Structure of extracted program
The structure of the extracted program and associated data is as
follows:
${app_dir} - top directory =
<some_path>/open_star
java_source - java source code top directory
java_classes - java byte code directory
open_star.jar - file containing the program
open_star_data - data required to run
ost_resoruces - resources for the program
ost_info_files - information about the program
ost_excample_projects - examples
5.2 Structure of data directory
The data directory structure for a given set of star field shots
to which the program is pointed must have the following structure:
<some_directory> - top data directory for data set
darkfield - directory containing dark field images
(can be empty)
starfield - directory containing star field images
whitefield - directory that is unused for now
6. To run
The native image file format of Open Star is ppm
( see http://netpbm.sourceforge.net and
http://netpbm.sourceforge.net/doc/ppm.html ).
The program will continuously scan the designated data directory
structure. All dark field images in <dir>/darkfield must be
entered before any images are entered into the <dir>/starfield
directory. All files in the <file_name>.ppm format will be added
to the summed image. The data top directory can be specified as
a command option ( -datadir <full_path_name> ) or it can be set
from the program menu ( Proj->set data dir ).
Right now Open Star will automatically convert most raw image
files found in its data directory structure into the ppm format
if it can find the "C" version of the dcraw executable. Also, the
program can convert a very limited number of raw data formats on
its own ( right now only Canon <file>.CR2 format ) if the dcraw
executable can not be found. Otherwise you must manually convert
your images into ppm format.
The program can be a memory hog if large raw image files are used.
Tweek the -Xmx variable as necessary if out of memory errors
occur.
Full syntax to run the program is:
[<java_path>/]java -Xmx800m
-cp <install_path>/java_classes/open_star.jar
my_proj.open_star.openstar [options]
There is a Linux script and a windows script to run run the program:
${app_dir}/run_linux
${app_dir}\run_windows.cmd
There are also scrpts to run the enclosed example in:
${app_dir}/open_star_data/ost_example_projects/example1
