Open Star Files

                                                               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