Eclipse Photography Software, Beta version 0.3.1 (2006 March 10) Documentation

Copyright 2006 Fred Bruenjes. http://www.moonglow.net

This page has been kept rather plain so that it may be easily printed.

Jump to a particular section:

Program Description

Overview:

Hardware control/interfacing features:

Software features:

Requirements:

Limitations:

Supported Canon cameras for exposure control:

The EOS 30D is NOT SUPPORTED. It is not known whether the EOS 20Da will work.

Serial port shutter cable sources and instructions:

What's New

Program Installation

  1. Disclaimer: Use this program at your own risk. No guarantees are made, if it doesn't work and you come away without any photos, sorry!
  2. Download the zip archive to an empty directory on your disk: eclipse.zip (2.35 MB)
  3. Unzip the archive into the empty directory. Note: the program does not come with an installer. Think of it as an IQ test: if you don't know how to unzip a file, there's no way you'll understand the more complicated steps below.

Setup and checkout (long before Eclipse Day)

  1. Configure your computer to disable any sleep, hibernation mode, or screen savers. You don't want your computer to shut itself off during the eclipse, ruining your photos!
  2. If you'll be connecting your Canon camera via USB or Firewire, make sure the camera drivers are installed on the PC and the camera connects OK. Install and run Canon's EOS Capture or RemoteCapture software to verify that the camera can be controlled remotely. If you can't control the camera from Canon's software, there is NO WAY it's going to work with mine. If your camera has a "Communication" menu option, make sure to select "PC connect." or "Normal" instead of "PTP" or "Print/PTP". Consult Canon's troubleshooting instructions if you run into issues. Once you've got it working, close Canon's software (EOS Capture or whatever), but leave the camera connected and powered on.
  3. Set up your camera(s). For USB/Firewire control, set the camera to manual exposure ("M" mode) and manual focus. Set the "Auto Power Off" mode OFF or disabled. Turn off Auto Exposure Bracketing mode. Turning off "Review" mode or reducing the review time can speed up things.
  4. Start the Eclipse software (double click the 'Eclipse' application). You might get some warnings about missing setup/configuration files - ignore that this time. Go to the 'Location/Time' menu and select 'Set Lat/Lon/Alt...'. A dialog pops up. Please enter the expected latitude, longitude, and altitude at your observing site. Below are some rough examples, be sure to contact your tour operator or consult maps for more accurate values. You'll need to come back and update the lat/lon/alt using your GPS on eclipse day when you select your actual observing site, since even small differences can shift the eclipse time significantly. Click the 'Set/Recalc/Reload' button when you're done. This will update the displays to reflect your location.

    Bilma/Dirkou, Niger: 18° 49.98' N, 12° 52.23' E
    Jalu, Libya: 28° 13.83' N, 21° 30.40' E
    Sallum, Egypt: 31° 34' N, 25° 9' E
    Cappadocia, Turkey: 38° 42' N, 34° 10' E

  5. Check that the calculated event times are reasonable. Select 'Location/Time' and then the 'Event Times...' menu option. Check the values shown against another source, like your tour operator's predictions or the NASA (Fred Espenak) bulletin. The times should be close to what other people are using. Don't fret if they aren't an exact match because this program calculates circumstances much more accurately than most other people, but if they are way out then check your coordinates. Click OK or Cancel when done.
  6. Now you must tell the program about the cameras you'll be using. Click the 'Setup' menu, and then select 'Hardware Configuration...'. If you have a Canon camera connected via USB or Firewire, then click the Camera 1 'Camera Name' drop down box and select your camera. If you are using a serial port shutter cable, click the 'shutter cable' checkbox and fill in or correct the COM port (ie COM1, COM2, ...), and cable type boxes. Most serial cables are 'RTS' (DB9 connector pin 7) type. If you are connecting additional cameras for shutter-press only control, give them a name and enter their serial port details in the same manner. Note that only two serial ports can be used for camera control, so if you are using stock cables that means only two cameras can be connected. The maximum of four cameras requires two dual-type serial shutter cables that use both the DTR and RTS connections. Finally, if you have a GPS or Kestrel weather meter connected, enter the COM port details. Click OK when done. If prompted, please exit and restart the software (a reboot is NOT necessary). At this point you may want to browse around the various menus to customize the settings of the more advanced options, see below for a description of each menu item.
  7. Now you should test the cameras. Click the 'Camera' menu, select the 'Push Shutter' option, and then pick one of the cameras that are listed. Hopefully you will hear the camera take a picture, and the camera's memory card light should illuminate to indicate that it's saving a photo to the card. If the camera doesn't work, recheck the connections, play around with the hardware configuration, etc. After getting the "push shutter" option working, on a USB/Firewire camera you should also try the 'Test Exposure' option under the 'Camera' menu. This commands the camera to take a 1/4000 F8 ISO100 RAW exposure. Check that the camera accepted these settings and that the exposure time, aperture, ISO, and file type are now set to those values, and that a RAW file was created at those settings. Again, if this doesn't work check your configuration.
  8. Now you need to start developing a camera script. The script is a text file that tells the software when to take photos with what settings. Click the 'File' menu, choose 'Edit Script...' and pick one of the scripts that the software was shipped with. basic.csv is a very simple script to get you started. deluxe.csv shows off all the possible features of the scripting language. Your script will probably end up somewhere in between. The "Notepad" editor should be launched with the file you selected. Browse through the file. If a script line starts with the character '#' that line is a comment that is ignored by the software. Otherwise each line has comma delimited fields specifying information. The first task you need to do is update the camera names, since odds are that you aren't using the same camera as these stock scripts. Do a find and replace or a manual change of the camera name from 'EOS 5D' to your camera's name. This name must EXACTLY match the name given in the hardware configuration dialog. Another thing that must match EXACTLY is the file type/quality setting, be sure to check the 'Camera' 'Show Supported File Types' menu to see what you can pick from. Go ahead and start modifying the script to whatever you desire. Keep in mind that the eclipse predictions are probably only accurate to 1-2 seconds, so allow for some leeway around contact times (or just take a bazillion photos to cover all possibilities). When you're done, be sure to save it.
  9. Back in the eclipse software, click 'File' and then 'Load Script...' and choose the script you just made. If you get some error messages, try to correct them and then reload the script. If everything is OK, you'll get a bunch of extra displays showing upcoming script actions.
  10. To test the script out, select 'Time' and then 'Simulated Time...'. Enter a date and time close to something interesting in your script, like a minute or two before second contact, and click OK. The software time will jump ahead while leaving the PC clock alone. You should hear your camera clicking away taking photos according to the script. At this point you can open the "script_debug.txt" file to see the times that the script items parsed to. After a while, stop the script (do 'Time' 'System Time', or 'File' 'Unload script') and compare the files stored on the camera to your script. If the camera didn't perform exactly as per the script, you probably tried to stuff too many exposures into the script. Take some stuff out or respace them and try again. Without using a serial port shutter cable, you may need to back off to 2-6 seconds or more in between exposures depending on the camera model, computer speed, and memory card speed.

    A REALLY IMPORTANT POINT is to sanity check the camera's exposure/aperture/ISO settings. Sometimes the EXIF or camera screen data can be incorrect compared to what the camera actually took. I like to set up a "simulated eclipse" where I point and focus the camera on a lit diffuse light bulb, with a box or some other object situated near the camera partly blocking the light bulb. This allows me to make sure that the exposure, aperture, and ISO really did change from exposure to exposure. The extent to which the box is in focus gives a clue about what aperture was used. At the end of a test I download the memory card to the computer to check the files carefully.

  11. Once you've got a script you're happy with, do a full end-to-end test. Pretend it's eclipse day, set up everything. Set the simulated time to be a little before first contact or whatever and let the setup run non-stop all the way through your entire sequence. You want to make sure nothing goes to sleep, no batteries die, no memory cards fill up, the cameras don't spontaneously go to sleep or disconnect, etc. You should also practice removing solar filters and measure how long that takes to complete.
  12. Once you're happy, make a backup copy of the script, that you can refer back to in case you screw it up later. Hint: use "Save As..." in the text editor.

The day before Eclipse Day

  1. Make sure you computer doesn't have sleep/hibernation/screen savers etc. enabled.
  2. If you're already at the eclipse site, take GPS readings and update the lat/lon/altitude dialog. If you have a GPS connected and configured you can just go to the 'Set Lat/Lon/Alt...' dialog box and click "Take GPS" to copy the GPS readings.
  3. If you have time, do a final test of the script.
  4. Charge your batteries, make sure cables are working, etc.
  5. Put fresh/empty memory cards in your cameras. Clean the lenses, etc. On 1-Series Canon cameras, make sure to reset the file counter if it's getting close to rolling over.

On Eclipse Day

  1. Connect and power everything up. Don't do it too early or you'll deplete your batteries! If you are connecting a Kestrel 4000, set it to Auto Store On, Store Rate 2 or 5 seconds, and Overwrite On.
  2. For USB/Firewire control, set the camera to manual exposure ("M" mode) and manual focus. Set the "Auto Power Off" mode OFF or disabled. Turn off Auto Exposure Bracketing mode.
  3. Start the software and check or update your final position based on GPS, in the 'Location/Time' 'Set Lat/Lon/Alt...' menu. Unless you are overriding event times, click the 'Set/Recalc/Reload' button. (If you're on a moving ship and have a GPS connected, hitting F6 will read the latest position and recalculate everything. If you don't know the intended coordinates at mid-eclipse, do this every once in a while to keep the position current.)
  4. Check that the computer time is correct. It should be set to 'Location/Time' 'System Time' and the UTC display in the upper left should be correct. Check it against a good timing source, like a GPS. If the computer clock is incorrect, fix it or use the 'Setup' 'Clock Error Adjustment...' feature to fudge the clock until it reads correct.
  5. Make sure you've configured everything (software options, camera settings, memory cards, cabling, etc) the same as when you tested the setup. Today is not the day to make any big new changes.
  6. Load your script.
  7. As you progress into the partial phases, keep an eye on the camera. Make sure it stays pointed at the Sun. Make sure there is enough space left on the memory card for the rest of the eclipse. Depending on the transparency of the sky and altitude of the Sun, you may need to edit the script to adjust the exposure time of the partial phases to an optimum value. Check the focus of the cameras now and then. Tape the focus ring and AF/MF switch so they can't be bumped. Do not let anyone else handle or look through your camera. Make sure cables are routed or tied down so someone won't stumble over them.
  8. If you need to change the battery or memory card on the USB/Firewire connected camera, choose 'Camera' 'Disconnect'. Turn the camera off and do whatever you need to do. Turn the camera back on, wait for it to connect to the computer (usually accompanied by a ding or other notification sound), and then select 'Camera' 'Connect' and check that the camera is again doing script items (or hit F1-F4 keys to manually fire the shutter).
  9. Once you get within 5 minutes of totality, stop checking the computer or camera. If a problem crops up you will not have time to fix it, so just sit back and enjoy the eclipse. The excitement of totality often causes people to make mistakes or misperceive things, so it's now too late to be messing with complicated software or making last-minute changes. Trust me, don't do it!
  10. REMEMBER TO TAKE SOLAR FILTERS OFF RIGHT BEFORE SECOND CONTACT. This is the MOST likely thing to go wrong, because it's up to you to remember to do it. Don't let all of this fancy camera automation spoil you so much that you forget to take the filters off. The sound file playback feature was initially added for the sole purpose of having the computer remind me to take the filter off.
  11. Watch totality!
  12. Conversely, after totality make sure you put the filters back on.
  13. After the eclipse: exit the software, shut down the computer, turn off the cameras, disconnect them, and clean up. Enjoy your photos and start planning your next eclipse trip.

Notes

Troubleshooting:

If the program acts wierd or unpredictably or has garbled displays, delete the config.ini and setup.ini files, then reenter all your configuration and preferences.

Files that are written:
GPS data is captured to data.log file.
Kestrel data is captured to kestrel.dat file.
Parsed script is written to script_debug.txt file.
When NOT using a serial shutter cable on some camera models, image thumbnail is written to thumbnail.jpg.

"Recalc" and "Reload":

Recalc means: recalculate the local circumstances (after a change in lat/lon or other critical parameters).
Reload means: reload the script (after a recalc, or a change in the script, to make the changes take effect).

Serial port shutter cables:

On the Hardware Configuration screen there are boxes labelled 'Shutter Press Time (ms)'. This determines how long the shutter button is electronically pushed down. If you set it too long, the camera will take two exposures. If you set it too short, the camera won't take an exposure at all. So this value requires some experimentation for best results.

GPS units and timing:

If you connect a GPS to use it as a timing source, make sure the GPS is reliable enough as a time standard. Run the GPS for 1-2 minutes and then observe the rightmost value on the first line of the main screen (it's in parentheses, a bit to the right of ClkErr). This is the standard deviation of the GPS timing measurements in seconds. If this number is small (less than 0.1) your GPS is stable enough. If this number is large, something is wrong with the GPS and it cannot be used. Sometimes a GPS unit will give poor timing results when its' display screen is set to a graphically intensive page, so try various GPS display pages to see which gives the most stable timing, leaving it on each page for 1-2 minutes.

Besselian Elements:

Eclipse circumstances are calculated using the Besselian elements from Fred Espenak's NASA Solar Eclipse bulletin. A digitized version of Espenak's limb profile is also used. Formulas are primarily from Jean Meeus' Elements of Solar Eclipses and Astronomical Algorithms.

Menu control descriptions

File menu:

Location/Time menu:

View menu:

Camera menu:

Setup menu:

Help menu:

Main Screen Description

First line (date/time):

Second line (debugging information):

Third line (position information):

Fourth line (GPS information):

Sixth line (centerline information):

Event information:

Current local circumstances:

Upcoming script items:

Upper right countdown display:

Sun Image:

Umbral duration map:

Description of the script file format

Fields are comma delimited. Lines can be in just about any order with a few exceptions (times are calculated and sorted based on your latitude/longitude location). A '#' character in the first column indicates that the entire line is a comment that should be ignored.

Action

Date / Reference Event

Event times: Other possibilities:

Offset sign

Ignored when absolute Year/Month/Day specified.

Time

This is an offset from the reference event, except when an absolute date was specified, in which case this is the UTC time of day.

Camera Name

Exposure

Only applicable to USB/Firewire camera.

Aperture

Only applicable to USB/Firewire camera.

ISO

Only applicable to USB/Firewire camera.

Mirror lock up time

File Quality

Only applicable to USB/Firewire camera. Use "Camera" "Show Supported File Types" menu option to see legal combinations. Note: on EOS-1D Mark II, FINE is a JPEG quality of 8, NORMAL is a quality of 5, other JPEG quality values are not accessible.

Size

Only applicable to USB/Firewire camera. Use "Camera" "Show Supported File Types" menu option to see legal combinations.

Incremental

Only applicable to USB/Firewire camera.

Comment

All text and images are © 2006 Manfred Bruenjes - All Rights Reserved.