A3O overvew

A3O overview

A3O is a suite of programs which are designed to operate a Fabry-Pérot observing station. Such an installation generally consists of a Fabry-Pérot interferometer (FPI), a camera to record the interference patterns, movable optics to set the direction of observation, and a computer which runs the A3O software and stores the image data. In normal operation, A3O runs four independent processes, which communicate using a message-based protocol.

Process | Program file | Purpose | Details
Master | Master.exe | Executes a user-written script which manages operations of Camera, Observatory, Analyze and Communicate. | more
Camera | Camera.exe | Controls one or more cameras, either a CCD camera which detects the interference patterns, or a sky camera which monitors the sky (e g, for clouds). | more
Observatory | Observatory.exe | Operates the movable optics which aim the FPI. Also records local sensor readings, and has analog and digital inputs and outputs. | more
Analyze | Analyze.exe | Display images and do basic data reduction on them. | more
Communicate | Communicate.exe | Compress and transfer images from FPI observing station to laboratory, or modified instructions from laboratory to station. Pass information between stations. | more

Each of the processes has its own Change log section. Articles in this help file which are new or changed since the last release are marked [image].


Overview of Master

Master coordinates Camera, Observatory and Analyze, controlling all operations of the station by communicating with the other processes. The user provides Master with a list of operations to be performed, a script. When Master is started, it executes the script and then stops. Most scripts are written as an infinite loop, so Master runs continuously.

Details of how to use the Master front panel for testing or debugging scripts are here.

A script is a text file; usually several script files are used together for a single job. Each line of a script is executed in sequence. The language of a script is a subset of C with added special-purpose commands to control the observing station.

Here is part of a typical script, color-coded (command, variable, comment). This script invokes another script, the file AcquireStoreDisplayImageFPI.txt.

// Take an initial laser calibration
xTime = xTimeLaser
SET_PARAMETER CAMERA FPI, ShutterMode = AUTO
MOVE_PH 0., PHLasZe						//  First move only zenith (az = 0, initial value)
MOVE_PH PHLasAz, PHLasZe					//  Second move only azmith (ze = laser ze)
SHUTTER OPEN 						//  Open the LASER shutter (not camera shutter)
SET_PARAMETER CAMERA FPI, ExposureTime = xTime
dataType = "L"
ImageSequenceL = ImageSequenceL + 1
seq = ImageSequenceL
TAKE_IMAGE FPI,dataType
CALL "AcquireStoreDisplayImageFPI"
SHUTTER CLOSE						//  Close the LASER shutter (not camera shutter)

// Now that we have done the initial housekeeping, wait until observation should commence)

WAIT_UNTIL beginNightTime

//  Begin night-time operation
iseq = 0

while($CurrentTime < endNightTime)
{
    // ...processing...
}

In this script fragment MOVE_PH sends a message to Observatory telling it to move the pointing head (PH), SHUTTER OPEN tells Observatory to open the laser shutter, SET_PARAMETER CAMERA changes one of Camera’s operating parameters, and TAKE_IMAGE tells Camera to acquire an image.


Master Operation

Master coordinates operations of all the processes (itself, Camera, Observatory and Analyze). For production, Master runs scripts continuously, without any user interaction. The front panel, shown below, is useful for testing, debugging, or monitoring operation.

For details on the various sections, click on the screen shot below.

In this example, a scipt file DataPARI_winds_Synch.txt is currently executing. The at line 26 shows the next script line to be executed. The column Count is the number of times that line has been encountered.

Positioning the mouse cursor (arrow) on the variable dirImages (line 26) shows a tooltip containing the current value for that variable (the string "D:\PARIData2011\20120315").

The orange bar at line 30 indicates a breakpoint has been set there, meaning if the script is run (as opposed to single-stepped), it will pause before executing line 30.

The result log shows useful information about each script command (for example, the value which is stored by an assignment), and the error log contains information about any script or communication errors which have occurred. Both these logs, as well as the optional user logs, are written to text files.

Debugging aids

The main use of the debugging aids is finding errors in scripts interactively.
  • Single step: Click the lower arrow [image] (the upper arrow does nothing). This executes a single script line, then pauses. When execution is paused, you can examine individual variables by mousing over them, set or remove breakpoints, change checkout mode, or look at the symbol table (all defined variables).

    You can also single-step by pressing F10 or F11. The difference between these is that F11 behaves like the single-step arrow: it pauses at every statement. F10 does not pause within subroutines (this is sometimes called “step over”, compared to “step into” for F11).

    Pressing shift-F11 will run the script until it returns from the current subroutine (“step out”).

  • Show all defined variables: Clicking this button updates the display to its left. The display will not appear until the button is clicked. It is a snapshot of the symbol table; it is not updated in real time. Click again while paused to update.
    In this example, the variables d,date and drImages have been defined. A variable becomes known when it is encountered during execution of a script. In this example, taken from the script above, the variables logDir (line 29) and logID (line 30) do not appear, because the script was paused on line 26.

    The type of each variable precedes its value. The type abbreviations are int (integer), real, bool, time. Quotes (") surround string values.

    There are some entries in the symbol table, such as false here, which are actually keywords. The column "#" is the internal identifier for the symbol, and not of concern to users.

  • Checkout mode: When this is checked, the script limits delays to 3 seconds. Delays come from DELAY, WAIT_UNTIL, or waiting for response from the other processes (Camera, Observatory or Analyze).

    This setting may be changed at any time, and will be effective with the next script line to be executed.

  • Pause: This button will only be active when the script is running (not paused). It will pause script execution before another line is executed. The current line may take some time to complete (e g, DELAY 120).

  • Run: This button will only be active when the script is paused (not running). It will start script execution at the line indicated by .

    Pressing F5 is the same as clicking Run.

  • Restart: This button will only be active when the script is paused (not running). It will start execution at the first line of the script which is already loaded. The effect is as if the next line indicator were moved to line 0, and Run clicked.

  • Copy end of logs: The Master, Camera and Observatory logs are written to disk periodically. If Camera or Observatory crashes, or hangs, the final part of the log will not be written to disk, so [image] copy the end of the respective logs into the Master results log. The Master logs themselves may be copied to the clipboard using [image].
  • Copy script: The script which is currently loaded is copied to the clipboard, with line numbers. for example,
      23 d = DateToInteger($CurrentTime)
  24 date = ConvertToString("%8d",d)
  25 dirImages = "D:\\PARIData2011\\" + date
  26 LOG_DIRECTORY Master,dirImages
  • Program display: This selection controls how often the display is updated.

    When debugging, the best choice is Continuous; the script display is refreshed every time a line is executed.

    For production, using Every n seconds can save some screen updates, which will speed up script execution.

    The Top level only check box is not yet implemented.

User logs

Master has provision for up to 3 “user logs”. These are windows in Master’s front panel to which you can send output for whatever use you wish.

If these logs are used, corresponding output files will be created on exit or log closing by script. The output files will be named MasterUser n_ yyyymmddhhmmss.txt, where n=1, 2 or 3, and will contain the output sent to the user logs by your script.

The command LOG_DISPLAY allows you to add lines to any of the five log windows (Results, Errors, or the three user logs). You could use this to show, for example, the start and end times, current image, etc. If you insert more than five lines, scroll bars will appear on the right.

Here is a sample script:

 0   // Demonstrate output to all 5 log windows
 1   LOG_DISPLAY R "Generated by the script"
 2   LOG_DISPLAY E "Also comes from the script"
 3   LOG_DISPLAY 1 "User log 1: send whatever you want here"
 4   LOG_DISPLAY 1 "Today is "+ConvertToString("%d",DateToInteger($CurrentTime))
 5   LOG_DISPLAY 2 "This is User log 2"
 6   LOG_DISPLAY 2 "The time is now "+ConvertToString("%09d",TimeToInteger($CurrentTime))+" UTC"
 7   LOG_DISPLAY 3 "User 3"
 8   x="String"
 9   y="stuff"
10   LOG_DISPLAY 3 x+"-01"+y+"."
11   LOG_DISPLAY 3 x+"-02"+y+"."

And this is what the logs look like after it is executed

Notice that the Results window shows the same strings as appear in the user logs windows. The number before Expr value is the script line number.

Script

The script is a text file containing operations to be performed sequentially. The script file currently being executed is shown in the script window:

The lines are alternately yellow- and white-striped, to make it easier to follow. The coloring has no other significance.

You can set a breakpoint in any line by clicking on that line, then pressing F9. The line will change from white to pink, or yellow to orange.

Here breakpoints have been set at lines 9 and 12.

When execution reaches a line with a breakpoint, execution pauses before that line is executed.

To remove a breakpoint, click on the line, and press F9. The line will change back to white or yellow.

To resume execution when paused at a breakpoint, click Run, or press F5.

Immediate execution

The immediate execution line acts like a script of a single line. During creation and testing of scripts, it can be used to verify the syntax of a script line, explore the operation of a command, or act as a calculator.

Result and error logs

The purpose of these logs is to be able to follow script execution retrospectively. The Results log shows
  • Version of Master, process ID, time started (UTC and local).
  • The right side of each assignment statement in the script.
  • Changes in script due to CALL, OVERLAY, RETURN and script completion.
  • Identification of the other processes.
  • Listing of available cameras, from Camera.
  • Station location, from Observatory.
  • Delay times from DELAY and WAIT_UNTIL.
  • Message responses from other processes.
  • Changes in the Master log file directory from LOG_DIRECTORY Master.
  • Script-generated output lines from LOG_DISPLAY R.
The time (UTC) is shown for every entry in the logs. The date appears periodically, and at the start. Here are excerpts from a Master Results log:
19:53:34 Starting Master v0.90  1/19/12
19:53:34 Process ID=3344  UTC is 2012-3-26  19:53:34.640; local time is 2012-3-26  12:53:34.640 Pacific Daylight Time (diff=420 min)
19:53:36 0 Expr value: "PgmDefault.txt"
19:53:36 1 Read pgm file "c:\A3O\Master\PgmDefault.txt"
19:53:38 0 Expr value: "DataPARI_winds_Synch"
19:53:38 1 Read pgm file "c:\A3O\Master\DataPARI_winds_Synch.txt"
19:53:39 23 Expr value: d int 20120326
19:53:41 24 Expr value: date "20120326"
19:53:42 25 Expr value: dirImages "D:\PARIData2011\20120326"
19:53:43 26 Expr value: dirImages "D:\PARIData2011\20120326"
19:53:43 27 Log file directory changed from . to D:\PARIData2011\20120326
19:53:43 27 Log file name is MasterResults_20120326125343.txt
...
19:53:53 59 Log file directory changed from D:\PARIData2011\20120326 to C:\Documents and Settings\meriwej\Desktop\PARIprograms\Logs
19:53:53 59 Log file name is PAR_20120326125353_MasterResults.txt
...
19:54:32 63 Waiting 3.000 seconds
19:54:38 70 Expr value: "TwilightNightTimes.txt"
19:54:38 71 Read pgm file "c:\A3O\Master\TwilightNightTimes.txt"
19:54:42 6 Expr value: "TimeCycle.txt"
19:54:47 8 Expr value: start time 2012.03.26.19:55:17.000 UTC
...
19:55:17 52 Expr value: endTime time 2012.03.27.10:24:48.000 UTC
19:55:18 71 RETURNing to DataPARI_winds_Synch.txt
19:55:22 73 Expr value: DateStart int 20120326
...
19:56:01 111 Expr value: beginHousekeepingTime time 2012.03.26.22:57:18.000 UTC
19:56:02 113 Expr value: beginHousekeepingTime time 2012.03.26.22:57:18.000 UTC
19:56:06 113 Waiting 3.000 seconds
20:03:47 122 Serial 120 from "SETUP CAMERA FPI"
20:03:50 120 timeout
20:03:58 123 Serial 121 from "SETUP COOLER FPI"
20:04:01 121 timeout
20:04:03 126 Serial 122 from "GET_STATUS CAMERA FPI, TEMPERATURE, temperature"
20:04:06 122 timeout
20:04:07 127 Serial 123 from "GET_STATUS CAMERA FPI, STATE, CurrentState"
20:04:10 123 timeout
Excerpts from the script that produced this log are below. The line numbers in the log correspond to the line numbers in the script. Because Camera was not running, messages to it all timed out (these are in script lines 122,123, 126 and 127).
...
  23 d = DateToInteger($CurrentTime)
  24 date = ConvertToString("%8d",d)
  25 dirImages = "D:\\PARIData2011\\" + date
  26 LOG_DIRECTORY Master,dirImages
  27
...
  59 LOG_DIRECTORY Observatory,logDir,logID,logOrder
...
  63 DELAY 30
...
  70 CALL "TwilightNightTimes.txt"
  71
  72 // Save the dates into variables
  73 DateStart	= DateToInteger(beginNightTime)
...
 111 beginHousekeepingTime = beginNightTime - 1200
 112
 113 WAIT_UNTIL beginHousekeepingTime
 114
 115 // Clear quick look graphics in the analyze program
 116 SETUP ANALYZE
 117
 118 // Move the SkyScanner to the home position and wait for this to complete
 119 SETUP FPI SKYSCAN
 120
 121 // Initialize the Andor camera and turn on cooling
 122 SETUP CAMERA FPI
 123 SETUP COOLER FPI
 124
 125 // Get the current status of the Andora camera after initialization
 126 GET_STATUS CAMERA FPI, TEMPERATURE, temperature
 127 GET_STATUS CAMERA FPI, STATE, CurrentState

The Error log is normally empty, except for the two header lines, which are identical to those in Results. You should check each error log to make sure there are no errors in your script.

Here is the error log for the above run. It has two errors, for the message responses that were not received, because Camera was not running. The columns in the error log are Time, Error sequence, Script file, Line number, Error test.

19:53:34 Starting Master v0.90  1/19/12
19:53:34 Process ID=3344  UTC is 2012-3-26  19:53:34.640; local time is 2012-3-26  12:53:34.640 Pacific Daylight Time (diff=420 min)
20:03:50 1 DataPARI_winds_Synch.txt 122 No response to message serial 120 received in 3 sec
20:04:01 2 DataPARI_winds_Synch.txt 123 No response to message serial 121 received in 3 sec


Script language

Script format

A script may be created by any text editor. The language supported resembles a subset of C, with added special-purpose commands (e g, SELECT_FILTER, TAKE_IMAGE). Unlike C, all statements are on a single line. Text following // is considered a comment, unless the // is within quotes..

White space (blanks and tabs) may be used to improve readability.

Note: The initial line of every script file is treated as a comment by Master. As a matter of good programming practice, you should use this line to describe the script, its purpose, the author, revision date, etc.

Variables, expressions and assignment

Variables are all “global”. That means any variable is accessible from any script; there is no scoping of variables as in C. Because of this, you should try not to use unneeded variables, and where practical, reuse variable names, being careful not to cause conflicts.

Variable types are integer (−231 ≤ i < 231 ), boolean (true or false), real (double, i e range of ±1.7×10±308 , 15 significant figures), string (0–99 characters, excluding NUL), and time (date and time to the nearest msec, range 1970-1-1 to 2038-1-19).

Variable names begin with an alphabetic character or underscore ( _ ), and contain letters, digits, and underscores. There is no limit on the length of variable names, although it is best not to use names that are really long.

The name of a variable is case-sensitive; e g, ABC is not the same as abc or Abc.

Show examples

Integer: | i=123 numberOfPasses=14 nPart_3=-10
Boolean: | done=true done=false
Real: | x=123.4 yOffset=4e-3 az=187.65e-1
String: | str1="Hello world" quote="\"" tab="\t" | the usual C escape sequences
Time: | midnightToday=2011.6.3 timeToMin=2011.6.3.11:23 | times are UTC
 | hhmm=11:23 timeToSec=2011.6.3.11:23:59

The type of a variable is determined by its first definition by an assignment. The type of a variable may change with each assignment.

Arrays of any of the above types, up to 10 dimensions, are supported in a limited fashion. Since arrays are not declared, the size and shape (number of subscripts) of an array are determined by its first use, according to these rules:

  1. The number of subscripts is that in the first use. “First use” means the first time the script interpreter encounters the array variable. Subscripts are non-negative integers. For example, if the first time the script interpreter sees variable abc is the line

          abc(1,2)=3

    then the number of subscripts for array abc is 2. Once set, the number of subscripts cannot be changed, and all future references to abc must have exactly 2 subscripts.

  2. The size of an array in each dimension is either 11, 101, or 100, and is determined by the first use, as follows:

    Subscript value | Lower bound | Upper bound | Size
    0 ≤ sub ≤ 10 | 0 | 10 | 11
    11 ≤ sub ≤ 100 | 0 | 100 | 101
    100 ≤ sub ≤ 1000 | sub/100*100 | lo limit+99 | 100
    1001 ≤ sub | sub/100*100 | lo limit+99 | 100

    So, if the first reference were abc(17,8888), the array abc would be “declared” as having dimensions abc(0:100,8800:8899). The notation here is lower bound:upper bound. For abc(1,2), the dimensions are abc(0:10,0:10).

    Because of the first-use restriction, it may be necessary to make an artificial reference to an array to get it dimensioned properly. For example, if an array abc(1:50) is desired, you cannot have the first reference be abc(1), because that will cause the array to be dimensioned abc(0:10). Instead you should have the first reference be abc(50), which will give abc(0:100), per the table above.

  3. All elements of an array must be the same type of data (e g, all real, or all integers). Scripts that violate this constraint will not function properly.

The form of an assignment statement is the familiar

      variableName = expression

System variables

A system variable is a read-only variable whose value is maintained by Master. The current system variables are

Name | Type | Description
Date and time
$CurrentTime | time | The current date and time as a time value.
$DayNumber | integer | Serial number of the current day, starting from Jan 1, 1841 = day 1. This variable is useful for determining the day of the week, odd/even days, etc.
$TimeOfDay | integer | Seconds since midnight of the current day.
$CurrentMidnight | time | Midnight of the current day (the most recently preceding midnight).
$TimeZoneDiff | integer | UTC − local time, in sec. The expression now-$TimeZoneDiff is a time value which, when converted, will give the local time.
Miscellaneous
$CheckoutMode | boolean | TRUE if the script is running in checkout mode.
$Serial | integer | The serial number of the most recently-sent message to another A3O process. Used for diagnostic purposes only.

Time values

When you specify time values as constants, you can use any of the following forms. Values for month, day, hour, minute and second can be 1 or 2 digits.

Format | Meaning
yyyy.m.d | Midnight of m/d/yyyy
yyyy.m.d.hh:mm | hh:mm:00 of specified day
hh:mm | the next occurrence of the specified time (either today or tomorrow)
yyyy.m.d.hh:mm:ss.sss | the exact time (.sss is msec, currently not used)
yyyy.m.d.hh:mm:ss | the time within 1 sec (msec assumed 0 (note 1)
hh:mm:ss.sss | the next occurrence of the exact time (either today or tomorrow)
hh:mm:ss | the next occurrence of the specified time (either today or tomorrow), with msec=0 (note 1)
Note 1. Since msec are not currently in use, this is the same as above.

Dates and times as described above will all be interpreted as UTC (Coordinated Universal Time). That means, for instance, that $TimeOfDay returns the UTC (GMT) value, regardless of the setting of the computer time zone. And in a script, WAIT_UNTIL 23:00 means to wait until 23:00 UTC. The day number, $DayNumber, changes at 00:00 UTC, so it will not necessarily be the same as the date of the time zone in which the computer is located.

Similarly, the functions DateToInteger(time) and TimeToInteger(time) return their times and dates as UTC, because their argument times are UTC also.

It is important to distinguish between a time (an instant in history) and its representation (a human-readable character string). A time is independent of the local time zone and the computer’s settings for time zone and daylight savings time. Since the default representation of times is UTC, the representation is also independent of these.

The conversion from time (internal) to representation (external) is done automatically for the log and the variable values that are shown in tool tips. The reverse conversion, from representation to time, occurs when you specify a time constant (e g 2011.6.6.11:22:33), either in a script, or in a control file.

The functions DateToInteger(time) and TimeToInteger(time) also convert from time to representation.

If you want to know the local time, you must explicitly “correct” the UTC time using $TimeZoneDiff or your knowledge of the time zone; then the conversion to a representation will show local time.

Expressions

An expression is composed of constants, variables and function calls, with the operators

Assignment: | =
Grouping, subscripting: | ( | )
Arithmetic: | + | - | * | /
Relational: | < | >= | <= | == | !=
Logical: | && | || | !

In general, the operators have the same meanings as in C. Time values may be compared using the relational operators.

A limited amount of arithmetic may be done with time values. If T is a time value, and S is an integer, representing number of seconds, T+S and T-S are time values. If U is also a time value, T-U is an integer number of seconds (rounded from the time difference, which has msec precision).

Built-in functions

For a list of available functions, see Built-in functions and subroutines. You cannot create user-written functions, although a user-written subroutine will usually be able to achieve the same objectives.

Control structures

These operate as in C, but the formatting is less flexible. Braces { } must be on separate lines.

if(expression)
{
}
else         else clause
{            is
}            optional

while(expression)
{
}

for(expression; expression; expression)
{
}

Note: the script language doesn’t include unary increment or decrement operators, so the loop expression in for must include a complete assignment, e g i=i+1, not i++. Also, all three expressions must be present, unlike C.

Show examples

if(endNightTime < beginNightTime)
{
    endNightTime = endNightTime + 86400 // advance 1 day
}

if ( ze < 0.5 )
{
     tagtype = "Z"
}
else
{
    tagtype = "N"
}

while($CurrentTime < endNightTime)
{
    TAKE_IMAGE FPI,tagtype
    DELAY 60 // 1 minute between images
}

zenithSunTwilight = 94	// (direction=increasing)
zenithSunNight = 97		// (direction=increasing)
zenithSunEndNight = 99	// (direction=decreasing)
zenithSunEnd = 97		// (direction=decreasing)

start = $CurrentTime+30		// allow short time, 30 secs, for calculations, and get next twilight
SolarPosition(start,&az,&ze)	// get az and ze angles for sun (reals), 30 sec from now

for (hr=1; hr<=24; hr=hr+1)
{
    t = hr*3600 + start
    zeLast = ze
    SolarPosition(t, &az, &ze)
    if(zeLast<zenithSunTwilight && ze>=zenithSunTwilight)
    {
        hrTwilight = hr - 1
    }
    if(zeLast<zenithSunNight && ze>=zenithSunNight)
    {
        hrNight = hr - 1
    }
    if(zeLast>zenithSunEndNight && ze<=zenithSunEndNight)
    {
        hrEndNight = hr - 1
    }
    if(zeLast>zenithSunEnd && ze<=zenithSunEnd)
    {
        hrEnd=hr-1
    }
}

Subroutines

Subroutines are implemented as separate scripts only. There is no special syntax for subroutine scripts, except that they should end with a RETURN or OVERLAY statement.

CALL string-valued expression
OVERLAY string-valued expression

The expression value is the name of a script file, or a complete path to a script file. The “.txt” extension may be omitted.

CALL will return at the end of the script file, or when encountering a RETURN statement in the script.
OVERLAY replaces the current script file with the indicated script.
RETURN terminates the current script file and transfers control to the line following the CALL to the current script file.

If the end of the script file is reached without encountering a RETURN, execution stops. There is no default RETURN implied by the end of a script.

Show examples

In file CallingScript.txt:
s="Starting"
subroutine1="Sub1.txt"
CALL subroutine1
// Now s="Done sub 1"
CALL "Sub2"
// Now s="Done sub 2"
OVERLAY "Sub3"

In file Sub1.txt:

s="Done sub 1"
RETURN // back to CallingScript
In file Sub2.txt:
s="Done sub 2"
RETURN // back to CallingScript

In file Sub3.txt:

s="Done with CallingScript" // continues, does not go back to CallingScript

Built-in subroutines

For a list of built-in subroutines, see Built-in functions and subroutines.


Script language built-in functions and subroutines

Built-in functions

Library

These are C run-time library functions. Each has a real-valued result. For more information, see a C library manual.

sin(real) | exp(real) | abs(real)1
cos(real) | log(real) | abs(integer)2
tan(real) | pow(base,power) | min(arg1,arg2)3
acos(real) | sqrt(real) | max(arg1,arg2)3
atan(real)
atan2(x,y)

Notes: 1 This is the same as C’s fabs; absolute value of a real argument.
Notes: 2 This is the same as C’s abs; absolute value of an integer argument.
Notes: 3 The arguments can be either integer or real, and can be mixed.

Functions which convert data types

ConvertToString(format,expression)
The function returns a string value. The format is a control string as used for the C library function printf. expression must have a type that corresponds to the first conversion specification in the control string.
ConvertToReal(format,expression)
The function returns a real value. The format is a control string which is a subset of the C library function scanf. expression must evaluate to a string.
Ex: pi=ConvertToReal("pi=%le","pi=3.1415926535") results in the variable pi being assigned the real value 3.1415926535.
The control string must contain exactly one %le (or %lf or %lg), and cannot contain any other conversion specifications which would require a pointer in C. The “pointer to double” size specifier l (lower-case L) is required.

Show example

Suppose the variable MyString has the value "2% of 99 is 1.98", but although the general format of the string is known, the numbers can vary. In other words, we want to parse a string whose form is integer1% of integer2 is real to determine the value of real. An assignment which does this is
value=ConvertToReal("%*d%% of %*d is %lf",MyString )
The asterisks (*) are C’s assignment suppression flags, which cause the integers to be parsed, but not stored. The double percent sign (%%) is the specification for a single percent sign in the input.
RealToInteger(real)
The function returns an integer value, obtained by truncating the fractional part of the real. This function is equivalent to casting a real to int in C.
DateToInteger(time)
TimeToInteger(time)
These functions return integer values derived from the time argument. The first returns yyyymmdd, and the latter hhmmSSsss.

Show examples

For these examples, assume these assignments have already been done:
n=3
Not_true=false
z=5.1
str="Hello?"
today=2012.1.25
Integer-valued:
Result: 		123-456
-333 		n+1
4 		(2/3)*(3/4)
0 (because 2/3=3/4=0)
Integer-valued:
Result: 		DateToInteger(today)
20120125
Boolean-valued:
Result: 		Not_true && (n>=3)
false 		!Not_true
true 		Not_true || (n>=3)
true
Real-valued:
Result: 		3.4+2*z+6
19.6 		z/2*3.14
8.007 		pow(10.0,0.30103)
2
Real-valued:
Result: 		sin(z)*sin(z)+cos(z)*cos(z)
1
String-valued:
Result: 		str+", "+str
"Hello?, Hello?" 		str+ConvertToString("%6.2f",sin(1))
"Hello?  0.84"
Time-valued:
Result: 		today+60
2012.01.25.01:01:00.000 UTC  		today-3601
2012.01.24.23:59:59.000 UTC

Functions dealing with files

FileStatus(path)
This function returns the last modify time for the file named by path. If the file does not exist, or the argument path has incorrect format, the resulting time will be 1970.1.1.00:00:00.

path may be any form of file location recognized by Windows, a complete path (D:\MyDataDirectory\MyFile.txt), a relative path (..\AnotherDirectory\AnotherFile.dat), or just a filename (FileIsHere.readme). However, you should always use a complete path, because, except in special cases, the current working directory is unknown to the script, and filenames or relative paths use the working directory as a reference point.

Show example

lastModTime=2012.1.1.00:00:00	// force an initial check
modTime = lastModTime

// Wait for a file update, checking every 60 sec
while(modTime == lastModTime)
{
    modTime = FileStatus("D:\\MyDataDirectory\\MyFile.txt")
    if(modTime == 1970.1.1.00:00:00)
    {
        // Error getting info on file, usually means file doesn't exist
    }
    DELAY 60
}

// File has been modified
// ... process file
lastModTime = lastModTime

FileXferStatus(order)
This function returns the state of a file-handling command: either a transfer initiated by one of the file-handling script commands:

  • FILE_FETCH
  • FILE_SEND
  • FILE_COMPRESS
  • FILE_UNCOMPRESS
  • FILE_MOVE
  • FILE_COPY
  • FILE_DELETE
  • Get a file from a remote A3O node.
  • Send a file to a remote A3O node.
  • Combine files into a compressed zip archive on a local A3O node.
  • Extract the files from a compressed zip archive on a local A3O node.
  • Move files from one directory to another on a local A3O node.
  • Copy files from one directory to another on a local A3O node.
  • Delete files on a local A3O node.
These commands all cause a message to be sent from Master to Communicate to initiate the operation. When the operation is complete, Communicate notifies Master; this function tells you whether the notification was received, and, if so, any error code.

The variable order is the number of file-handling requests since that for which status is wanted. So, use 0 for the most recent file-handling command, 1 for the next most recent one, etc. A file-handling request is one of FILE_FETCH, FILE_SEND, FILE_COMPRESS or FILE_UNCOMPRESS.

Master keeps information for the latest 10 transfer requests; thus order must be in the range 0–9 .

The value of this function is 0 if the transfer was completed without error, negative if the order is invalid or other error occurring on the local node, and positive if an error occurred during the file transfer, or the transfer has not yet completed.

Value | Meaning
Errors in the script or message-passing
−2 | Communicate is not running on the local node, or not responding.
−3 | Remote host in the transfer command was not in the network list.
−4 | Incorrect order (order must be 0−9).
−1 | File transfer with specified order never requested.
−6 | Message to Communicate incomplete or erroneous.
−7 | Information for this serial no longer available (only the most recent 10 are kept).
−8 | Internal program error. Notify maintainer.
File transfer with no error yet
0 | Transfer completed without error.
1 | Transfer is still in progress.
File transfer errors
12007 | Remote host not found. Check the network list.
TODO | Unable to connect to remote host.
12014 | Username or password for remote host incorrect. Check the network list.
12003 | Specified directory on remote node not found. Remember that the directory is relative to the remote node’s FTP root directory.
2 | Specified directory on local node not found. The source (FILE_SEND) or destination (FILE_FETCH) directory must exist.
87 | Remote node file format invalid or missing.
TODO | Specified file was not found on remote node (FILE_FETCH only).
2 | Specified file was not found on local node (FILE_SEND only).
12031 | Connection reset by remote server.
File compression errors
−1 | Error unpacking compress files message (details in Communicate log).
−2 | Error opening file in zip archive.
−3 | Error opening source file.
−4 | Error reading source file.
−5 | Error writing to zip file.
−6 | Error closing file in zip archive.
−7 | Error closing zip file.
−8 | No files matching specified pattern found in source directory.
−9 | Error creating zip file.
File uncompression errors
−11 | Error unpacking uncompress files message (details in Communicate log).
−14 | Destination directory isn’t a valid directory name, or directory doesn’t exist.
−15 | Destination directory does not exist.
−16 | Specified destination is not a directory.
−17 | Destination directory is read-only.
−18 | Destination directory is a system directory, so cannot be written to.
−19 | Error writing uncompressed file.
−20 | Error attempting to open compressed source (zip) file.
−21 | Error opening uncompressed file for writing.
−22 | Error while reading central directory of compressed source (zip) file.
−23 | Error while reading compressed file from zip archive.
−24 | Error while closing compressed source (zip) file.

Show example

This script illustrates FILE_FETCH, FILE_SEND and FileXferStatus(order). No file transfers have been done previously in this session.

Line# Script
   1 srcDirectory  = "C:\\A3O\\Master"
   2 srcFilename   = "TestFileXfer.txt"
   3 destNodeName  = "JWM-A3O"
   4 destDirectory = "A3O ftp testing"
   5 destFilename  = "TestFileXfer.txt"
   6
   7 st=FileXferStatus(0) // these should both be -1 (no status, because xfer hasn't taken place)
   8 st=FileXferStatus(1)
   9 FILE_SEND srcDirectory, srcFilename, destNodeName, destDirectory, destFilename
  10
  11 // Check send status periodically for 60 sec
  12 for (i=0; i<60; i=i+1)
  13 {
  14 	  st=FileXferStatus(0)
  15 	  if(st==1)
  16 	  {
  17 		DELAY 1 // continue to monitor
  18 	  }
  19 	  else
  20 	  {
  21 		i=60 // done--stop monitoring (Error if st!=0)
  22 	  }
  23 }
  24
  25 // Get the file back with a different name and directory
  26 fetchDirectory = "C:\\A3O\\Master\\MyLogs"
  27 fetchFilename  = "TestFileXferFetched.txt"
  28
  29 FILE_FETCH destNodeName, destDirectory, destFilename, fetchDirectory, fetchFilename

Master result log from the above:

05:04:26 1 Expr value: srcDirectory "C:\Miscellaneous\Meriwether\A3O\Master"
05:04:27 2 Expr value: srcFilename "TestFileXfer.txt"
05:04:29 3 Expr value: destNodeName "JWM-A3O"
05:04:35 4 Expr value: destDirectory "A3O ftp testing"
05:04:35 5 Expr value: destFilename "TestFileXfer.txt"
05:04:35 7 Expr value: st int -1  no xfers done yet
05:04:35 8 Expr value: st int -1
05:04:35 9 Expr value: srcDirectory "C:\A3O\Master"
05:04:35 9 Expr value: srcFilename "TestFileXfer.txt"
05:04:35 9 Expr value: destNodeName "JWM-A3O"
05:04:35 9 Expr value: destDirectory "A3O ftp testing"
05:04:35 9 Expr value: destFilename "TestFileXfer.txt"
05:04:35 12 Expr value: i int 0
05:04:35 12 Expr value: i bool true
05:04:35 14 Expr value: st int 1  xfer in progress
05:04:35 15 Expr value: bool true
05:04:35 17 Expr value: false int 1
05:04:36 12 Expr value: i int 1
...
05:04:56 12 Expr value: i int 20
05:04:56 12 Expr value: i bool true
05:04:56 14 Expr value: st int 1
05:04:56 15 Expr value: bool true
05:04:56 17 Expr value: false int 1
05:04:57 * Received message from Communicate: op=SendFile serial=115
05:04:57 12 Expr value: i int 21
05:04:57 12 Expr value: i bool true
05:04:57 14 Expr value: st int 0  xfer complete, no error
...
05:04:57 26 Expr value: fetchDirectory "C:\A3O\Master\MyLogs"
05:04:57 27 Expr value: fetchFilename "TestFileXferFetched.txt"
05:04:57 29 Expr value: destNodeName "JWM-A3O"
05:04:57 29 Expr value: destDirectory "A3O ftp testing"
05:04:57 29 Expr value: destFilename "TestFileXfer.txt"
05:04:57 29 Expr value: fetchDirectory "C:\A3O\Master\MyLogs"
05:04:57 29 Expr value: fetchFilename "TestFileXferFetched.txt"
...
05:04:57 * Received message from Communicate: op=FetchFile serial=116

Built-in subroutines

SolarPosition(time,&azimuthVariable,&zenithVariable)
LunarPosition(time,&azimuthVariable,&zenithVariable)

Places the position of the indicated body at the specified time into the variables named in the last two arguments.

These use JPL ephemeris Fortran program PLEPH (PLanetary EPHemeris) and the NOVAS functions julian_date, vector2radec, and equ2hor. The computed positions are based on the station location (station latitude, station longitude and station height in m), which are read from the Observatory control file. If Observatory is not running, the station location defaults to (−16.5, −71.5, 2200).

Show examples

// Get the angles to the sun at noon UTC
SolarPosition(12:00:00,&az,&ze)

//  Calculate angle to moon right now
LunarPosition($CurrentTime, &moonAz, &moonZe) // angles will be stored as reals in the variables moonAz, moonZe

ControlFileRead(filename, variablename1, variablename2,...)
or
error = ControlFileRead(filename, variablename1, variablename2,...)

Both forms read the file filename, a text file which should contain lines of the form

    variablename value
and stores the values into the script variables named by the subsequent arguments. filename is always .txt , but the .txt may be omitted in the script, and Master will add it to the filename.

The type of the script variable is determined by the format of the constants value. Existing values and types of the script variables which are arguments of ControlFileRead are lost.

The second form returns an integer value: 0 if no error occurred, a positive value for a file-related error, and a negative value for syntax or symbol errors (for these, the last three digits are the line number in the control file of the last error). The script must be prepared to handle these errors.

For the first form, if any of error occurs, an error dialog box appears, and script execution stops until an operator dismisses the error message.

Both forms log any errors to MasterErrors.

Show examples

// Re-read exposure times,to allow changes while the a script is running
ControlFileRead("XTimes","xTimeLaser","xTime630","xTimeDark")
The file XTimes.txt is
// Exposure times, all in integer seconds
xTimeLaser 30	// exposure in seconds for the camera imaging for laser (630)
xTime630   300	// seconds for nighttime 630 nm sky exposure
xTimeDark  350     // dark image exposure

After the ControlFileRead is executed, the variables xTimeLaser=30, xTime630=300, and xTimeDark=350, all integers. They need not have been defined previously; if they had been, the old values and type would be lost. The name in the ControlFileRead argument must exactly match the name in the control file.

ControlFileRead("Params","intParam","realParam","boolParam","timeParam")
The file Params.txt is
intParam      -3	// will be stored as a integer value
realParam    1.2	// will be stored as a real value
boolParam   true	// will be stored as a boolean value
timeParam  12:34	// will be stored as a time value

After the ControlFileRead is executed, the variables intParam=-3 (type integer), realParam=1.2 (type real), boolParam=true (type boolean), and timeParam=2012.1.25.12:34:00.000 (type time), assuming the date when read was 2012-1-25.

// Attempt to read a control file every 3 seconds until we succeed, or have tried 10 times
err = 1 // so we execute the loop the first time
for (tries = 0; tries < 10 && err != 0; tries = tries + 1)
{
    err = ControlFileRead("FickleFile.txt", "flyByNight")
    if(err != 0 )
    {
        DELAY 3
    }
}

ImageProperties(x0, y0, xSize, ySize, xBin, yBin, nBuckets, buck0, buck1, &count, &min, &max, &avg) [all args integer, except avg, which is real]

Note: The format of this function has changed; prior to Master v1.02, the arguments nBuckets, buck0, buck1 and count were not included. Any older scripts which used this function must be updated.

ImageProperties computes the number of superpixels in each of nBuckets rnages of superpixel values, as well as the minimum and maximum superpixels (integer), and average superpixel (real), for a rectangular region in the image currently being displayed by Analyze.

Each bucket is specified by its lower and upper limits, buck0 and buck1, respectively, which are superpixel values. The number of superpixels in bucket i (i e, buck0(i) ≤ superpixel value ≤ buck1(i)), will appear in count(i).

The output variables count, min, max and avg do not need to exist before invoking this function; they will be created if necessary.

If count exists, but is not an array, it will be converted to one. If it is already an array, but has fewer than nBuckets elements, it will be expanded. If it is an array of type other than integer, or has more than one subscript, it will be converted to an 1-D array of integers, and prior data will be lost.

If nBuckets is zero, the contents of the array count will be unchanged (and it will not be created if it doesn’t exist), but min, max, and avg will still be computed. The ranges of the buckets may overlap. The number of buckets cannot exceed 100, due to the limitation on array size.

If the number of buckets is more than 10, the first reference to buck0 and buck1 should have a subscript > 10, since the size of an array is set by the first reference. See here.

The region is defined by (x0, y0) as its lower-left corner, and has dimensions (xSize, ySize). Within that region, a superpixel will be calculated as the sum of xBin × yBin pixels. All the image pixels must be within the rectangular region for a superpixel to be computed.

The binning specified in ImageProperties is independent of any binning done by the camera. If a 1024×1024 image had been acquired using 2×2 binning, thus storing a 512×512 image, ImageProperties’s binning would further combine the superpixels stored by the hardware.

If there is no image displayed, Analyze will return zeros for min, max and avg, and count will be unchanged (or will not be created if it doesn’t exist) .

Show examples

Suppose a 1024×1024 image has pixel (x, y) = x + 2y, so the upper left corner of the image is

  0  1  2  3  4  5
  2  3  4  5  6  7
  4  5  6  7  8  9
  6  7  8  9 10 11
  8  9 10 11 12 13
 10 11 12 13 14 15
Then
loLimit(1)=4
loLimit(2)=6
loLimit(3)=10
hiLimit(1)=5
hiLimit(2)=8
hiLimit(3)=10
ImageProperties(0, 1, 3, 4, 1, 2, 3, loLimit, hiLimit, &histo, &min, &max, &avg)
will compute the statistics for the 3×4 pixel region shown in red, binning them into 6 1×2 super-pixels (6, 8, 10, 14, 16, 18).

After execution,
count(1)=0 (integer),
count(2)=2 (integer),
count(3)=1 (integer),
min=6 (integer),
max=18 (integer),
and avg=12 (real).

If instead, the binning had been 1×1, the results would have included
count(1)=3,
count(2)=5 and
count(3)=1,

To get just the statistics, without the histogram:
x0=1
y0=1
xSize=256 // assumes image is 256×256 or larger
ySize=256
xBin=1
yBin=1
// No buckets gets just min, max and avg.
dummy(1)=0 // not used, but must be defined.
ImageProperties(x0, y0, xSize, ySize, xBin, yBin, 0, dummy, dummy, &dummy, &min, &max, &avg)
To get a histogram of all pixel values in a 256×256 image (unbinned pixels are 0–65,535):
x0=1
y0=1
xSize=256
ySize=256
xBin=1
yBin=1

nBuckets=66000/1000 // i e, 66 buckets
buck0(nBuckets)=0 // force arrays to be large enough
buck1(nBuckets)=0
nBuckets=0
// 0-999, 1000-1999, ..., 65000-65999
for (p=0; p<66000; p=p+1000)
{
    nBuckets=nBuckets+1
    buck0(nBuckets)=p
    buck1(nBuckets)=p+(1000-1)
}
ImageProperties(x0, y0, xSize, ySize, xBin, yBin, nBuckets, buck0, buck1, &count, &min, &max, &avg)
The array count will be created with 101 elements, and the histogram will appear in count(1:66).

GaussianFit(nPoints, x, y, paramsInit, fixed, goal, maxIterations, &usedIterations, &paramsFit, &resid, &calc, &area)

Inputs:
nPoints is the number of points (x, y) to be fitted.

x, y are vectors of points to be fitted. Elements may be either integer or real, but all must be the same in a vector.

paramsInit is a real vector containing the initial guesses, or constant values, for the four parameters:
paramsInit(1)=baseline paramsInit(2)=amplitude paramsInit(3)=mean paramsInit(4)=std dev

fixed is a vector of booleans which specifies which of the four parameters is not to be varied. If all four fixed(i) are false, no fitting is done, but the sum of squares, calculated values and area are computed.

goal is a convergence criterion for the fit, either the fractional change of sumSquares between iterations, or the value of sumSquares. A positive value of goal is a fractional change; a negative value is −(the upper limit for sumSquares).

maxIterations is the number of iterations of the Gauss-Newton method to be used in attempting to reach the goal.

Outputs:
usedIterations is the number of iterations actually used. If it is not less than the limit in maxIterations, the fit may not have converged. Usually, that is due to the initial guesses being too far off, or extremely noisy data, or data that is not Gaussian in form.

paramsFit is a real vector containing the best-fit parameters.
paramsFit(1)=baseline paramsFit(2)=amplitude paramsFit(3)=mean paramsFit(4)=std dev
For parameters which are fixed, the value will be the same as the corresponding element of paramsInit.

resid is the sum of squares for the best fit, i e Σ(yi − yCalci)2.

calc is a real vector of the values calculated using the best-fit parameters.

area is the area under the calculated curve between x 1 and x nPoints.

The output variables need not exist prior to using GaussianFit. If they do exist, whatever data they contain will be overwritten.

Given data to be fitted, a way of choosing the initial guesses which usually works is to locate the minimum and maximum y i; then, let p(1)=min (baseline), p(2)=max (amplitude), p(3)=x i at the location of maximum y (mean), and make a reasonable guess for p(4) (std dev).

Show examples

Fit 50 points, stopping when there is a fractional change in the residuals of no more than 0.001, or when 30 iterations have been reached. The points to be fitted are in integer arrays x and y.

n=50

// Set the initial guesses
p(1)=0.0   // baseline
p(2)=600.0 // amplitude
p(3)=356.0 // mean
p(4)=15.5  // std dev

// Indicate that all are to be fitted (none is fixed)
fixed(1)=false
fixed(2)=false
fixed(3)=false
fixed(4)=false

GaussianFit(n, x, y, p, fixed, 0.001, 30, &pFit, &resid, &calc, &area)


Script-writing tips

Choose a coding style and use it for all scripts.

  • Standard way of including title, author, revision, parameters, etc.
  • Consistent formatting of loops, comments, code blocks, etc.

Use meaningful variable names.

Break long scripts up into modular parts, with well-defined interfaces.

Reuse variables for temporary quantities.

This is important because all variables have global scope. Unlike most programming languages, there are no local, automatic, or stack variables. Once a variable is created, it cannot be deleted, and there is a limit on the number of variables (currently 300).

Test all scripts in checkout mode.

Since scripts are not compiled, error-checking occurs at run time. Thus, you should run the script through as part of the testing procedure. Because some commands incur long delays, Master has an option checkout mode, which strictly limits all commands.

Look at Master error logs.

These logs should be empty, except for the header information. Any errors listed should be fixed. Scripts may keep running in the presence of errors, but may not produce the results you want.


Output to log files

Each of Master, Camera, Observatory, Analyze and Communicate creates one or more logs, for use in diagnosing problems with the program’s operations due to script errors, program bugs, or unexpected conditions. Analyze does not produce a standard log file, but instead has the “quick-look” output file, which contains results from processing the images.

The logs MasterUser n are written to by a user script only. MasterResults and MasterErrors consist primarily of results and errors from running a script, but may also have user-generated entries. A script outputs to a Master log file using LOG_DISPLAY.

The remaining logs (for Camera, Observatory, Analyze and Communicate) are written to only by the corresponding process.

A script can control the directory and filename for any log using LOG_DIRECTORY (exception: the directory for Analyze). All log files are of type .txt, which will be added to the end of the user-specified filename. This cannot be changed.

By default, log files accumulate as long as the corresponding A3O process is running. A script may close a log file and open a new one with a different name. It can also close a log file and reopen it; you do this to flush the output to the file and make it accessible to another program. Opening and closing of log files is done with the script command LOG_OUTPUT.

Each process uses default settings for the log file directories and filenames (e g, MasterResults_20120728130107.txt). See LOG_OUTPUT for details. Therefore, it is not necessary for a script to open a log file unless you have previously closed it.

All log files except Analyze
Output to the log files is buffered. The buffer holds 1,000 lines, and is displayed on the screen in the front panel of the A3O process. When the buffer is full, it is written to the corresponding log file, and the screen display is cleared.

Log files are not created, opened, or reopened on disk until the buffer is written. After each buffer write, the disk file is closed, to allow access by other programs. When the buffer is full, the log file is opened for appending (previous contents preserved), unless LOG_OUTPUT specified OVERWRITE. For OVERWRITE, the file is opened for writing (previous contents lost).

Analyze log file only
The Analyze log (i e, the “quick-look” file) is created and opened when the first image is displayed. The file remains open until Analyze exits, or a LOG_OUTPUT Analyze, CLOSE is received from Master. While it is open, the quick-look file can't be read by other software.

Example: Standard log file naming, separate log for each session

// Come here at the start of each session to open a new set of Master log files
LOG_OUTPUT Master, CLOSE
LOG_OUTPUT Master, OPEN

// The default directories are used, the same as the executables.
// The default filenames are used, e g, MasterResults_20030728130107.txt.
// Because the filename will include a timestamp,
// there won't be an existing file with the same name.

// Repeat the above for the other processes
LOG_OUTPUT Camera, CLOSE
LOG_OUTPUT Camera, OPEN
LOG_OUTPUT Observatory, CLOSE
LOG_OUTPUT Observatory, OPEN
LOG_OUTPUT Analyze, CLOSE
LOG_OUTPUT Analyze, OPEN
LOG_OUTPUT Communicate, CLOSE
LOG_OUTPUT Communicate, OPEN

Example: Standard log file naming, different directory for each day

// Come here at the start of each day to open a new set of Master log files
// Make a directory which is of form yyyy-mm-dd
yr = DateToInteger($CurrentTime) // yyyymmdd
mo = yr / 100
day = yr - mo * 100
yr = mo / 100
mo = mo - yr * 100
directory="D:\\Data " + ConvertToString("%04d-", yr) + ConvertToString("%02d-", mo) + ConvertToString("%02d", day)

LOG_DIRECTORY Master, directory

Example: Customized log file naming, directory for each day of the week, constant log filename

// Come here at the start of each day to overwrite the User2 log file
// Directories will be Log_n, with n=0,...,6 for Sunday,..., Saturday
n=$DayNumber+4 // to make Sunday 0 mod 7
n=n-((n/7)*7)
directory=ConvertToString("D:\\Data\\Log_%d",n)

// Make the MasterUser2 file have the name "MyOutputFile.txt" by making its
// ID MyOutputFile and omitting process name and timestamp
LOG_DIRECTORY MasterUser2, directory, "MyOutputFile", 3
LOG_DISPLAY 2 "Initial MasterUser2 line"

// Close the previous output file (in the prior directory) and open a new one
LOG_OUTPUT MasterUser2, CLOSE
// After this, D:\Data\Log_N\MyOutputFile.txt will contain the single line "Initial MasterUser2 line"

LOG_OUTPUT MasterUser2, OVERWRITE // this will overwrite an existing file with the same name
LOG_DISPLAY 2 "Second MasterUser2 line"
LOG_OUTPUT MasterUser2, CLOSE
// After this, D:\Data\Log_N\MyOutputFile.txt will contain the single line "Second MasterUser2 line"

// Other log files (MasterResults, MasterErrors, MasterUser1, MasterUser3) are not affected.


Script commands

These are the commands that are recognized by the script interpreter. The commands themselves must be all upper-case, as shown here, although their arguments are upper- and lower-case.

General-purpose

DELAY integer-valued-expression | ♦ | Pause script execution for integer-valued-expression seconds.
WAIT_UNTIL time-valued-expression | ♦ | Pause script execution until the specified time.
OVERLAY string-valued-expression | ♦ | Load the script file named and begin execution. No return is possible.
CALL string-valued-expression | ♦ | Load the script file named and begin execution, returning when done.
RETURN | ♦ | Reload the script file that called us.
LOG_DIRECTORY origin origin is Master, Camera, Observatory or Analyze; or MasterResults, MasterErrors, MasterUser1-3 . , directory [, id [, order]] | ♦ | Change the directory where the log files are written for origin to the string-valued-expression directory. Optional string-valued-expression id is a string of up to 99 characters to appear in the file name. Optional integer-valued-expression order is an integer with digits 1,2,3, specifying the positions of origin, the time and id in the filename.
LOG_OUTPUT origin origin is Master, Camera, Observatory or Analyze; or MasterResults, MasterErrors, MasterUser1-3 . , action action = OPEN, OVERWRITE or CLOSE. | ♦ | Start or stop the log for the named program. Logs are named by date and time they are started (opened).
LOG_DISPLAY log log = R, E, 1, 2, 3, O, C for Master results, Master errors, Master user logs 1-3, Observatory and Camera, respectively. string-valued-expression | ♦ | Appends a line consisting of string-valued-expression to the specified log display and the corresponding log file.

Camera operation

SETUP CAMERA unitname ♦ Tells Camera to initialize camera unitname.
SETUP COOLER unitname ♦ Tells Camera to initialize the cooler associated with camera unitname.
SHUTDOWN CAMERA unitname ♦ Tells Camera to shut down camera unitname.
SHUTDOWN COOLER unitname ♦ Tells Camera to turn off the cooler of camera unitname.
SET_PARAMETER CAMERA unitname unitname is FPI or SkyMon , paramSetName paramSetName is one of the following:
AcqMode
ADChannel
AntiBloomGate
AuxPort=n (followed by , value)
CoolerMode
EMAdvanced
EMCCDGain
EMGainMode
ExposureTime
FanMode
FinalTemp
FullImageCol0
FullImageCol1
FullImageRow0
FullImageRow1
HorizonBin
OutputAmpType
PreAmpGain
ReadMode
ShiftSpeedH
ShiftSpeedV
ShutterCloseT
ShutterMode
ShutterOpenT
ShutterType
Temperature
TrigMode
VerticalBin
 Bold entries do not appear in SET_PARAMETER CAMERA. =value 		♦ Change a value in the camera’s parameter table or change a camera control value.
GET_PARAMETER CAMERA unitname unitname is FPI or SkyMon , paramGetName paramGetName is one of the following:
AcqMode
ADChannel
AntiBloomGate
CoolerMode
EMAdvanced
EMCCDGain
EMGainMode
ExposureTime
FanMode
FinalTemp
FullImageCol0
FullImageCol1
FullImageRow0
FullImageRow1
HorizonBin
OutputAmpType
PreAmpGain
ReadMode
ShiftSpeedH
ShiftSpeedV
ShutterCloseT
ShutterMode
ShutterOpenT
ShutterType
TrigMode
VerticalBin
 , variable variable is the name of the script variable to receive the value 		♦ Retrieve a value from the camera’s parameter table.
TAKE_IMAGE unitname, imagetype ♦ Start image acquisition, using the values in camera’s parameter table.
COPY_IMAGE unitname ♦ Transfer the image from the camera to computer memory.
SAVE_IMAGE filename ♦ Store an image from computer memory into a disk file.
GET_STATUS CAMERA unitname unitname is FPI or SkyMon , parameterName parameterName is State, Temperature, or AuxPort=n , variable ♦ Get the camera’s status bits. When parameterName=State, the meaning depends on the camera model.

FPI operation

SETUP FPI unitname unitname must be SkyScan | ♦ | Tells Observatory to initialize the device unitname.
SHUTDOWN LASER unitname | ♦ | This command is not yet implemented.
SHUTDOWN PHdome unitname | ♦ | This command is not yet implemented.
SHUTDOWN OTHER unitname | ♦ | This command is not yet implemented.
SELECT_FILTER | ♦ | Moves a filter into the optical path, either for the FPI or for the sky monitor camera.
MOVE_PH azimuth, zenith | ♦ | Position the pointing head to the indicated angles.
SELECT_SCENE view view = LASER or SKY. | ♦ | Moves the FPI’s mirror so the interferometer sees the named object.
SHUTTER [name,] state state = OPEN or CLOSE. | ♦ | Open or close the named USB shutter, or the older unnamed shutter.
EXTENDER position position = IN or OUT. | ♦ | Positions the optical extender.
GET_STATUS OBSERVATORY, parameterName, variable | ♦ | Request the current value of parameterName from Observatory; store into variable.

Image display

SETUP ANALYZE | ♦ | Tells Analyze to assume an initial state.
DISPLAY_IMAGE image | ♦ | Tells Analyze to display the named image file.
ANALYZE_IMAGE | ♦ | This command is not yet implemented.

Observatory conditions

GET_STATUS OBSERVATORY, parameterName, variable | ♦ | Request the current value of parameterName from Observatory; store into variable.
PULSE channel, direction direction = POS or NEG , duration | ♦ | Tells Observatory to pulse one of the digital output channels for duration msec.
LEVEL channel, level level = 0 or 1 | ♦ | Tells Observatory to set one of the digital output channels to level.


Script command ANALYZE_IMAGE

ANALYZE_IMAGE is not yet implemented.


Script command CALL

CALL string-valued-expression

CALL changes the script execution to a different file, the called script, named by string-valued-expression. Upon encountering a RETURN in the called script, execution resumes in the caller.

A similar command, OVERLAY, allows transfer of execution to another script without returning.

The string-valued-expression is the name of the file containing the called script. Like all script files, the file itself must have the extension .txt, but this may be omitted in string-valued-expression.

Either a complete or relative path may be given. A relative path is relative to the current working directory. The working directory may change when Master uses the function ControlFileRead.

Examples:

Main.txt                     Subroutine.txt
// The calling script     // The called script
x = 1.23                  x = x + 10
CALL "Subroutine"         RETURN
// now x = 11.23

C:\A3O Programs\Main.txt                   E:\A3O Temporary\Sub4.txt
// The calling script                // The called script
disk = "E:"                          if(subName=="Sub4")
tempDir = disk + "\\A3O Temporary"   {
subName = "Sub4"                         CALL Sub4A
CALL tempDir + subName               }
                                     CALL Sub4B
                                     RETURN
The order of execution is the first four lines of Main, then the first two lines of Sub4, followed by all the lines of Sub4A (since the if condition will be true), the lines of Sub4B, and then back to Main.

Remember that variable names are not unique to a subroutine; they are all global in scope.

It is possible for a script to call itself (recursion). There must be an explicit mechanism for returning without a self-call, or you will have an infinite loop (and subsequent crash).


Script command COPY_IMAGE

COPY_IMAGE unitname

This command causes Master to send a message to Camera to transfer image data from the camera to computer memory. In normal use, you would first have acquired an image using TAKE_IMAGE , and following COPY_IMAGE you would use SAVE_IMAGE to store the image as a disk file.

The camera is identified by unitname, which is either FPI (e g, the Andor camera which captures the interferograms) or SkyMon (e g, the SBIG camera which monitors the sky image).

The size and boundaries of the image copied, as well as the shift speeds and other parameters of image transfer, are determined by Camera’s parameter table.

Example:

// Acquiring, copying, and storing an image
SET_PARAMETER CAMERA FPI, ShutterMode = AUTO // setting these is only necessary if they were not already set
SET_PARAMETER CAMERA FPI, ExposureTime = 3.5 // either by a previous SPC or from the Camera control file
TAKE_IMAGE FPI,"A" // the image type is arbitrary
DELAY 4 // in practice, this would more likely involve polling the camera periodically
COPY_IMAGE FPI
SAVE_IMAGE "MyImageFile.img" // image filenames are arbitrary, although it is wise to establish conventions.


Script command DELAY

DELAY integer-valued-expression

When a script encounters this command, execution of the script is suspended for integer-valued-expression seconds. This suspension only affects Master itself; other processes continue to run, and any messages they send to Master will be queued until the script resumes. See also WAIT_UNTIL.

Example:

// Allow cooler to cool down.  Let it reach -78 degrees C or time out after 8 minutes.
startCheckingTime=$CurrentTime
CoolingStatus = 0
while(CoolingStatus == 0)
{
    GET_STATUS CAMERA FPI, TEMPERATURE, temperature
    if(temperature <= -78.0)
    {
        CoolingStatus = 1
    }
    if( $CurrentTime-startCheckingTime >= (8*60) )
    {
        CoolingStatus = 1
    }
    DELAY 30 // wait 30 seconds
}
When a script is run in checkout mode, the delay will be a maximum of 3 seconds.


Script command DISPLAY_IMAGE

DISPLAY_IMAGE image

Tells Analyze to load and display an image file. image can be either a complete path, or a filename in the most-recently-used directory. It’s best to use the full path.

Examples:

DISPLAY_IMAGE "E:\\MyImageDirectory\\L20120309.img"
Note that \\ is required to get a single \ in the string constant.

seq=0
dir="C:\\AkFPIImageA\\"
today=DateToInteger($CurrentTime) // yyyymmdd (integer)
date=ConvertToString("%d",today) // "yyyymmdd"
seq=seq+1
dataType="X"
serialNumber = ConvertToString("%03d",seq) // "001"
imageName = dir + dataType + date + serialNumber + ".img"
DISPLAY_IMAGE imageName // displays the image file C:\AkFPIImageA\X20120318001.img,
                        // assuming today's date is 2012-3-18


Script command EMAIL_SEND

EMAIL_SEND to, from, cc, subject, body.

The purpose of this command is to send an email message from the local machine via a SMTP (Simple Mail Transfer Protocol) server. Email is sent using SSL (Secure Socket Layer). The default SMTP server is an entry in the Communicate control file. The server can be changed with EMAIL_SET_SERVER.

The parameters are

Parameter | Data type1 | Meaning | Examples
tostring Email address of the primary recipient. If the string is empty2, the default to for this SMTP server is used. "John Doe" <john.doe@myISP.net>
<john.doe@myISP.net>
john.doe@myISP.net
from string Email address of the sender. This must be acceptable to the SMTP server. If the string is empty2, the default from for this SMTP server is used "Jon Dough" <Dough_Jon@yourISP.com>
<Dough_Jon@yourISP.com>
Dough_Jon@yourISP.com
cc string Email address of a secondary recipient. Null string if none. "Juan D'Oh" <dohj@hisISP.com>
<dohj@hisISP.com>
dohj@hisISP.com
subject | string | Brief description of the message topic. | 2013-9-23 data ready for pickup
body string
or
string array 		Text of the message. If the parameter is string, that string is the entire text. If it is string array, each array element is a single line of the text. Single line: Brevity is the soul of wit.

See below for example of a string array.
1) string means an expression that evaluates to a string, but string array means the name of an 1-dimensional array of strings (expressions are not allowed).
2) An empty string is one of zero length, e g, mt="".

Examples:

EMAIL_SEND "you@yourplace.edu", "me@myplace.edu", "him@hisplace.edu", "Twain on politics", "Politics is the art of looking for trouble, finding it, misdiagnosing it and then misapplying the wrong remedies."
Sends an email from me to you, copy to him. Subject is "Twain on politics". The message will be a single line.
part1="Politics is the art of looking for trouble"
part2="finding it"
part3="misdiagnosing it and then misapplying the wrong remedies."
EMAIL_SEND "", "", "him@hisplace.edu", "Twain on politics", part1+", "+part2+", "+part3
Same message text as the first example, except the default email addresses for the current SMTP server will be used. A string expression is used to create the single-line message.
from="you@yourplace.edu"
to="me@myplace.edu"
title="The Walrus and the Carpenter"
type="excerpt"

line(1)="\"The time has come,\" the Walrus said,"
line(2)="\"To talk of many things:"
line(3)="Of shoes -- and ships -- and sealing-wax --"
line(4)="Of cabbages -- and kings --"
line(5)="And why the sea is boiling hot--"
line(6)="And whether pigs have wings.\""

EMAIL_SEND to, from, "", title+" "+type, line
Sends an email from you to me, no cc. Subject is “The Walrus and the Carpenter excerpt”. The body of the message will be six lines long, and will read
"The time has come," the Walrus said,
"To talk of many things:
Of shoes -- and ships -- and sealing-wax --
Of cabbages -- and kings --
And why the sea is boiling hot--
And whether pigs have wings."

In this example, note the use of \" to include quotation marks in the string literals. Also, storing the string line(1) creates a string array line(0:10). Because line(0) has not been defined, it will not be used in the email.

The subject in this example is a string expression, the concatenation of three strings, title+" "+type.

Because there is no way to remove a string array once it has been created (by an assignment to one of its elements), EMAIL_SEND removes all leading undefined or empty strings at the beginning and end of a string array you specify as the body. In the last example above, line(0) was removed because it was never defined (assuming no code prior to the example). If you later wanted to use the same array line to send a 3-line message, you could use something like

line(1)="My new message has only"
line(2)="three"
line(3)="lines."
line(4)=""
line(5)=""
line(6)=""
and the lines 4−6 will not appear in the message.


Script command EMAIL_SET_SERVER

TO DO


Script command EXTENDER

EXTENDER position
position = IN or OUT.

A message is sent to Observatory to move the optical extender to the indicated position. IN is for visible, and OUT is IR.

The digital I/O lines used, level for each position, and input value for each position are all determined by the Observatory control file.


Script command FILE_COMPRESS

FILE_COMPRESS sourceDirectory, sourcePattern, destDirectory, destFilename.

The purpose of this command is to compress files on the local machine. One or more files are packed into a single archive. Currently, only the zip protocol is used for compression.

To use FILE_COMPRESS, sourceDirectory and destDirectory must exist on the local machine. If destFilename already exists, it will be overwritten. The sourceDirectory and destDirectory may be the same.

sourcePattern may be either a single existing filename, or a pattern including the wildcards “*” and “?”. The pattern is interpreted by the Windows file system, which uses “*” to mean any number of characters, and “?” to mean a single character.

To use this command, Communicate must be running on the local machine.

The status of the most recent 10 file-handling requests may be obtained using FileXferStatus(order).

Examples:

// Compress a single image file
imageDir="E:\\MyImageDirectory"
compressedImageDir="D:\\A3O\\Laser images"
FILE_COMPRESS imageDir, "L20120309.img", compressedImageDir, "L20120309.zip"
Note that \\ is required to get a single \ in the string constant.

// Create a zip file containing all the images in the directory
imageDir="C:\\EKU_FPIImages"
zipDir="C:\\EKU_FPIImagesCompressed"
today=DateToInteger($CurrentTime) // yyyymmdd (integer)
date=ConvertToString("%d",today) // "yyyymmdd"
zipFilename= date + ".zip"
FILE_COMPRESS imageDir, "*.img", zipDir, zipFilename
If today is 2013-1-2, and directory C:\EKU_FPIImages contains the files
EKU_L_20130101_235959_001.img
EKU_Z_20130102_000001_001.img
EKU_X_20130102_000015_002.img
EKU_X_20130102_000130_003.img
Happy new year.txt
a single archive 20130102.zip, containing four image files, will be created in directory C:\EKU_FPIImagesCompressed.


Script command FILE_COPY

FILE_COPY sourceDirectory, sourcePattern, destDirectory.

The purpose of this command is to copy files from one directory to another on the local machine. It cannot be used to transfer files to another A3O node; for that, use FILE_SEND.

To use FILE_COPY, sourceDirectory and destDirectory must both exist on the local machine. If any of the referenced files already exist in destDirectory, they will be overwritten. The sourceDirectory and destDirectory cannot be the same.

sourcePattern may be either a single existing filename, or a pattern including the wildcards “*” and “?”. The pattern is interpreted by the Windows file system, which uses “*” to mean any number of characters, and “?” to mean a single character.

To use this command, Communicate must be running on the local machine.

The status of the most recent 10 file-handling requests may be obtained using FileXferStatus(order).

A related command is FILE_MOVE.

Examples:

// Copy a single image file
imageDir="E:\\MyImageDirectory"
specialImageDir="D:\\A3O\\MySpecialImages"
FILE_COPY imageDir, "L20120309.img", specialImageDir
After completion, one copy of L20120309.img will be in each directory.

Note that \\ is required to get a single \ in the string constant.

// Copy all the images in the directory
imageDir="C:\\EKU_FPIImages"
allImageDir="D:\\A3O\\All_my_images"
FILE_COPY imageDir, "*.img", allImageDir
If directory C:\EKU_FPIImages contains the files
EKU_L_20130101_235959_001.img
EKU_Z_20130102_000001_001.img
EKU_X_20130102_000015_002.img
EKU_X_20130102_000130_003.img
Happy new year.txt
the four image files will be copied to directory D:\\A3O\\All_my_images. After this operation, directory C:\EKU_FPIImages will still contain the same five files.


Script command FILE_DELETE

FILE_DELETE sourceDirectory, sourcePattern, destDirectory.

The purpose of this command is to remove files from a directory on the local machine.

To use FILE_DELETE, sourceDirectory must exist on the local machine.

sourcePattern may be either a single existing filename, or a pattern including the wildcards “*” and “?”. The pattern is interpreted by the Windows file system, which uses “*” to mean any number of characters, and “?” to mean a single character.

To use this command, Communicate must be running on the local machine.

The status of the most recent 10 file-handling requests may be obtained using FileXferStatus(order).

Examples:

// Delete a single image file
imageDir="E:\\MyImageDirectory"
FILE_DELETE imageDir, "L20120309.img"
Note that \\ is required to get a single \ in the string constant.

// Delete all the images in the directory
imageDir="C:\\EKU_FPIImages"
FILE_DELETE imageDir, "*.img"
If directory C:\EKU_FPIImages contains the files
EKU_L_20130101_235959_001.img
EKU_Z_20130102_000001_001.img
EKU_X_20130102_000015_002.img
EKU_X_20130102_000130_003.img
InstallationLog.txt
after this operation, directory C:\EKU_FPIImages will contain only the file InstallationLog.txt.


Script command FILE_FETCH

FILE_FETCH sourceNodeName, sourceDirectory, sourceFilename, destDirectory, destFilename.

The purpose of this command is to transfer files from a remote A3O machine on the network (node) to the local machine. Files are transferred using FTP (File Transfer Protocol) or sFTP (Secure FTP), so the remote machine must have an FTP or sFTP server. Which of these protocols is used is determined by the serverName field in the Communicate control file.

To use FILE_FETCH, sourceDirectory and and sourceFilename must exist on the remote machine, and destDirectory must exist on the local machine. If destFilename already exists on the local machine, it will be overwritten.

For more information, see File transfer operations in Communicate.


Script command FILE_MOVE

FILE_MOVE sourceDirectory, sourcePattern, destDirectory.

The purpose of this command is to move files from one directory to another on the local machine. It cannot be used to transfer files to another A3O node; for that, use FILE_SEND.

To use FILE_MOVE, sourceDirectory and destDirectory must both exist on the local machine. If any of the referenced files already exist in destDirectory, they will be overwritten. The sourceDirectory and destDirectory cannot be the same.

sourcePattern may be either a single existing filename, or a pattern including the wildcards “*” and “?”. The pattern is interpreted by the Windows file system, which uses “*” to mean any number of characters, and “?” to mean a single character.

To use this command, Communicate must be running on the local machine.

The status of the most recent 10 file-handling requests may be obtained using FileXferStatus(order).

A related command is FILE_COPY.

Examples:

// Move a single image file
imageDir="E:\\MyImageDirectory"
allImageDir="D:\\A3O\\All_my_images"
FILE_MOVE imageDir, "L20120309.img", allImageDir
Note that \\ is required to get a single \ in the string constant.

// Move all the images in the directory
imageDir="C:\\EKU_FPIImages"
allImageDir="D:\\A3O\\All_my_images"
FILE_MOVE imageDir, "*.img", allImageDir
If directory C:\EKU_FPIImages contains the files
EKU_L_20130101_235959_001.img
EKU_Z_20130102_000001_001.img
EKU_X_20130102_000015_002.img
EKU_X_20130102_000130_003.img
Happy new year.txt
the four image files will be moved from directory C:\EKU_FPIImages to directory D:\\A3O\\All_my_images. After this operation, directory C:\EKU_FPIImages will contain only the file Happy new year.txt.


Script command FILE_SEND

FILE_SEND sourceDirectory, sourceFilename, destNodeName, destDirectory, destFilename.

The purpose of this command is to transfer files from the local machine to another A3O machine on the network (node). Files are transferred using FTP (File Transfer Protocol) or sFTP (Secure FTP), so the remote machine must have an FTP or sFTP server. Which of these protocols is used is determined by the serverName field in the Communicate control file.

To use FILE_SEND, sourceDirectory and sourceFilename must exist on the local machine, and destDirectory must exist on the remote machine. If destFilename already exists on the remote system, it will be overwritten.

For more information, see File transfer operations in Communicate.

The status of the most recent 10 file transfer requests may be obtained using FileXferStatus(order).

For an example, see FileXferStatus(order).


Script command FILE_UNCOMPRESS

FILE_UNCOMPRESS sourceDirectory, sourceFilename, destDirectory.

The purpose of this command is to uncompress files on the local machine. A single archive may contain one or more files. Currently, only the zip format is supported.

To use FILE_UNCOMPRESS, sourceDirectory and destDirectory must exist on the local machine. The command uncompresses all the files in the archive into the destination directory. Files retain their original names and file times (creation and modification). If any of the files already exist, they will be overwritten.

The sourceDirectory and destDirectory may be the same.

sourceFilename must be a zip-formatted file. Such a file can be produced by FILE_COMPRESS, by Windows file compression, or by a compression program such as WinZip. Non-zip formats, such as gzip, rar, or 7-zip, are not supported.

FILE_COMPRESS and FILE_UNCOMPRESS both preserve the file creation, modification and access times.

The status of the most recent 10 file-handling requests may be obtained using FileXferStatus(order).

To use this command, Communicate must be running on the local machine.

Example:

// Assume a zip file 20130110.zip in C:\CompressedData has previously been created,
// e g, by FILE_COMPRESS. Now we want to recover these image files.
zipDir = "C:\\CompressedData"
today = 20130110 // yyyymmdd (integer)
date = ConvertToString("%d",today) // "yyyymmdd"
zipFilename = date + ".zip"
imageDir = "C:\\ImageData\\2012-10-3 PKR images"
FILE_UNCOMPRESS zipDir, zipFilename, imageDir

// Check send status periodically for 5 minutes
for (i=0; i<60; i=i+1)
{
      st=FileXferStatus(0)
      if(st==1)
      {
        DELAY 5 // continue to monitor
      }
      else
      {
        i=60 // done--stop monitoring (Error if st!=0)
      }
}
// Expect st=0
All the files that were compressed into 20130110.zip will be extracted (uncompressed) into the directory C:\ImageData\2012-10-3 PKR images. If any of those files already existed, they will be overwritten.


Script command GET_PARAMETER (Camera)

GET_PARAMETER CAMERA unitname, paramGetName, variable

Retrieve a value from the specified camera’s parameter table. The parameter tables are initialized from Camera’s control file, and may be modified by SET_PARAMETER CAMERA.

The following table shows the possible parameter names and the type of value that will be retrieved into variable.

Parameter name | Value type returned | Parameter name | Value type returned
AcqMode | string | HorizonBin | integer
ADChannel | integer | OutputAmpType | integer
AntiBloomGate | integer | PreAmpGain | real
CoolerMode | integer | ReadMode | string
EMAdvanced | integer | ShiftSpeedH | real
EMCCDGain | integer | ShiftSpeedV | real
EMGainMode | integer | ShutterCloseT | integer
ExposureTime | real | ShutterMode | string
FanMode | integer | ShutterOpenT | integer
FinalTemp | integer | ShutterType | string
FullImageCol0 | integer | TrigMode | string
FullImageCol1 | integer | VerticalBin | integer
FullImageRow0 | integer
FullImageRow1 | integer

Example:

// Set the exposure time for the FPI camera to t+1.23 seconds (t already defined as integer or real).
SET_PARAMETER CAMERA FPI, ExposureTime=t+1.23
// Read it back from the FPI camera's parameter table, storing in tOut
GET_PARAMETER CAMERA FPI, ExposureTime, tOut // should be t+1.23


Script command GET_STATUS (Camera)

GET_STATUS CAMERA unitname, parameterName, variable

This command tells Master to send a message to Camera requesting the camera’s status.

The parameterName is one of State, Temperature or AuxPort=n. Camera’s response will be stored in variable.

For AuxPort=n, the value of n must be 1–4. This feature is only available on Andor cameras; it is the state of the TTL Auxiliary Input Port on the Andor plug-in card. The value stored will be either 0 (off, or low) or any non-zero value (on, or high).

When the parameterName is State, the value returned in variable will be the camera’s status bits. The meaning of this value depends on the camera model. For instance, the Andor camera can return the following (among many others):

Symbol used by Andor | Value | Meaning
DRV_ACQUIRING | 20072 | Acquisition in progress.
DRV_IDLE | 20073 | The system is not currently acquiring.
DRV_TEMPCYCLE | 20074 | Executing temperature cycle.
DRV_NOT_INITIALIZED | 20075 | System not initialized.

Example:

// Acquire an image from the FPI camera, waiting until the exposure is complete

SET_PARAMETER CAMERA FPI, ExposureTime=1.5 // change the exposure time to 1.5 sec
TAKE_IMAGE FPI

checkCount = 0
currentState  = 0 // so the 'while' condition is false the first time through

// Check the status every second, or until 10 sec has elapsed
while(currentState != 20073 && checkCount < 10)
{
    DELAY 1
    GET_STATUS CAMERA FPI, STATE, currentState
    checkCount = checkCount+1
}


Script command GET_STATUS (Observatory)

GET_STATUS OBSERVATORY, parameterName, variable

parameterName is one of AZIMUTH, ZENITH, PRESSURE, TEMPERATURE, DIGITAL_INPUT or ANALOG_INPUT. These are not case-sensitive, so, for instance, AZIMUTH, Azimuth and azimuth are equivalent.

For the DIGITAL_INPUT and ANALOG_INPUT, the name is followed by =channelNumber.

GET_STATUS OBSERVATORY tells Master to send a message to Observatory requesting the specified value. When Observatory responds, the value will be stored into variable.

Examples:

// Get the current pointing head position into (az, ze)
GET_STATUS OBSERVATORY, AZIMUTH, az
GET_STATUS OBSERVATORY, ZENITH, ze

// Do not take data if the ambient temperature sensor reads more than 4 volts
GET_STATUS OBSERVATORY, Temperature, ambient
OKtoTakeData = ambient <= 4.0

// Thermistor Test
// Take 100 samples, one every 3 seconds, from analog input channels 4-7.
// Display results in user log 1 window.
for (i = 0; i < 100; i = i+1)
{
    for (ch = 4; ch <= 7; ch = ch+1)
    {
        GET_STATUS OBSERVATORY, ANALOG_INPUT=ch, aIn
        chName=ConvertToString("Analog input %d: ",ch) // ConvertToString only converts a single expression
        LOG_DISPLAY 1 chName+ConvertToString("%f",aIn)
    }
    DELAY 3
}
The ambient temperature and pressure sensors are connected to analog inputs. The Observatory control file variables AInChan_Temp, AInType_Temp, AInRangeMin_Temp, AInRangeMax_Temp, AInConvA_Temp, AInConvB_Temp; AInChan_Press, AInType_Press, AInRangeMin_Press, AInRangeMax_Press,AInConvA_Press, AInConvB_Press specify the connections for temperature and pressure, respectively.


Script command LEVEL

LEVEL channel, level

LEVEL causes a message to be sent to Observatory, instructing it to set the digital output channels channel to level.

The digital output channel must be an existing digital output channel; valid channel numbers are 0 – n−1, where n depends on both the hardware and, for some hardware, the configuration of digital inputs and outputs determined by the Observatory control file. The digital I/O configuration is shown in the Observatory log. Here are excerpts from a sample log, for a system with a DT-9812 module.

Board name="DT9812-10V(02)"
Board entry="DT9812"
...
Subsystem "AD Unit 0" is type analog input  Element 0 has 8 channels
...
Subsystem "DA Unit 0" is type analog output  Element 0 has 2 channels
...
Subsystem "DIN Unit 0" is type digital input  Element 0 has 1 channels
...
Subsystem "DOUT Unit 0" is type digital output  Element 0 has 1 channels
...
Subsystem "CT Unit 0" is type counter/timer  Element 0 has 1 channels
Subsystem enumeration: nAD=1 nDA=1 nDIn=1 nDOut=1 nCtrTim=1 nDIOBits=16
The log uses the Data Translation nomenclature for channel, while this documentation uses “channel” to mean a single analog or digital I/O line. A Data Translation digital channel has 8 I/O lines; i e, 8 A3O channels. For this hardware, which is not affected by the Observatory control file, the digital channels are numbered 0–7.

Example:

// Change the level of digital output to TTL hi for 5 seconds
LEVEL 4, 1
DELAY 5
LEVEL 4, 0
A related command PULSE could have been used for the same purpose.


Script command LOG_DIRECTORY

LOG_DIRECTORY origin, directory [,id [,order]]

The purpose of this command is to specify the naming and location of the log files.

Each of Master, Camera, Observatory,Analyze and Communicate creates one or more logs, for use in diagnosing problems with the program’s operations due to script errors, program bugs, or unexpected conditions. Analyze does not produce a standard log file, but instead has the “quick-look” output file, which contains results from processing the images.

The most recent part of each log is displayed on the screen in a scrollable window (except in Analyze). As the size of the log grows, the older parts are copied to a file. In addition, the most recent part of each log can be copied to the Windows clipboard using a button on the Master, Camera or Observatory front panel, from which it can be pasted into documents or e-mail.

The log file names are customizable, with certain restrictions. There are three parts, from which any one, two or three may be chosen. The order of the parts may also be specified. Log files always have the extension .txt.

The three possible parts are the creator, a timestamp (date and time), and the ID (an arbitrary string).

The origin includes the creating process, and for Master, a qualifier. Origins are

MasterResults
MasterErrors
MasterUser1, 2 and 3
Camera
Observatory
Analyze
Communicate

The timestamp contains the date and time of the log file creation, in the form

yyyymmddhhmmss
The ID is a user-selected identifier of up to 99 characters. The characters must be legal in a Windows filename, which means it cannot include the characters < > : " / \ |.

The log file name is formed from the three parts described above:

1) Creator (process name and qualifier, separated from other parts with _ )
In previous versions of Master, an _ was not used before the process name in every case.
2) Creation time
3) Identifier

The user specifies the order in which these three parts are combined, using

  • a permutation of 123, to include all three parts;
  • a permutation of 12, 13 or 23 to include two parts; or
  • 1, 2 or 3 to include only a single part.

    Note: If only the identifier is included (i e, 3), the qualifier will be omitted in the filename. Qualifiers are only used for Master, and they are Results, Errors, User n.

The default directory for each log file is the directory of the program, except for Analyze, where the directory is always the same location as the first image.

The default order for the log file name parts is 1, 2, 3. The default filenames are

Created by | Default format | Example default file name
Master | MasterErrors_YYYYMMDDhhmmss.txt | MasterErrors_20030728130107.txt
Master | MasterResults_YYYYMMDDhhmmss.txt | MasterResults_20030728130107.txt
Master | MasterUser n_YYYYMMDDhhmmss.txt n = 1, 2, 3 | MasterUser1_20030728130107.txt
Observatory | Observatory_YYYYMMDDhhmmss.txt | Observatory_20030710141432.txt
Camera | Camera_YYYYMMDDhhmmss.txt | Camera_20030710134721.txt
Analyze | Analyze_YYYYMMDDhhmmss.txt | Analyze_20120308183753.txt
Communicate | Communicate_YYYYMMDDhhmmss.txt | Communicate_20120308183753.txt

YYYY=year, MM=month, DD=day of month, hh=hour (24-hour clock), mm=minute, ss=second that the program was started (or time that log file was opened, if the log file has been CLOSEd and reOPENed), in local time.

The logs begin when each program is started. They are updated every time there are 1000 lines in the screen display, or when the program is ended by clicking OK, Close, or Exit. The file is not created on disk until the initial update (i e, after lines 1-1000 have been generated). This delay allows users to control the log file directories and filenames from the script.

Each time the screen display reaches 1000 lines, all those lines will be appended to the log file, and the top line of the screen display will read [previous log written to file]. In the log file itself, the lines [previous log written to file] will be replaced with [Local time year-month-day hh:mm:ss], where the date and time are the time at which the lines were appended (in other words, approximately the time at which the screen log overflowed).

Each program other than Analyze and Communicate has a button Copy log. This causes the current screen display to be copied to the Windows clipboard. No change is made in the screen display, and no log file is written. The main purpose of this button is to allow you to get a copy of the log while the program is running, since when the program is stopped, the complete log is available in the log files described above.

To change the defaults, the script command LOG_DIRECTORY is used. The command has two required and two optional arguments:

LOG_DIRECTORY origin, directory [,id [,order]]

The required arguments origin and directory give the process name (and qualifier for Master) and directory for that process’s log files (currently, only Master has multiple log files). The optional arguments id and order give an identifier and sequence of the filename parts. If there are three or more arguments, the third is always id. If id and/or order are omitted, the previous settings are used.

If the specified directory does not exist, it will be created. All directories on the specified path that do not exist are added. Thus, if disk D: has no data or directories on it,

LOG_DIRECTORY Master, "D:\\MyLogs\\2009\\Oct"
will create new directories MyLogs on D:\, 2009 in D:\MyLogs, and Oct in D:\MyLogs\2009.

The directory name argument of LOG_DIRECTORY cannot be longer than 99 characters, and must be a valid Windows directory. The complete path to the log file, made up of the directory argument combined with the log file name, will be passed to Windows, so it must be a valid path.

Although origin can refer to any of the four processes, LOG_DIRECTORY has no effect on the directory that Analyze’s quick-look output is stored in. That file is always stored in the same directory as the active image at the time the file is opened. The id and order may be used to control the filename, however.

Examples, assuming Master.exe is in directory C:\A3O\Programs:

Directory for log files | String value of directory argument (see note about \\ below)
C:\MyLogs\2009\Oct | "C:\MyLogs\2009\Oct"
C:\A3O\Programs\MyLogs\Caj | ".\MyLogs\Caj"

The directory argument can be constructed in the script using string operators, for instance

yearUTC=DateToInteger($CurrentTime)/10000
directoryArg="C:\\MyLogs\\" + ConvertToString("%d\\Caj",yearUTC)
// Result of above is directoryArg="C:\MyLogs\2009\Caj"

Observe that when you write string literals (strings within quotes) in your script, you have to write "\\" when you want “\” in the string, because “\” is used to begin escape sequences. Examples of escape sequences are \\ to mean \, and \" to mean ".

Each process’s log files is controlled independently, so you may want to have four separate commands at the start of your script. Here is how you would get all the log files (except Analyze’s) to be stored in C:\Caj\Logs, with filenames like CAJ_20091002160812_MasterResults.txt:

logDir="C:\\Caj\\Logs" // the variable logDir now has value "C:\Caj\Logs"
logID="CAJ_"
logOrder=321

LOG_DIRECTORY Master, logDir, logID, logOrder
LOG_DIRECTORY Camera, logDir, logID, logOrder
LOG_DIRECTORY Observatory, logDir, logID, logOrder
LOG_DIRECTORY Analyze, logDir, logID, logOrder // doesn't change directory,
                                               // does set filename format
LOG_DIRECTORY Communicate, logDir, logID, logOrder

The first LOG_DIRECTORY statement could also have been written LOG_DIRECTORY Master,"C:\\Caj\\Logs","CAJ_",321

To change the directories during a run, use the LOG_OUTPUT origin, CLOSE, change the directories as desired, then LOG_OUTPUT origin, OPEN.

Here are examples of the six possible orders which use all three parts. if the identifier is "ID":

Order* | File name example
1 | 1 2 3 | Observatory_20091001114730ID.txt
2 | 1 3 2 | Observatory_ID20091001114730.txt
3 | 2 1 3 | 20091001114730_Observatory_ID.txt
4 | 2 3 1 | 20091001114730ID_Observatory.txt
5 | 3 1 2 | ID_Observatory_20091001114730.txt
6 | 3 2 1 | ID20091001114730_Observatory.txt

And here are examples of the six possible orders which use only two of the three parts:

Order* | File name example
1 | 1 2 | Observatory_20091001114730.txt
2 | 2 1 | 20091001114730_Observatory.txt
3 | 1 3 | Observatory_ID.txt
4 | 3 1 | ID_Observatory.txt
5 | 2 3 | 20091001114730ID.txt
6 | 3 2 | ID20091001114730.txt

For orders which use just one part:

Order | File name example
1 | 1 | Observatory.txt
2 | 2 | 20091001114730.txt
3 | 3 | ID.txt

* spaces are shown for clarity; in the script, these will be 123, 132, 213, etc.

Suppose you want files to be named like PKR_Observatory_20091001114730.txt. Then you make id="PKR" and the order 312. For PKR_20091001114730_Observatory.txt, the order would be 321 and id="PKR_" . In both cases the underscore character ("_") which separates the program name (creator) from the rest of the filename is added by Master, but the one between id and timestamp is part of id in the second example.

If you want the Camera log file appear in the directory C:\MyDirectory, and to be named MyFilenameGoesHere.txt (no timestamp or creator), use the script line LOG_DIRECTORY Camera "C:\\MyDirectory", "MyFilenameGoesHere", 3.


Script command LOG_DISPLAY

LOG_DISPLAY log string-valued-expression

Each time Master is started, it creates two logs: Master results and Master errors. These are text files (see LOG_DIRECTORY for the filenames and directories). Examples of these logs are in Operation.

The most recent 1000 lines of each log are also displayed on the Master front panel.

Running a script stores entries into Master results, usually one line for each script line executed. If any there are any errors in the script, entries are made into Master errors.

In addition, a script can insert whatever text it wants into either of these logs, or into three user logs. The user logs will not be created unless the script executes a LOG_DISPLAY for the corresponding user log.

Choices for log in LOG_DISPLAY are

R | Master results
E | Master errors
1 | User log 1
2 | User log 2
3 | User log 3
LOG_DISPLAY appends a line consisting of string-valued-expression to the specified log display and the corresponding log file.

Examples:

// Put the line "Begin data collection" into Master results log
LOG_DISPLAY R "Begin data collection"

// Insert a line like "Data collection complete for 2012-4-3 with 1234 images" into user log 1
// Assumes collection date is in time-valued collDate, and # images in nImages

collDate=$CurrentTime // get some values for the test
nImages=1234

d=DateToInteger(collDate) // yyyymmdd
yr=d/10000
mon=(d-yr*10000)/100
day=d-((yr*100+mon)*100)
dateString=ConvertToString("%d",yr) +ConvertToString("-%d",mon) +ConvertToString("-%d",day) // year-month-day
LOG_DISPLAY 1 "Data collection complete for "+dateString+ConvertToString(" with %d images",nImages)


Script command LOG_OUTPUT

LOG_OUTPUT origin, action

The origin is either one of the process names Master, Camera, Observatory, Analyze, or Communicate; or a specified Master log: MasterResults, MasterErrors, or MasterUser n.

The process Master produces two log files, MasterResults and MasterErrors, and, optionally, MasterUser n (n=1, ..., 3). LOG_OUTPUT Master opens or closes all of them at once, but they can also be controlled separately. See Output to log files for an example.

Neither origin nor action is case-sensitive: LOG_OUTPUT MASTER, OPEN and LOG_OUTPUT Master, open, among others, are equivalent.

The action is one of

  • OPEN, to start a new log file or append to an existing log file;
  • OVERWRITE, to start a new log file or overwrite an existing log file; or
  • CLOSE, which closes the current log file.
Since a log file is started when each program is started, LOG_OUTPUT is usually used in CLOSE, OPEN or CLOSE, OVERWRITE pairs.

The purpose of this command is to allow you to break a lengthy log file into segments. Since you can’t access a file while one of the programs has it open, it is also useful for being able to examine, e g, daily log files.

The naming and directory where the log files appear is controlled by LOG_DIRECTORY. Part of a log file name is the date and time when each segment of the log file was opened (these are local, not UTC). For example,

WAIT_UNTIL startDataTaking
// ... take data
// Done with the night's datataking at 0700 local time

LOG_OUTPUT Master, close  // done with the log for the night's data-taking
LOG_OUTPUT Master, open   // start a new log segment for the next night
LOG_OUTPUT Camera, close
LOG_OUTPUT Camera, open
LOG_OUTPUT Observatory, close
LOG_OUTPUT Observatory, open
LOG_OUTPUT Analyze, close
LOG_OUTPUT Analyze, open
LOG_OUTPUT Communicate, close
LOG_OUTPUT Communicate, open

Assuming the default log file naming (see LOG_DIRECTORY for how to change that), this might produce the Observatory daily log files

Observatory_20120527180145.txt (when Observatory was started)
Observatory_20120528070000.txt (from the close after the first night of data-taking)
Observatory_20120529070000.txt (from the close after the second night)
Observatory_20120530070000.txt
Observatory_20120531070000.txt
Observatory_20120601070000.txt


Script command MOVE_PH

MOVE_PH azimuth, zenith

When this command is executed, Master sends a message to Observatory to start motion of the pointing head to the indicated angles. The pointing head is the observation port of the FPI, and the direction of the is the direction of observation.

After sending the message, Master waits for Observatory to send a completion response, which occurs when either the pointing head has achieved the requested angle, or a time limit has been reached. Until this response has been received, the script suspends execution.

The expressions for azimuth and zenith are evaluated as reals, and units are degrees. See Coordinate systems for details.

The time limit is determined by the Observatory control file variables PRate_PHAz, PRateMax_PHAz, PRate_PHZe, PRateMax_PHZe, maxIterations_PHAz and maxIterations_PHZe for the Biondi-type pointing head, and by maxWait_SkyScan for a Skyscanner pointing head.

Examples:

// Look at the moon
LunarPosition($CurrentTime, &az, &ze) // position of the moon from the JPL planetary ephemeris
MOVE_PH az, ze

// Take an initial laser calibration
// For laser images, the angles are PHLasAz and PHLasZe, and the exposure time is xTimeLaser

xTime = xTimeLaser
SET_PARAMETER CAMERA FPI, ShutterMode = AUTO

MOVE_PH 0., PHLasZe         //  First, move only zenith (az = 0, the initial value on power-up)
MOVE_PH PHLasAz, PHLasZe    //  Second, move only azimuth (ze = laser ze)

SHUTTER OPEN                //  Open the LASER shutter (not camera shutter)
SET_PARAMETER CAMERA FPI, ExposureTime = xTime
dataType = "L"
ImageSequenceL = ImageSequenceL + 1
seq = ImageSequenceL
TAKE_IMAGE FPI,dataType
CALL "AcquireStoreDisplayImageFPI"
SHUTTER CLOSE               //  Close the LASER shutter (not camera shutter)


Script command OVERLAY

OVERLAY string-valued-expression

OVERLAY changes the script execution to a different file, the called script, named by string-valued-expression. The called script will not return to the caller. A RETURN in the called script will go to the caller of the caller.

A similar command, CALL, allows transfer of execution to another script, returning on completion.

The purpose of OVERLAY is to

  • Escape from the initial PgmDefault.txt script.
  • Add the ability to replace an entire script while it is running.
  • Break a long script into more manageable parts.
The last two can also be accomplished with CALL.

Examples:

PgmDefault.txt
// The script started when Master begins
OVERLAY "MyDataCollectionScript"
// Any script lines following will never be executed

MyDataCollectionScript.txt
// Loops on a whole day of data collection
SETUP CAMERA FPI
SETUP COOLER FPI
// ... collect data ...
SHUTDOWN COOLER FPI
SHUTDOWN CAMERA FPI
OVERLAY "MyDataCollectionScript"
When the OVERLAY is executed, a fresh copy of MyDataCollectionScript.txt is loaded. If the script has been changed, those changes will have effect in the next daily cycle. It is much more difficult to change “top-level” scripts using CALL, because changing the lines in a calling script means RETURN from a caller will fail.


Script command PULSE

PULSE channel, direction, duration

PULSE causes a message to be sent to Observatory, instructing it to send a pulse to the digital output line channel. The pulse can be either positive-going (direction = POS) or negative-going (direction = NEG).

The pulse length duration is in msec. The exact pulse length depends on Windows’ timing, which varies with the load on the system. You should not assume better than 20% + 10 msec accuracy on an unloaded system.

See LEVEL for a discussion of valid digital output channel numbers.

Example:

// Change the level of digital output to TTL hi for 5 seconds
PULSE 4, POS, 5*1000
A related command LEVEL could have been used for the same purpose.


Script command RELAY

RELAY name, state

RELAY allows a script to change the state of relays controlled by Observatory.

Each relay is identified by the parameters relay board serial number and relay number (the order of the relay on the specific board, counting from 0). The correspondence between the names of individual relays and their identification parameters is determined by the Observatory control file, which contains entries such as

RelayName MirrorL 77 2
meaning the third relay on the board whose serial is 77 is referred to as MirrorL in scripts (i e, the name parameter in RELAY). Relay names are case-sensitive, so BigGuy, bigguy and Bigguy are all different relays.

The parameter state is an integer-valued expression which gives the desired state for the relay: 0 for relay open (disconnected), or 1 for closed (connected, or energized).

Master queries Observatory for the list of relay names. Although Master makes the request when it starts, a few script lines may be executed before the response is received from Observatory. Thus, do not use the RELAY in the first few lines of the inital script.

RELAY initiates the relay operation, but does not wait for the operation to complete. It is up to the script to ensure that an appropriate length of time elapses between RELAY and using the resulting configuration.

A similar caution applies to successive commands to the same relay; how successive commands are handled depends on the relay board vendor’s library. It may queue commands, executing them in order, or execute just the last one for a given relay, or it may get confused.

Examples:

// Power L, disconnect R
RELAY MirrorL, 1
RELAY MirrorR, 0
// Switch states of two relays, with only one relay allowed on at once
// relayState initially contains the current state of relay Click (0 or 1)
RELAY Click, 0
RELAY Clack, 0            // now both relays are off
DELAY 2                   // wait for the relay that was on to go off
RELAY Click, 1-relayState
RELAY Clack, relayState   // now each relay is in the opposite state
relayState = 1-relayState // update the current state of Click


Script command RETURN

RETURN

This changes execution from the current script to the script that invoked the current script (the caller), at the line following the CALL. Each CALL should be paired with a RETURN.

If transfer of execution without possibility of returning is wanted, use OVERLAY.

Example:

Script Calling script | Script I am called
x=0 | x=x+1
CALL "I am called" | RETURN
x=x+2 // result will be 3 | x=9 // this line will not be executed


Script command SAVE_IMAGE

SAVE_IMAGE filename

Store an image which was previously acquired and copied.

The parameter filename may be either a complete or relative path. A relative path is relative to the current working directory. The working directory may change when Master uses the function ControlFileRead. It is safest to always use a complete path, as in the example following.

Example:

// Storing an image that was previously acquired and copied
seq = seq + 1
serialNumber = ConvertToString("%03d",seq) // serialNumber will be a 3-digit string
imageDir = "E:\\TestImages\\" // double \\ because this is an escape sequence;
                              // the directory will be E:\TestImages\
dataType="T"
imageName= imageDir + dataType + date + serialNumber + ".img" // 'date' is a previously-defined string
SAVE_IMAGE imageName    // e g, E:\TestImages\T20120313012.img
DISPLAY_IMAGE imageName // tells Analyze to display this image


SELECT_FILTER

Script command SELECT_FILTER

SELECT_FILTER unitname, filterName

This command causes Observatory to move a filter into the optical path, either for the FPI (unitname=FPI) or for the sky monitor camera (unitname=SkyMon) .

The FPI can be equipped with either a 2-position filter (the older model), a 3-position slide filter (newer), or an n-position color wheel, such as the the Finger Lake Instrument model FL-CFW-6-6 (6 filter slots) .

FPI filter model | Filter names
2-position | 630 or 732
3-position slide | 557, 630 or 0 The digit zero, meaning no filter ("OPEN").
n-position color wheel | 0, 1, ..., n−1. Any integer expression evaluating to one of these may be used as the filter name.

The Santa Barbara Instrument Group (SBIG) sky monitor camera has a 4-position filter (the “color wheel”) built in.

Sky monitor filter | Filter names
SBIG model ST-402ME | red, green, blue or clear

When Master encounters a SELECT_FILTER FPI command in the script, it sends a message to Observatory, which then commands the filter holder or wheel to move, either by sending the appropriate signals on the digital outputs (2- or 3-position and SBIG), or by issuing a command to the filter control library (color wheel). It then monitors the digital inputs or queries the library to know when the filter is in position. The digital outputs and inputs to be used are determined by parameters in the Observatory control file.

For SELECT_FILTER the command does not complete (i e, the script is paused) until the new filter is in place. For the Finger Lake Instrument model FL-CFW-6-6 , this can take as long as 17 seconds.

Example:

// Capture FPI images using two different filters (slots 3 and 2),
// assuming a 6-position color wheel is installed.
SELECT_FILTER FPI, 3
TAKE_IMAGE FPI, "D" // using the user-defined convention A=filter 0, B=filter 1, ...
COPY_IMAGE FPI
SAVE_IMAGE "My image-filter_3"
SELECT_FILTER FPI, 2
TAKE_IMAGE FPI, imagetype,"C"
COPY_IMAGE FPI
SAVE_IMAGE "My image-filter_2"

If the command is SELECT_FILTER SkyMon a message goes to Camera, which then moves the color wheel on the sky monitor camera.

Example:

// Take sky images in red and green
SELECT_FILTER SkyMon, red
TAKE_IMAGE SkyMon, "R"
COPY_IMAGE SkyMon
SAVE_IMAGE "My image-red"
SELECT_FILTER SkyMon, green
TAKE_IMAGE SkyMon, "G"
COPY_IMAGE SkyMon
SAVE_IMAGE "My image-green"


Script command SELECT_SCENE

SELECT_SCENE view

In some older models, the scene select mirror directs light into the FPI. The mirror has two positions: calibration (view = LASER) and data-taking (view = SKY). The script command SELECT_SCENE causes Master to send a message to Observatory to set the position of the mirror.

After SELECT_SCENE, the script does not proceed until either the scene mirror is in the requested position, or a time limit has been exceeded. The Observatory control file variables MaxWait_ScLaser and MaxWait_ScSky set the time limits.

Example:

// Do 3 laser calibrations

for (i=0; i<3; i=i+1)
{
    SELECT_FILTER 630 //select laser filter, same as 630 filter
    DELAY 5

    // Move scene select mirror to laser position
    SELECT_SCENE LASER

    MOVE_PH 3, 2
    SET_PARAMETER CAMERA,EXPOSURE=xTimeLaser

    imageSequenceL = imageSequenceL + 1
    CALL "TakeCopyImage"
    dataType = "L" + ConvertToString("%03d",imageSequenceL)
    CALL "ImageFileName"
    SAVE_IMAGE ImageName
}
// End of laser calilbrations

// Open shutter and select 732 filter for evening twilight,
// as opposed to 630 choice

for (i=0; i<3; i=i+1)
 {
    SHUTTER OPEN	//open shutter so to see sky outside
    SELECT_SCENE SKY
    SELECT_FILTER 732
    DELAY 5 // give filter changer time to move filter

    // Move mirrors to orient toward Sun in evening twilight
    // PH_zen is the zenith angle of 60 degrees and will remain constant

    MOVE_PH 2, 3
    SET_PARAMETER CAMERA,EXPOSURE=xTimeSun
    WaitTime = xTimeSun

    imageSequenceT = imageSequenceT + 1
    CALL "TakeCopyImage"

    dataType = "T" + ConvertToString("%03d",imageSequenceT)
    CALL "ImageFileName"
    SAVE_IMAGE, ImageName
}


Script command SET_PARAMETER (Camera)

SET_PARAMETER CAMERA unitname, paramSetName=value
SET_PARAMETER CAMERA unitname, AuxPort=n, binaryValue

SET_PARAMETER CAMERA causes Master to change a parameter which controls the operation of one of the system’s cameras. All but AuxPort and Temperature are values, stored in camera’s parameter table, which determine various aspects of image acquisition, and so do not have any effect until the next image is acquired.

For paramSetName AuxPort, Temperature, CoolerMode and FanMode, Master sends a message to Camera, telling Camera to perform the indicated operation.

There is an independent camera parameter table for each camera. In the script command SET_PARAMETER CAMERA, unitname is FPI or SkyMon, identifying which camera is affected.

Choices for paramSetName are:

Parameter name | Value type | Units | Parameter name | Value type | Units
AcqMode | string* |  | HorizonBin | integer |
ADChannel | integer |  | OutputAmpType | integer* |
AntiBloomGate | integer |  | PreAmpGain | real |
CoolerMode | integer* |  | ReadMode | string* |
EMAdvanced | integer* |  | ShiftSpeedH | real | μsec
EMCCDGain | integer |  | ShiftSpeedV | real | μsec
EMGainMode | integer* |  | ShutterCloseT | integer | msec
ExposureTime | real | sec | ShutterMode | string* |
FanMode | integer* |  | ShutterOpenT | integer | msec
FinalTemp | integer | ° C | ShutterType | string* |
FullImageCol0 | integer |  | Temperature | integer | ° C
FullImageCol1 | integer |  | TrigMode | string* |
FullImageRow0 | integer |  | VerticalBin | integer |
FullImageRow1 | integer |
* Special values
AcqMode | SINGLE, ACCUM or KIN
CoolerMode | 0=return to ambient on shutdown 1=maintain cooling on shutdown
FanMode | 0=full speed 1=low speed 2=off (not in Camera control file—only via script commands)
EMAdvanced | 1=enable access to higher EM gain levels
EMGainMode | 0=gain controlled by DAC 0-255 1=0-4095 2=linear 3=real EM gain
OutputAmpType | 0=EMCCD gain register 1=conventional CCD register
ReadMode | FVB, MULTI, RANDOM, TRACK or IMAGE
ShutterMode | AUTO, OPEN or CLOSE
ShutterType | LO or HI
TrigMode | INTERNAL or EXTERNAL

SET_PARAMETER CAMERA unitname, AuxPort=n, value tells Camera to set the named camera’s auxiliary port n (n = 1−4) to binaryValue (0 or 1).

Examples:

// Take a set of 4 images with different binning and exposure time
tExp = 4.5 // seconds
for (iBin = 1; iBin <= 4; iBin = iBin + 1)
{
    SET_PARAMETER CAMERA FPI, ExposureTime=tExp/(i*i)
    SET_PARAMETER CAMERA FPI, HorizonBin=iBin
    SET_PARAMETER CAMERA FPI, VerticalBin=iBin
    TAKE_IMAGE FPI, "b" // the image type is arbitrary
    COPY IMAGE FPI
    SAVE_IMAGE "Binned" + ConvertToString( "%d" , iBin ) + "x" + ConvertToString( "%d" , iBin ) + ".img" // image file will be, e g, Binned2x2.img
}

// Set up for full vertical binning (Andor camera)
SET_PARAMETER CAMERA FPI, ReadMode="FVB"


Script command SETUP (Analyze)

SETUP ANALYZE

Executing this command causes Master to send a message to Analyze. If Analyze is running, it will reset some variables to an initial state.

At present, SETUP ANALYZE causes Analyze to re-initialize the wind velocity plots and make the current laser and zenith images (if any) unavailable (these images are used for the temperature and wind velocity calculations).


Script command SETUP (Camera)

SETUP CAMERA unitname

This command causes Master to send a message to Camera, telling Camera to initialize the named camera. Master waits for Camera to complete the initialization before proceeding.

In this command, unitname must be either FPI or SkyMon.

The initialization performed by Camera depends on the type of camera. See Camera / Initialization and shutdown for more information.


SETUP (cooler)

Script command SETUP (cooler)

SETUP COOLER unitname

This command causes Master to send a message to Camera, telling Camera to initialize the cooling apparatus of the named camera. Master waits for Camera to complete the initialization before proceeding. “Completion” here means the cooler has been turned on, although it may not have reached the final temperature.

In this command, unitname must be either FPI or SkyMon.

The initialization performed by Camera depends on the type of camera. See Camera / Temperature control for more information.


Script command SETUP (FPI)

SETUP FPI unitname

This command tells Observatory to initialize the device unitname. At present, the only possible unitname is SkyScan.

SETUP FPI SkyScan causes Master to send a message to Observatory to start SkyScan’s homing routine. This routine causes SkyScan the position sensors to find the embedded magnets and slew mirror to home position, for both motors (azimuth and zenith).

The script continues execution after SETUP FPI SkyScan; it does not wait for the homing to finish, and there is no direct way for a script to determine whether the homing operation has completed.


Script command SHUTDOWN (Camera)

SHUTDOWN CAMERA unitname

This command causes Master to send a message to Camera, telling Camera to shut down the named camera. Master waits for Camera to complete the shutdown before proceeding.

In this command, unitname must be either FPI or SkyMon.

The shutdown steps performed by Camera depends on the type of camera. See Camera / Initialization and shutdown for more information.


Script command SHUTDOWN (cooler)

SHUTDOWN COOLER unitname

This command causes Master to send a message to Camera, telling Camera to shut down the cooling apparatus of the named camera. Master waits for Camera to complete the shutdown before proceeding. “Completion” here means the cooler has been turned off, although it may not have reached ambient temperature (if the cooler mode allows this).

In this command, unitname must be either FPI or SkyMon.

The shutdown steps performed by Camera depend on the type of camera and the cooler mode. See Camera / Temperature control for more information.


Script command SHUTDOWN (laser)

SHUTDOWN LASER unitname

This command is not yet implemented.


Script command SHUTDOWN (PHdome)

SHUTDOWN PHdome unitname

This command is not yet implemented.


Script command SHUTDOWN (other)

SHUTDOWN OTHER unitname

This command is not yet implemented.


Script command SHUTTER

SHUTTER [name, ] state

If name is omitted, the command controls a shutter which is connected to the digital output specified by Observatory control file variables DOut_FPIShutter, PPol_FPIShutter, PWidth_FPIShutter, Level_FPIShutterOpen and Level_FPIShutterClose. This shutter type is controlled by a digital level.

When name is given, the command controls a USB shutter. The correspondence between shutter name and shutter serial number is given by the Observatory control file variables ShutterName.

Both of the forms of this command send a message to Observatory to move the shutter to the desired state, either OPEN or CLOSE.

Master queries Observatory for the list of shutter names. Although Master makes the request when it starts, a few script lines may be executed before the response is received from Observatory. Thus, do not use the named SHUTTER in the first few lines of the inital script.

SHUTTER initiates the shutter motion, but does not wait for the motion to complete. It is up to the script to ensure that an appropriate length of time elapses between SHUTTER and using the resulting configuration.

Examples:

// Shutter controlled by digital output
SHUTTER OPEN
TAKE_IMAGE
SHUTTER CLOSE

// USB shutter named NorthQd
SHUTTER NorthQd,OPEN
TAKE_IMAGE
SHUTTER NorthQd,CLOSE


Script command TAKE_IMAGE

TAKE_IMAGE unitname, imagetype

Start image acquisition for the camera specified by unitname: either FPI (e g, the Andor camera which captures the interferograms) or SkyMon (e g, the SBIG camera which monitors the sky image). The image is acquired using the values in Camera’s parameter table, such as exposure time.

The image type is used for classification of the image. It is a single character that is stored in the image header, and used by Analyze. The meaning of each image type is up to the user, and any convention may be used. The Analyze control file specifies how each type of image is processed.

The parameter imagetype is a string-valued expression. The string may be more than one character long, but only the initial character is used.

Example:

// Acquiring, copying, and storing an image
SET_PARAMETER CAMERA FPI, ShutterMode = AUTO // setting these is only necessary if they were not already set
SET_PARAMETER CAMERA FPI, ExposureTime = 3.5 // either by a previous SPC or from the Camera control file
TAKE_IMAGE FPI,"A" // the image type is arbitrary

// Wait for the acquisition to complete
DELAY 3.5 // it's expected to take at least this long
checkCount = 0

GET_STATUS CAMERA FPI, STATE, currentState
// Check once per second until either acquisition is complete, or we've waited for exposure time + 5 sec
while(currentState!=20073 && checkCount< 5) // for the Andor camera, 20073 is "DRV_IDLE"
{
    DELAY 1
    GET_STATUS CAMERA FPI, STATE, currentState
    checkCount = checkCount+1
}

// Transfer the image from the FPI camera to computer memory
COPY_IMAGE FPI

// Store the image
imageName= imageDir + dataType + date + serialNumber + ".img" //  imageDir, dataType, date and serialNumber are all previously-defined strings
SAVE_IMAGE imageName
DISPLAY_IMAGE imageName // tells Analyze to display the image


Script command WAIT_UNTIL

WAIT_UNTIL time-valued-expression

When a script encounters this command, execution of the script is suspended until time-valued-expression is reached. This suspension only affects Master itself; other processes continue to run, and any messages they send to Master will be queued until the script resumes. See also DELAY.

WAIT_UNTIL $CurrentTime + 30 // this is equivalent to DELAY 30

// Variable beginDatataking contains the time at which we want to start taking images.
// Allow 5 minutes for the system to stabilize.
WAIT_UNTIL beginDatataking - (5*60)
// ... code to start up system (takes about 1 minute)
WAIT_UNTIL beginDatataking

WAIT_UNTIL 00:00:00 // waits until next midnight UTC
When a script is run in checkout mode, the wait will be a maximum of 30 seconds.


Master Known Bugs

TO DO


Changes in Master v1.06 2014-11-24

  1. This version of Master must be used with updated versions of the other processes: Observatory v1.62, Camera v1.27, Analyze v2.03 and Communicate v0.07, or later.

  2. An integer expression is now acceptable for the color wheel filter selection in SELECT_FILTER FPI. Previously, only an integer constant was acceptable, although the documentation specified an integer expression.


Changes in Master v1.05 2014-11-22

  1. This version of Master must be used with updated versions of the other processes: Observatory v1.62, Camera v1.27, Analyze v2.03 and Communicate v0.07, or later.

  2. The previous v1.04 did not run correctly under 32-bit Windows XP. This version should run under Windows XP, Windows 7, or Windows 8.


Changes in Master v1.04 2014-11-18

  1. This version of Master must be used with updated versions of the other processes: Observatory v1.62, Camera v1.27, Analyze v2.03 and Communicate v0.07, or later.

  2. The script command SELECT_FILTER unitname, filterName has been modified to support the n-position color wheel. The filters are named 0, ..., n−1.

  3. Master v1.03 may not have run on a Windows XP. This version should run under Windows XP, Windows 7, or Windows 8.


Changes in Master v1.03 2014-9-17

  1. This version of Master must be used with updated versions of the other processes: Observatory v1.55, Camera v1.27, Analyze v2.03 and Communicate v0.07, or later.

  2. A new script function GaussianFit(nPoints, x, y, paramsInit, fixed, goal, maxIterations, &usedIterations, &paramsFit, &resid, &calc, &area) has been added. Details.
  3. The Master window is now resizeable, by maximizing, or by dragging one of its edges.

  4. There have been some small changes in the display of variables via tooltips.

  5. This is the first version of Master built with Visual Studio 2013 and Intel Fortran XE 2015. There should be no difference in functionality.


Changes in Master v1.02 2014-3-7

  1. This version of Master must be used with updated versions of the other processes: Observatory v1.55, Camera v1.27, Analyze v2.03 and Communicate v0.07, or later.

  2. The script function ImageProperties(x0, y0, xSize, ySize, xBin, yBin, nBuckets, buck0, buck1, &count, &min, &max, &avg) has changed to allow computation of a histogram, as well as the statistics, of an image displayed by Analyze. Details.


Changes in Master v1.01 2013-12-6

  1. This version of Master must be used with updated versions of the other processes: Observatory v1.55, Camera v1.27, Analyze v2.02 and Communicate v0.07, or later.
  2. Some changes were made to the inter-process message handling to prevent deadlock (one or more processes hang).


Changes in Master v1.00 2013-10-1

  1. Script command RELAY has been added. This command controls USB relays, such as the USB-Relay board made by Picard Industries.


Changes in Master v0.99 2013-9-24

  1. Script command EMAIL_SEND has been added. This command sends a user-defined email message. Communicate must be running on the local machine to send email.

  2. Script command EMAIL_SET_SERVER has been added. This command will be recognized in a script, but its functionality is not yet implemented. node.

  3. The button Show all defined variables gave an incorrect display for real and boolean arrays. This has been fixed.

  4. Master scripts now support arrays of strings. Each array element is limited to 99 characters in length.

  5. The tooltip for variables in a script did not work correctly for arrays. It will now show all elements of a 1-dimensional array.

  6. Using the button Restart (go to the initial line of the current script) did not always enable the Single-step and Run buttons. This has been corrected.

  7. Typing in the “script immediate” box (next to DoIt) disables the 60-second countdown to automatic script start.

  8. Typing Enter in the “script immediate” box executes the typed command, the same as if DoIt were clicked.


Changes in Master v0.98 2013-2-20

  1. Script command FILE_UNCOMPRESS has been added. FILE_UNCOMPRESS extracts files from a compressed archive.

  2. Script command FILE_MOVE has been added. FILE_MOVE transfers groups of files from one directory to another on the local A3O node.

  3. Script command FILE_COPY has been added. FILE_COPY copies groups of files from one directory to another on the local A3O node.

  4. Script command FILE_DELETE has been added. FILE_DELETE removes groups of files from a directory on the local A3O node.

  5. The function FileXferStatus allows a script to determine the completion status (done or error) for each of the above commands. All of these commands require Communicate be running on the local machine.


Changes in Master v0.97 2013-1-18

  1. Script commands FILE_COMPRESS and FILE_UNCOMPRESS have been added. FILE_UNCOMPRESS is not yet implemented in Communicate, although Master will recognize it as a valid command.


Changes in Master v0.96 2012-11-8

  1. The conversion of literal time constants (e g, 2012-11-8.12:34:56) from a script or control file was incorrect when standard time was in effect; the 1-hour daylight bias was being added to the correct UTC values. This has been corrected.

  2. To accomodate the new A3O process Communicate, these additions have been made:

    1. Script commands FILE_FETCH and FILE_SEND have been added.

    2. Script function FileXferStatus(order) has been added.

    3. The script commands LOG_DIRECTORY and LOG_OUTPUT now accept Communicate as a process name.

  3. The system variable $Serial has been added for diagnostic purposes.

  4. “Identify” messages are sent to each process every 30 minutes. In future versions, this will allow a script to determine whether a process is still running, and so whether to continue to send requests to it.

  5. New or changed documentation in the help file now is indicated by a red asterisk: .


Changes in Master v0.95 2012-9-12

  1. This version of Master must be used with updated versions of the other processes: Camera v1.19, Observatory v1.44 and Analyze v1.88, or later.

  2. The time Master was started was not showing correctly in the MasterResults and MasterErrors logs. This has been fixed.

  3. Documentation for the script command LOG_OUTPUT has been updated.

  4. The special-purpose subroutine

    ControlFileRead(filename, variablename1, variablename2,...)

    can also be used in the form

    error = ControlFileRead(filename, variablename1, variablename2,...)

    See Script language for details.


Changes in Master v0.94 2012-9-5

  1. This version of Master must be used with updated versions of the other processes: Camera v1.19, Observatory v1.44 and Analyze v1.88, or later.

  2. The script commands LOG_DIRECTORY and LOG_OUTPUT have been enhanced to allow control of the individual Master log files (i e, MasterResults, MasterErrors, MasterUsern).

  3. The script command LOG_OUTPUT now allows opening a log file as either append or overwrite.

  4. The special-purpose subroutine ControlFileRead now accepts control file variables of types boolean and string. Strings are limited to 99 characters, and longer strings will be truncated, and a warning will appear in the MasterErrors log.

  5. The examples for ControlFileRead were incorrect. They have been fixed.

  6. Attempting to see the value of long string variables using tooltips caused a crash. This has been corrected.

  7. The system variable $DayNumber was off by 1 day for dates February in a leap year. This has been fixed.

  8. User log files are not created if a script hasn’t done any output (using LOG_DISPLAY). Previously, the user log file would be created with the single line * END OF LOG *.

  9. In user log files, the header, end-of-log line, and timestamp for each line have been removed. Only those characters that were output by the script (via LOG_DISPLAY) will appear in the user logs.

  10. Some minor formatting changes have been made in the log file headers.

  11. Details and examples for using log files have been added here.


Changes in Master v0.93 2012-8-24

  1. This version of Master must be used with updated versions of the other processes: Camera v1.18, Observatory v1.43 and Analyze v1.87, or later.

  2. A new function FileStatus has been added, to allow a script to determine existence and last modified date of a file.

  3. The script command LOG_DIRECTORY has been enhanced to allow an ID of up to 99 characters, and to select which of the three components of the filename will appear.

    A slight change in the filename format inserts an underscore between ID and process name. If you were using the order 312 or 231, you may need to change your script.

  4. The example for LOG_OUTPUT was incorrect. It has been fixed.


Changes in Master v0.92 2012-5-19

  1. The interlock between the script interpreter and front panel in Master has been renamed, to avoid possible interference with other processes.


Changes in Master v0.91 2012-4-18

  1. The unary operator boolean not (!) did not always give the correct result. For example, in the script code
    a = 2>3 // result=false (correct)
b = !a  // result=false (ERROR, should be true)
    the value of a was not properly negated. This has been fixed. Relational operators not equal (!=) were not affected by this error.

  2. The select function, described in the “Script language” document, has not yet been implemented. It has been removed from the on-line help file, and will be restored when the function is working.

  3. A new button on the Master front panel, Copy script, copies the script to the clipboard, with line numbers. It’s useful for understanding a log file.

  4. A feature on the Master front panel allows typing in single script lines for immediate execution. This is useful for quick testing of language syntax without having to edit a file and restart Master for each change.

  5. The built-in function ConvertToReal has been added. This was in the documentation, but had not been implemented.

  6. The script command SHUTTER has been expanded to allow up to four named USB shutters. See Observatory changes in v1.40.


Changes in Master v0.90 2012-1-19

  1. Master has been rebuilt to fix what appeared to be an incompatibility with Analyze v1.84. In fact there was no incompatibility, just a warning message.

  2. Script lines may now have comments at the end. Previously, comments had to appear on a separate line. Comments begin with “//”, and may be separated by blanks or tabs.


Overview of Camera

Camera controls the cameras used by an FPI station. Those normally include a camera which captures the output of the interferometer, such as the Andor DV434, and may also include a sky monitor camera, such as the Santa Barbara Instrument Group SBIG ST-402 CCD Camera.

Camera will operate under control of Master, or stand-alone. When Master is running (the usual mode of operation for datataking), it will send messages to Camera , such as “take an exposure”. Camera in turn will communicate with Observatory and Master.

Camera maintains a table of parameters which govern the operation of the camera. There is a separate table for each camera. Any parameter can be changed by Master, using the script command SET_PARAMETER. The initial values for the parameters are read from the Camera control file. Some examples of these parameters are exposure time, binning, and image size. Which parameters are applicable, and what they do, depend on the type of camera.

Obtaining an image is a three-step process:

  • Expose the detector to the image source (i e, open the camera’s shutter).
  • Transfer the image data from the camera’s memory to the computer’s memory.
  • Copy the image data to a disk file.

When controlled by Master , these operations are triggered by the script commands TAKE_IMAGE, COPY_IMAGE, and SAVE_IMAGE, respectively.


Camera's control file

Camera’s control file

The control file is a text file, which you can edit with any text editor. Like the other control files used by A3O, each line has the general format symbol_name value.

The following table shows the possible parameters. Most are required; those that are optional have default values. To understand how they affect the camera's operation, you will need to consult the camera manufacturer’s manual (e g, User’s Guide to Andor SDK).

Under Type, A=Andor, S=SBIG (Santa Barbara Instrument Group), P=Princeton Instruments.

symbol_name | Data type | Required? | Type | Meaning | Default value
General
FPIMake | MFRMFR is one of Andor, Princeton (e g, PIXIS), SBIG (Santa Barbara Instrument Group), none (no camera in use). | yes |  | The manufacturer of the camera used for FPI imaging. |
SkyMonMake | MFR | yes |  | The manufacturer of the camera used for sky monitoring. |
TestImageDirectory | string | no |  | The full path to the directory where images stored using the front panel will appear. | Directory of Camera.exe
ReadMode | RMRM is one of rm_FVB (Full Vertical Binning), rm_MT (Multi-Track), rm_RT (Random-Track), rm_ST (Single-Track) or rm_Image. Cropped is not supported. | yes | A | Describes how the pixels of an image are binned. |
AcqMode | AMAM is one of am_SS (Single Scan), am_ACC (Accumulate) or am_KS (Fast Kinetics). Kinetic Series and Run Till Abort are not supported.. | yes | A | Controls the number and timing details of image acquisition. |
TrigMode | TMTM is either tm_INT (Internally triggered) or tm_EXT (Externally triggered). External Start, External Exposure, External FVB EM and Software are not supported. | yes | A | Determines when image data capture starts relative to acquisition start. |
ShiftSpeedH | real | yes | A | The speed at which the charge in the shift register is shifted horizontally. It is also the speed at which the signal is digitized via the on-board A/D converters. |
ShiftSpeedV | real | yes | A | The speed at which each row on the CCD is shifted vertically into the shift register. |
PreAmpGain | real | yes | A | Each horizontal shift speed has an associated number of valid pre-amp gains. |
ShutterMode | SMSM is one of sm_AUTO (The camera controls the shutter), sm_OPEN (Shutter remains open), sm_CLOSE (Shutter remains closed). | yes | A, S | How the shutter is to be operated. |
ShutterType | STST is either st_TLL_LO (TTL low for open) or st_TLL_HI (TTL high for open). | yes | A | The polarity of a pulse generated by the camera to control an external shutter. |
ShutterOpenT | integer | yes | A | Time required for shutter to open. |
ShutterCloseT | integer | yes | A | Time required for shutter to close. |
FinalTemp | integer | yes | A, P | Desired temperature for the CCD. |
AccumCycleT | integer | yes | A | Period in seconds between the start of individual scans accumulated in computer memory to create each member of a kinetic series. |
DDGGateStep | integer | yes | A | Not in use |
Image
ExposureTime | integer | yes | A, S, P | Time in seconds the shutter is open for image acquisition. |
HorizonBin | integer | yes | A, P | Number of pixels combined horizontally, within the CCD. |
VerticalBin | integer | yes | A, P | Number of pixels combined vertically, within the CCD. |
FullImageCol0 | integer | yes | A, P | Starting pixel column for an image. |
FullImageCol1 | integer | yes | A, P | Ending pixel column for an image. |
FullImageRow0 | integer | yes | A, P | Starting pixel row for an image. |
FullImageRow1 | integer | yes | A, P | Ending pixel row for an image. |
Kinetic
FKHeight | integer | yes | A | Sub-area height in rows. |
FKNumber | integer | yes | A | Number of images in a series. |
FKExposureT | real | yes | A | Exposure time in seconds. |
FKBinMode | integer | yes | A | Binning mode: 0 for FVB, 4 for Image. |
KineticCycleT | integer | yes | A | Period in seconds between the start of each scan in a kinetic series. |
FKVShiftSpeed | integer | yes | A | Index of the fast kinetics vertical shift speed. |
KineticScanNum | integer | yes | A | Number of scans in a kinetic series. |
Tracking
MultiTrackNum | integer | yes | A | Number of tracks. |
MultiTrackHeight | integer | yes | A | Height of each track, in pixels. |
MultiTrackOffset | integer | yes | A | Vertical displacement of tracks. |
MultiTrackBottom | integer | yes | A | First pixel row of the first track. |
MultiTrackGap | integer | yes | A | Number of rows between each track (may be 0). |
RandomTrackNum | integer | yes | A | The number of random tracks. |
SingleTrackCenter | integer | yes | A | The center pixel row of a single track. |
SingleTrackHeight | integer | yes | A | The height of a single track in pixels. |
Miscellaneous
AntiBloomGate | 0 – 3 | no | S | 0 = Low during integration (ABG shut off); 1 = Clocked at low rate; 2 = Clocked at medium rate; 3 = Clocked at high rate. |
AccumScanNum | integer | yes | A | Number of scans to be acquired and accumulated for the acquisition mode am_ACC. the PC |
ADChannel | integer | yes | A | Choose one of the possible A-Ds of the system. |
OutputAmpType | 0 or 1 | yes | A | 0=EMCCD gain register 1=conventional CCD register |
EMAdvanced | 0 or 1 | yes | A | Allow access to higher EM gain levels. |
EMGainMode | 0 – 3 | yes | A | Choice of EM Gain mode. |
EMCCDGain | integer | yes | A | The EM gain. |
CoolerMode | 0 or 1 | yes | A | 1 to maintain temperature after shutdown; 0 to allow return to ambient. |
USBPort | integer | yes | S, P | The USB port to which the SBIG or Princeton camera is attached. |


Camera's parameter table

Camera’s parameter table

A camera parameter table is maintained for each camera, and when a camera operation is performed, any required parameters are taken from the table for that camera. Many of the parameters are not used in normal operation. For the function of each parameter, consult the Andor or SBIG user manual.

Each camera parameter table is initialized from the camera control file. Camera parameter table entries may be changed by SET_PARAMETER CAMERA, or read by GET_PARAMETER CAMERA.

Note: Although the Camera control file uses symbols for some parameter settings (e g, am_SS for acquisition mode = single scan), GET_PARAMETER CAMERA and SET_PARAMETER CAMERA use numeric values (e g, 1 for acquisition mode = single scan).

Parameter name | Type | Values
AcqMode | AcqMode | 1=Single Scan, 2=Accumulate, 3=Fast Kinetics
ADChannel | integer |
AntiBloomGate | integer |
CoolerMode | integer |
EMAdvanced | integer |
EMCCDGain | integer |
EMGainMode | integer |
ExposureTime | real |
FanMode | integer |
FinalTemp | integer |
FullImageCol0 | integer |
FullImageCol1 | integer |
FullImageRow0 | integer |
FullImageRow1 | integer |
HorizonBin | integer |
OutputAmpType | integer |
PreAmpGain | real |
ReadMode | ReadMode | 0=Full Vertical Binning, 1=Multi-task, 2=Random-task, 3=Single-track, 4=Image
ShiftSpeedH | real |
ShiftSpeedV | real |
ShutterCloseT | integer |
ShutterMode | ShutterMode | 0=Auto, 1=Open, 2=Close
ShutterOpenT | integer |
ShutterType | ShutterType | 0=Output TTL low signal to open shutter, 1=Output TTL high signal to open shutter
TrigMode | TrigMode | 0=Internal, 1=External
VerticalBin | integer |

There are some camera parameters, listed below, that are not accessible by GET_PARAMETER CAMERA and SET_PARAMETER CAMERA. These can only be set via the control file, and can’t be changed by a script.

AccumCycleT | FKVShiftSpeed | MultiTrackNum
AccumScanNum | KineticCycleT | MultiTrackOffset
FKBinMode | KineticScanNum | RandomTrackNum
FKExposureT | MultiTrackBottom | SingleTrackCenter
FKHeight | MultiTrackGap | SingleTrackHeight
FKNumber | MultiTrackHeight | USBPort


Initialization and shutdown

n Initialization occurs when
  • Camera is started.
  • The operator chooses Initialize camera from the Operation dropdown on Camera’s front panel and clicks Execute.
  • Camera receives a message from Master to initialize. These are generated by SETUP CAMERA unitname in a script.
For the Andor camera, the initialization sequence is
  1. Execute Andor driver function Initialize to initialize the camera hardware.

  2. Get detector size and hardware and software versions from the camera.

  3. Get the number of amplifiers and their characteristics from the camera.

  4. Determine the number of Andor cameras connected.

  5. Get information on, and capabilities of, each camera. Capabilities include horizontal and vertical shift speeds, number of A/D channels, and pre-amp gains associated with each horizontal shift speed.

  6. Place the results of the above into the Observatory log.

For the Santa Barbara Instrument Group (SBIG) camera, the initialization sequence is

  1. Execute SBIG driver function SBIGUnivDrvCommand to initialize the driver.

  2. Open the device on the USB port specified by variable USBPort in Camera’s control file. The connection can be USB or Ethernet.

  3. Get the SBIG universal driver and USB driver version numbers.

  4. Execute SBIG driver function SBIGUnivDrvCommand(CC_OPEN_DRIVER... to initialize the driver.

  5. Establish a link to the device connected to the specified port. Get the camera type, CCD info, readout modes, and camera capabilities.

  6. Place the results of the above into the Observatory log.

n Shutdown occurs when

  • The operator chooses Shut down camera from the Operation dropdown and clicks Execute.
  • Camera receives a message from Master to shut down. These are generated by SHUTDOWN CAMERA unitname in a script.
For the Andor camera, shutdown executes Andor driver function ShutDown.

For the Santa Barbara Instrument Group (SBIG) camera, the shutdown sequence is

  1. Execute SBIG driver function SBIGUnivDrvCommand(CC_CLOSE_DEVICE... to close the device.
  2. Execute SBIG driver function SBIGUnivDrvCommand(CC_CLOSE_DRIVER... to close the driver.
  3. Place the results of the above into the Observatory log.


Acquiring an image

To “acquire an image” means the camera’s shutter is opened, allowing light to fall on the CCD detector. After acquisition is complete, the image needs to be read out of the CCD array into computer memory, and then saved into a disk file.

The script commands for these operations are

  • TAKE_IMAGE starts image acquisition. more
  • COPY_IMAGE copies an acquired image from the camera’s CCD detector into computer memory. more
  • SAVE_IMAGE transfers an image from computer memory to a disk file. more
For acquisition, the camera is first set up according to its type.

Andor camera setup

  • Set the acquisition mode from AcqMode.
  • Set read out mode from ReadMode
  • Wait for 2 seconds to allow MCD to calibrate fully before allowing an acquisition to begin.
  • Set the exposure time from ExposureTime.
  • Get the actual acquisition timings to be used for exposure, accumulation and kinetics (the last two are not normally used).
  • Set up the shutter from ShutterType, ShutterMode, ShutterOpenT and ShutterCloseT.
  • Set the trigger mode from TrigMode.
  • Set the image parameters:
    1. Get the detector size in pixels.
    2. Set the binning from HorizonBin and VerticalBin.
    3. Set the image rows and columns to the full size of the detector.
  • Set the horizontal shift speed from ShiftSpeedH using the closest available value.
  • Set the A/D channel to be used.
  • Set the preamp gain, if the camera supports it.
  • Set the vertical shift speed from ShiftSpeedV using the closest available value.
  • Set the EM parameters if the camera supports them:
    1. OutputAmpType
    2. EMAdvanced
    3. EMGainMode
    4. EMCCDGain
    5. OutputAmpType

SBIG camera setup

  • Set the CCD to be used as the imaging CCD.
  • Set the exposure time from ExposureTime.
  • Set the antiblooming gate state during integration from AntiBloomGate.
  • Set the open shutter mode using ShutterMode.

When the camera has been set up, record the image acquisition starting time, and the temperature of the camera. Send a message to Observatory requesting the current conditions (pointing head direction, outdoor temperature and pressure, etc).

Finally, issue the command to the camera to begin image acquisition. Normally, when the acquisition has completed, you will want to copy the image.

For the SBIG camera, Camera checks every 40 msec and ends the exposure when the integration is complete.

For the Andor camera, to determine when the acquisition is complete, you can either wait some time longer than the actual exposure time, or use GET_STATUS CAMERA.


Copying an image

To “copy an image” means an image that was previously acquired (see Acquiring an image ) is read out of the CCD array into computer memory. Usually, after copying is complete, the image will be saved into a disk file.

The script commands for these operations are

  • TAKE_IMAGE starts image acquisition. more
  • COPY_IMAGE copies an acquired image from the camera’s CCD detector into computer memory. more
  • SAVE_IMAGE transfers an image from computer memory to a disk file. more

When acquisition was started, a message was sent to Observatory requesting the current conditions. When copying an image, Camera looks for the response to that message, and copies the values into the image header. Those values include

  • Version of Observatory.
  • State of the digital inputs.
  • Doppler shift FSR.
  • Azimuth and zenith angles.
  • Current ambient temperature and pressure.
  • Station latitude, longitude and height.
  • Station number.
  • Auxiliary inputs (up to 12).

The number of pixels to be copied depends on the dimensions and binning:

nPixels = (FullImageCol1 - FullImageCol0 + 1) * (FullImageRow1 - FullImageRow0 + 1) / (HorizonBin * VerticalBin)
All the values on the right side are camera parameters, from the Camera control file, or SET_PARAMETER CAMERA in the script.

The time this image was copied is recorded in the header (as local time, not UTC).

The entire buffer is filled with an initial pattern (pixel number*3 mod 216 with hex 12345678 in the initial 8 bytes and 9ABCDEF0 in the final 8 bytes), and then the image data is transferred from the camera to the buffer. The initial pattern will be completely overwritten if the transfer proceeds without error.

Normally, after copying, you will want to save the image as a disk file.


Saving an image

To “save an image” means an image that was previously acquired (see Acquiring an image) and copied from the camera into computer memory (see Copying an image) is stored in a file on the disk. The file contains the image itself, along with data about the image (the image header).

The script commands for these operations are

  • TAKE_IMAGE starts image acquisition. more
  • COPY_IMAGE copies an acquired image from the camera’s CCD detector into computer memory. more
  • SAVE_IMAGE transfers an image from computer memory to a disk file. more

In the script, SAVE_IMAGE specifies the image path to be used. The path includes both the directory and the filename (for example, E:\A3OImages2012\20120305\X20120305007.img). There are no restrictions on the directory or filename, but it is useful to adopt some standard naming convention.


Image file format

  • Image header
  • Image pixels

The image header is exactly 1,024 bytes long. When written to a file, this structure is followed by enough 0 bytes for a total length of 1,024.

Each section of the header has its own version number. If the file format changes, the corresponding section version number must also change. Programs that process image files will use the version numbers to know how to parse the header sections.

This is the C++ structure for version 2 of the header:

struct ImageFileHeader
{
    char fileIdentifier[4]; // character constant "A3OI" designates an A3O image file
    int vn;                 // the format of this file
    int pgmVersion;         // the version of Camera that produced this file
    int hdrSize;            // length of this header in units of 'char'
    short avOffset,avSize;  // offset in the file and section length for each section
    short diOffset,diSize;
    short cpOffset,cpSize;
    short cnOffset,cnSize;
    short iiOffset,iiSize;
    AndorVersion av;
    DetectorInfo di;
    CameraParameters cp;    // values of the camera parameters at the time
                            //  this image was acquired
    Conditions cn;          // conditions as reported by Observatory
    ImageInfo ii;
};

The AndorVersion section stores information about the Andor camera's hardware and driver, obtained from the Andor driver. This is version 1.

struct AndorVersion
{
    int vn; // version of this structure
    // Results from GetHardwareVersion
    unsigned int PCBVer, FlexVer, Dummy1Ver, Dummy2Ver, Dummy3Ver, Dummy4Ver;
    // Results from GetSoftwareVersion
    unsigned int EpromVer, CofFileVer, VxdRev, VxdVer, DllRev, DllVer;
};

The DetectorInfo section stores information about the camera's detector. This is version 1.

struct DetectorInfo
{
    int vn;               // version of this structure
    int XPixels, YPixels; // results from GetDetector
};

The CameraParameters section all the camera settings at the time the image was acquired. This is version 4.

struct CameraParameters
{
    int vn;                    // version of this structure
    ReadModeType ReadMode;
    AcqModeType AcqMode;
    TrigModeType TrigMode;
//v<2    int ShiftSpeedH;     // Speed in microseconds per horizontal pixel shift
//v<2    int ShiftSpeedV;     // Speed in microseconds per vertical pixel shift
    float ShiftSpeedH;        // Speed in microseconds per horizontal pixel shift
    float ShiftSpeedV;        // Speed in microseconds per vertical pixel shift
    ShutterModeType ShutterMode;
    ShutterTypeType ShutterType;
    int ShutterOpenT;         // Time shutter takes to open, in milliseconds
    int ShutterCloseT;        // Time shutter takes to close, in milliseconds
    int FinalTemp;            // Desired temperature of the detector in Centigrade
    int AccumCycleT;          // The accumulation cycle time in seconds
    int DDGGateStep;          // Gate step in picoseconds
    float ExposureTimeRq;     // the length of time the CCD collects light prior to
                              //  readout, in seconds (requested by user)
    float ExposureTimeActual; // time actually used by camera
    int FKHeight;             // Sub-area height in rows
    int FKNumber;             // Number is series
    float FKExposureT;        // Exposure time in seconds
    int FKBinMode;            // Binning mode (0-vertical binning ON,
                              //  4-vertical binning OFF)
    float KineticCycleT;      // The kinetic cycle time in seconds
    int FKVShiftSpeed;        // Speed in micro-seconds per pixel shift
    int HorizonBin;           // Number of pixels to bin horizontally
    int VerticalBin;          // Number of pixels to bin vertically
    int FullImageCol0;        // Start column (inclusive)
    int FullImageCol1;        // End column (inclusive)
    int FullImageRow0;        // Start row (inclusive)
    int FullImageRow1;        // End row (inclusive)
    union
    {
        int MultiTrackNum;    // Number tracks, valid values 1 to number of vertical pixels
        int AntiBloomGate;    // for SBIG
    };
    int MultiTrackHeight;     // Height of each track, valid values > 0 (maximum
                              //  depends on number of tracks)
    int MultiTrackOffset;     // Vertical displacement of tracks, valid values depend
                              //  on number of tracks and track height
    int MultiTrackBottom;     // First pixels row of the first track
    int MultiTrackGap;        // Number of rows between each track
    int AccumScanNum;         // Number of scans to accumulate
    int KineticScanNum;       // Number of scans to store
    int RandomTrackNum;       // Number tracks, valid values 1 to number of vertical pixel/2
    int SingleTrackCenter;    // Centre row of track, valid range 0 to
                              //  number of vertical pixels
    int SingleTrackHeight;    // Height of track, valid range > 1
    // New in Camera v1.11
    float PreAmpGain;         // In some cameras, the preamp gain is settable
    // New in Camera v1.12
    char ADChannel;
    char OutputAmpType;       // 0=EMCCD gain register  1=conventional CCD register
    char EMAdvanced;          // 1=enable access to higher EM gain levels
    char EMGainMode;          // 0=gain controlled by DAC 0-255  1=0-4095
                              //  2=linear  3=real EM gain
    char CoolerMode;          // 0=return to ambient on shutdown  1=maintain cooling on shutdown
                              // NOTE: CoolerMode isn't an image parameter, but it's here
                              //  so SET PARAMETER CAMERA can be used
    char FanMode;             // 0=full speed  1=low speed  2=off (not in control file--only via script commands)
    char unused[2];           // set to 0
    int EMCCDGain;            //

};

The Conditions section records the readings from Observatory at the time the image was acquired. This is version 6.

struct Conditions
{
    int vn;                     // version of this structure (diff between v3 and v4
                                //  is the PH in digitalInputs)
    int ObsVn;                  // version of Observatory that sent this info
    unsigned int digitalInputs; // 1 bit per input, in standard order; ms 2 bits are
                                //  PH type (00=Biondi, 01=Skyscan, 10=sky monitor camera)
    double azAngle,zeAngle;     // in degrees
// Added in v3
    double temp, press;         // outdoor temp in deg C, barometric pressure in bars
    double aux[12];             // unassigned analog input channels
                                //  (only 1st 4 in use at present)
// Added in v5
    double dopplerShiftFSR;     // m/s of velocity due to free spectral range
                                //  (peak spacing)
// Added in v6
    double stationLatitude,stationLongitude,stationHeight;
    int stationNumber;          // for user to identify the station
};

The ImageInfo section has information about the image. This is version 3.

struct ImageInfo
{
    int vn;                        // version of this structure
    SYSTEMTIME imageAcqStartTime;  // when the current image acquisition started
    SYSTEMTIME imageCopyStartTime; // when the current image copy started
    int imageTemperature;          // detector temperature at time image acquisition started
    unsigned int imageTemperatureStatus;
                                   // error return from GetTemperature for above (Andor),
                                   //  or SetTempInt:power:regulatorEnabled for SBIG
    unsigned int size;             // total size of the image in bytes (calculatable from cp also)
    CameraID id;                   // type of camera that took this image (only present if vn>1)
    char imageType;                // characterization of this image (only present if vn>2);
                                   //  a user-chosen tag, which Analyze may use.
                                   //  Typical image types are D=Dark, L=Calibration (laser),
                                   //  Z=Zenith, N=Nightglow, but actual types
                                   //  are from a table in the Analyze control file.

};


Temperature control

The detector temperature is maintained by a cooling unit built into each camera. The parameters CoolerMode (Andor camera only) and FinalTemp in camera’s parameter table are used.

These temperature control parameters have initial values from Camera’s control file, and may be changed using script command SET_PARAMETER CAMERA.

n The temperature control parameters are only applied when

  • The operator chooses Cooler on from the Operation dropdown on Camera’s front panel and clicks Execute.
  • Camera receives a message from Master to initialize the cooler. These are generated by script command SETUP COOLER.
For the Andor camera, the cooler-on sequence is
  1. Execute Andor driver function SetCoolerMode using CoolerMode (0=temperature is maintained on shutdown, 1=returns to ambient temperature on shutdown) to specify whether the cooler is switched off when the camera is shut down.
  2. Execute Andor driver function GetTemperatureRange, and use the resulting range to validate FinalTemp.
  3. Execute Andor driver function CoolerON.
  4. Execute Andor driver function SetTemperature, using FinalTemp. A script will continue execution after this, although the final temperature may not be achieved for several minutes.
  5. Start a timer to check the cooler temperature every 30 seconds. The successive temperatures will be displayed in the Camera log.
  6. Results from each step will be included in the Camera log.

For the Santa Barbara Instrument Group (SBIG) camera, the cooler-on sequence is

  1. Execute SBIG driver function SBIGUnivDrvCommand(CC_SET_TEMPERATURE_REGULATION) to turn on temperature regulation, using FinalTemp. A script will continue execution after this, although the final temperature may not be achieved for several minutes.
  2. Start a timer to check the cooler temperature every 30 seconds. The successive temperatures will be displayed in the Camera log.
  3. Results from each step will be included in the Camera log.

n The cooling apparatus associated with a camera is turned off when

  • The operator chooses Cooler off from the Operation dropdown on Camera’s front panel and clicks Execute.
  • Camera receives a message from Master to shut down the cooler. These are generated by script command SHUTDOWN COOLER.
For the Andor camera, the cooler-off sequence is
  1. Execute Andor driver function CoolerOFF. The rate of temperature change is controlled in some models until the temperature reaches 0º.

    Note: The camera parameter CoolerMode (0=temperature is maintained on shutdown, 1=returns to ambient temperature on shutdown) to deter whether the cooler is switched off when the camera is shut down (e g, by by script command SHUTDOWN CAMERA).

    A script will continue execution after this, although the temperature may be increasing for several minutes.

  2. Start a timer to check the cooler temperature every 30 seconds. The successive temperatures will be displayed in the Camera log.
  3. Results from each step will be included in the Camera log.

For the Santa Barbara Instrument Group (SBIG) camera, the cooler-off sequence is

  1. Execute SBIG driver function SBIGUnivDrvCommand(CC_SET_TEMPERATURE_REGULATION) to turn off temperature regulation. A script will continue execution after this, although the temperature may be increasing for several minutes.
  2. Start a timer to check the cooler temperature every 30 seconds. The successive temperatures will be displayed in the Camera log.
  3. Results from each step will be included in the Camera log.


Status functions

Camera monitors the status of each of the cameras. A script can obtain this status in a script using GET_STATUS CAMERA.

A camera’s status includes the state of the camera itself, the temperature of its detector, and, if available, the state of the digital input ports on the camera’s control board (Andor has this feature).

The meaning of the status depends on the camera model. The present version of Camera (v1.17 2012-4-18) supports various models of Andor cameras, and the Santa Barbara Instrument Group (SBIG) sky monitor camera.

Related commands are GET_PARAMETER CAMERA, which retrieves a camera’s control parameters, and SET_PARAMETER CAMERA, which allows you to change them.

Here is a table of the camera status values for the Andor cameras:

Andor symbol | Description | Value
DRV_ERROR_CODES | Error occurred | 20001
DRV_SUCCESS | All parameters accepted, or operation completed successfully. | 20002
DRV_VXDNOTINSTALLED | Device Driver not installed. | 20003
DRV_ERROR_SCAN |  | 20004
DRV_ERROR_CHECK_SUM |  | 20005
DRV_ERROR_FILELOAD | Unable to load "*.COF" or "*.RBF" files. | 20006
DRV_UNKNOWN_FUNC | Unknown function, incorrect cof file. | 20007
DRV_ERROR_VXD_INIT |  | 20008
DRV_ERROR_ADDRESS |  | 20009
DRV_ERROR_PAGELOCK | Unable to acquire lock on requested memory. | 20010
DRV_ERROR_PAGEUNLOCK |  | 20011
DRV_ERROR_BOARDTEST |  | 20012
DRV_ERROR_ACK | Unable to communicate with card | 20013
DRV_ERROR_UP_FIFO |  | 20014
DRV_ERROR_PATTERN |  | 20015
DRV_ACQUISITION_ERRORS |  | 20017
DRV_ACQ_BUFFER | Computer unable to read the data via the ISA slot | 20018
DRV_ACQ_DOWNFIFO_FULL |  | 20019
DRV_PROC_UNKONWN_INSTRUCTION |  | 20020
DRV_ILLEGAL_OP_CODE |  | 20021
DRV_KINETIC_TIME_NOT_MET | Unable to meet Kinetic cycle time. | 20022
DRV_ACCUM_TIME_NOT_MET | Unable to meet Accumulate cycle time. | 20023
DRV_NO_NEW_DATA | No acquisition has taken place | 20024
DRV_PCI_DMA_FAIL |  | 20025
DRV_SPOOLERROR | Overflow of the spool buffer. | 20026
DRV_SPOOLSETUPERROR |  | 20027
DRV_FILESIZELIMITERROR |  | 20028
DRV_ERROR_FILESAVE | Failed to save data to file. | 20029
DRV_TEMP_CODES |  | 20033
DRV_TEMPERATURE_CODES |  | 20033
DRV_TEMP_OFF | Temperature is OFF. | 20034
DRV_TEMPERATURE_OFF |  | 20034
DRV_TEMP_NOT_STABILIZED | Temperature reached but not stabilized | 20035
DRV_TEMPERATURE_NOT_STABILIZED |  | 20035
DRV_TEMP_STABILIZED | Temperature has stabilized at set point. | 20036
DRV_TEMPERATURE_STABILIZED |  | 20036
DRV_TEMP_NOT_REACHED | Temperature has not reached set point. | 20037
DRV_TEMPERATURE_NOT_REACHED |  | 20037
DRV_TEMP_OUT_RANGE |  | 20038
DRV_TEMPERATURE_OUT_RANGE |  | 20038
DRV_TEMP_NOT_SUPPORTED |  | 20039
DRV_TEMPERATURE_NOT_SUPPORTED |  | 20039
DRV_TEMP_DRIFT | Temperature had stabilised but has since drifted | 20040
DRV_TEMPERATURE_DRIFT |  | 20040
DRV_GENERAL_ERRORS |  | 20049
DRV_INVALID_AUX |  | 20050
DRV_COF_NOTLOADED |  | 20051
DRV_FPGAPROG |  | 20052
DRV_FLEXERROR | Unable to load "*.RBF". | 20053
DRV_GPIBERROR | Error communicating with GPIB card. | 20054
DRV_EEPROMVERSIONERROR |  | 20055
DRV_DATATYPE |  | 20064
DRV_DRIVER_ERRORS |  | 20065
DRV_P1INVALID | Invalid parameter. | 20066
DRV_P2INVALID | Invalid parameter. | 20067
DRV_P3INVALID | Invalid parameter. | 20068
DRV_P4INVALID | Invalid parameter. | 20069
DRV_INIERROR | Unable to load "DETECTOR.INI". | 20070
DRV_COFERROR | Unable to load "*.COF". | 20071
DRV_ACQUIRING | Acquisition in progress. | 20072
DRV_IDLE IDLE | Waiting for instructions. | 20073
DRV_TEMPCYCLE | Executing temperature cycle. | 20074
DRV_NOT_INITIALIZED | System not initialized. | 20075
DRV_P5INVALID | Invalid parameter. | 20076
DRV_P6INVALID |  | 20077
DRV_INVALID_MODE | Acquisition, readout or trigger mode, or fast kinetics, is not available. | 20078
DRV_INVALID_FILTER | Filter not available for current acquisition. | 20079
DRV_I2CERRORS |  | 20080
DRV_I2CDEVNOTFOUND | Could not find the specified device. | 20081
DRV_I2CTIMEOUT | I2C command timed out. | 20082
DRV_P7INVALID | Invalid parameter. | 20083
DRV_P8INVALID | Invalid parameter. | 20084
DRV_P9INVALID | Invalid parameter. | 20085
DRV_P10INVALID | Invalid parameter. | 20086
DRV_P11INVALID | Invalid parameter. | 20087
DRV_USBERROR | Unable to detect USB device or not USB2.0. | 20089
DRV_IOCERROR | Integrate On Chip setup error. | 20090
DRV_VRMVERSIONERROR |  | 20091
DRV_USB_INTERRUPT_ENDPOINT_ERROR |  | 20093
DRV_RANDOM_TRACK_ERROR | Invalid combination of tracks, out of memory, etc | 20094
DRV_INVALID_TRIGGER_MODE |  | 20095
DRV_LOAD_FIRMWARE_ERROR |  | 20096
DRV_DIVIDE_BY_ZERO_ERROR | The sum of the green field within the ROI is zero. | 20097
DRV_INVALID_RINGEXPOSURES |  | 20098
DRV_BINNING_ERROR | Range not multiple of horizontal binning. | 20099
DRV_INVALID_AMPLIFIER | Not a valid amplifier | 20100
DRV_INVALID_COUNTCONVERT | Count Convert mode not available. | 20101
DRV_ERROR_MAP |  | 20115
DRV_ERROR_UNMAP |  | 20116
DRV_ERROR_MDL |  | 20117
DRV_ERROR_UNMDL |  | 20118
DRV_ERROR_BUFFSIZE | Output buffer size too small. | 20119
DRV_ERROR_NOHANDLE |  | 20121
DRV_GATING_NOT_AVAILABLE |  | 20130
DRV_FPGA_VOLTAGE_ERROR |  | 20131
DRV_OW_CMD_FAIL |  | 20150
DRV_OWMEMORY_BAD_ADDR |  | 20151
DRV_OWCMD_NOT_AVAILABLE |  | 20152
DRV_OW_NO_SLAVES |  | 20153
DRV_OW_NOT_INITIALIZED |  | 20154
DRV_OW_ERROR_SLAVE_NUM |  | 20155
DRV_MSTIMINGS_ERROR | Invalid timing request | 20156
DRV_OA_NULL_ERROR | Invalid pointer. | 20173
DRV_OA_PARSE_DTD_ERROR |  | 20174
DRV_OA_DTD_VALIDATE_ERROR |  | 20175
DRV_OA_FILE_ACCESS_ERROR | Failed to determine status of file. | 20176
DRV_OA_FILE_DOES_NOT_EXIST |  | 20177
DRV_OA_XML_INVALID_OR_NOT_FOUND_ERROR |  | 20178
DRV_OA_PRESET_FILE_NOT_LOADED |  | 20179
DRV_OA_USER_FILE_NOT_LOADED | Supplied User file failed to load. | 20180
DRV_OA_PRESET_AND_USER_FILE_N | Failed to load Andor and User file. | 20181
DRV_OA_INVALID_FILE | Data cannot be written to the Preset Andor | 20182
DRV_OA_FILE_HAS_BEEN_MODIFIED | File to be written to has been modified | 20183
DRV_OA_BUFFER_FULL/ |  | 20184
DRV_OA_INVALID_STRING_LENGTH | One or more of the string parameters has an invalid length | 20185
DRV_OA_INVALID_CHARS_IN_NAME | Mode name and/or description contain | 20186
DRV_OA_INVALID_NAMING | Mode and description have the same name, | 20187
DRV_OA_GET_CAMERA_ERROR | Unable to retrieve information about the | 20188
DRV_OA_MODE_ALREADY_EXISTS | Mode name already exists in the file. | 20189
DRV_OA_STRINGS_NOT_EQUAL |  | 20190
DRV_OA_NO_USER_DATA | No data for selected mode. | 20191
DRV_OA_VALUE_NOT_SUPPORTED |  | 20192
DRV_OA_MODE_DOES_NOT_EXIST | Mode name does not exist. | 20193
DRV_OA_CAMERA_NOT_SUPPORTED | Camera not supported. | 20194
DRV_OA_FAILED_TO_GET_MODE |  | 20195
DRV_PROCESSING_FAILED |  | 20211
DRV_ERROR_NOCAMERA | No camera found | 20990
DRV_NOT_SUPPORTED | Camera does not support | 20991
DRV_NOT_AVAILABLE | Your system does not support this feature | 20992


Camera change logs

TO DO


Auxiliary ports

Auxiliary ports are only available on Andor cameras. There are four TTL Auxiliary Input Ports and four TTL Auxiliary Output Ports on the Andor plug-in card. The value at each input or output will be either 0 (off, or low) or any non-zero value (on, or high).

To set an output port to a specified value from a script, use SET_PARAMETER CAMERA unitname, AuxPort=n, binaryValue

To read the value of an input port within a script, use GET_STATUS CAMERA unitname, AuxPort=n, variable.

The ports can also be controlled from the Camera front panel, using the operations Get auxiliary port and Set auxiliary port.


Camera Known Bugs

TO DO


Changes in Camera v1.30 2014-1-9

  1. This version of Camera must be used with updated versions of the other processes: Master v1.01, Observatory v1.55, Analyze v2.01 and Communicate v0.07, or later.

  2. Camera incorrectly used the test image directory from the control file for all images, not just for those created from the front panel. This has been corrected, so images stored by Master’s SAVE_IMAGE do not use the test image directory. This is the same behavior as existed in v1.23 and earlier.


Changes in Camera v1.29 2013-12-18

  1. This version of Camera must be used with updated versions of the other processes: Master v1.01, Observatory v1.56, Analyze v2.01 and Communicate v0.07, or later.

  2. Camera was still sending an incorrectly-formatted list of available cameras to Master. This has been corrected..


Changes in Camera v1.28 2013-12-17

  1. This version of Camera must be used with updated versions of the other processes: Master v1.01, Observatory v1.55, Analyze v2.01 and Communicate v0.07, or later.

  2. Camera was sending an incorrectly-formatted list of available cameras to Master. This version attempted to correct that, but did not.


Changes in Camera v1.27 2013-12-16

Changes in Camera v1.25 2013-12-16

  1. This version of Observatory must be used with updated versions of the other processes: Master v1.01, Camera v1.27, Analyze v2.02 and Communicate v0.07, or later.

  2. Required for compatibility with Master v1.01


Changes in Camera v1.26 2013-12-9

  1. This version of Camera must be used with updated versions of the other processes: Master v1.00, Observatory v1.53, Analyze v2.01 and Communicate v0.07, or later.

  2. For the Princeton camera, the shutter mode is now set explicitly, and also logged. This change should not have any effect for the Pixis models.


Changes in Camera v1.25 2013-12-5

  1. This version of Camera must be used with updated versions of the other processes: Master v1.01, Observatory v1.53, Analyze v2.01 and Communicate v0.07, or later.

  2. The test image directory specified by the Camera control file was displayed correctly on the front panel, but was ignored when storing test images. This has been corrected.


Changes in Camera v1.24 2013-10-1

  1. This version of Camera must be used with updated versions of the other processes: Master v1.00, Observatory v1.48, Analyze v2.01 and Communicate v0.06, or later.

  2. Support for the Princeton Pixis series of cameras has been added.

  3. The exposure time, binning, and image filename can now be specified from the front panel for images generated and stored using the front panel. The directory for these images is an optional parameter in the camera control file, using a new entry TestImageDirectory. If this parameter does not appear in the control file, the directory of Camera.exe is used, as previously.


Changes in Camera v1.23 2013-10-1

  1. This version of Camera must be used with updated versions of the other processes: Master v1.00, Observatory v1.48, Analyze v2.00 and Communicate v0.06, or later.

  2. Control file lines which contain only blanks and tabs are now ignored. Previously, such lines caused spurious errors.


Changes in Camera v1.22 2013-9-24

  1. This version of Camera must be used with updated versions of the other processes: Master v0.99, Observatory v1.47, Analyze v1.99 and Communicate v0.05, or later.

  2. There are no changes in functionality from v1.21.


Changes in Camera v1.21 2013-2-20

  1. This version of Camera must be used with updated versions of the other processes: Master v0.98, Observatory v1.46, Analyze v1.91 and Communicate v0.03, or later.

  2. There are no changes in functionality from v1.20.


Changes in Camera v1.20 2012-11-8

  1. This version of Camera must be used with updated versions of the other processes: Master v0.96, Observatory v1.45, Analyze v1.90 and Communicate v0.01, or later.

  2. There are no changes in functionality from v1.19.


Changes in Camera v1.19 2012-9-5

  1. This version of Camera must be used with updated versions of the other processes: Master v0.94, Observatory v1.44 and Analyze v1.88, or later.

  2. The Camera log file can now be named more flexibly. See LOG_DIRECTORY for details.


Changes in Camera v1.18 2012-8-24

  1. This version of Camera must be used with updated versions of the other processes: Master v0.93, Observatory v1.43 and Analyze v1.87, or later.

  2. The Camera log file can now be named more flexibly. See LOG_DIRECTORY for details.

  3. The Camera main window can be changed in size by dragging on the edges. At present, it cannot be made much smaller than its initial size.


Changes in Camera v1.17 2012-4-18

  1. The camera parameter FKExposureT has been changed from integer to real. Since this parameter is not currently being used, there should be no effect on existing scripts.


Changes in Camera v1.16 2012-1-19

  1. Camera has been rebuilt to be compatible with Master v0.90.


Overview of Observatory

Observatory controls the filter, scene selector, FPI shutter , optical extender and pointing head. In addition, Observatory handles all the digital and analog I/O.

Observatory can be used in conjuction with Master and Camera (the normal usage for data-taking), or by itself (“stand-alone”, useful for testing). In either case, Observatory has a display, shown below, referred to as the front panel.

The various sections of the front panel are discussed in Manual positioning, Pulse and digital I/O, Counter/timer, Shutters, Analog input, Pointing head position, and Log.

When Observatory is used with Master and Camera, it exchanges messages with them. Master’s script generates commands, and Camera gets the conditions for each image.

Parameters that control Observatory’s operation appear in a control file. See Observatory’s control file.


Coordinate systems

The JWM coordinate system represents points on the unit sphere by a pair of angles, azimuth and zenith. These angles are constrained as

−180º ≤ azimuth ≤ +180º
−180º ≤ zenith ≤ +180º

This representation is not unique, because the points (az, ze) and (az ± 180, −ze) are equivalent. Also, the angles −180 and +180 are equivalent, for both axes.

So while a pair of angles in the JWM coordinate system determines a unique point, the point may have several different representations. For example, these points are all equivalent (those in red are not valid in the JWM coordinate system, because |zenith| > 180):

(az, ze) = (−180, −160) ≡ (0, 160) ≡ (180, −160) ≡ (0, −200) ≡ (180, 200) ≡ (−180, 200)
In converting from the point to the coordinates, a canonical representation is chosen:
−180º ≤ azimuth ≤ +180º
0º ≤ zenith < +180º

In the example above, the bold value meets this criterion.

SkyScan coordinates are values for the azimuth and zenith angles which the hardware is capable of achieving. The range of motion depends on the SkyScan model. For the older model SkyScan azimuth range is 180º, and zenith range is 360º. For the SkyScan4, both axes have a range of 360º. The coordinate origin is (0, 0) (straight up), and the home position is (0, 180). The home position is where the hardware parks on power-up or -down. The hardware can move ±90º from home position for azimuth and +0 to −360º for zenith .

To convert JWM coordinates to SkyScan coordinates, we must change the ranges of azimuth and zenith:

0º ≤ azimuth ≤ +180º
−180º ≤ zenith ≤ +180º

The reduction of the azimuth range is accomplished by using the relation (az, ze) ≡ (az ± 180, −ze). The reduction of the zenith range is accomplished by using the relation (az, ze) ≡ (az, ze ± 360). For example, if the PH is told to move to (az, ze) = (−125, −260), using the azimuth reduction gives the equivalent point (55, +260), and then the zenith reduction gives (55, −100).

The following is applicable only to the newer SkyScan4:
To convert SkyScan coordinates to JWM canonical coordinates, if SkyScan reports az>180, (az, ze) ≡ (az−180, −ze). Otherwise, the reported values are already JWM canonical.

The following is applicable only to older SkyScan models:
The peculiar range for the zenith comes from the modification of the hardware.

The position of the PH is controlled by a pair of integers (counts), one for each axis. The limits are

0 ≤ azimuth ≤ 12,000 counts
0 ≤ zenith ≤ 24,000 counts

Home position is (6000, 0) counts.

To convert SkyScan coordinates to counts,

az_counts = 6000 + az · (6000/90)
ze_counts = 6000 − ze · (6000/90)

To convert counts to SkyScan coordinates, the above are inverted:

az = (az_counts − 6000) / (6000/90)
ze = (ze_counts − 6000) / −(6000/90)

No changes are needed to convert SkyScan coordinates to JWM canonical coordinates, because the SkyScan coordinate ranges are a subset of the JWM coordinate ranges for both azimuth and zenith.


Manual positioning

These controls on the front panel are used to move a SkyScan pointing head manually.

These invoke the corresponding subroutines in the SmartMotor’s firmware. You could use these to verify the SkyScan is operational.

Do not use them when you are testing SkyScan’s ability to move to a position.

To make SkyScan move, enter the angles here (in degrees) and click Move pointing head. You should see the angles and elapsed time updated in the position display windows, shown at right.

These adjust the pointing head angles by small increments. The values for Coarse, Medium and Fine come from the Observatory control file (symbols azCoarse, etc). Typical values are 1, 0.3 and 0.1 degrees. respectively. The top arrow increases and the bottom one decreases the angle for the azimuth axis (top row) and zenith (bottom).

These use the JPL planetary ephemeris (PLEPH) to get the position of the listed reference body at the time it is selected.

For example, at right Sun has been selected, at 15:31 PDT on 2012-5-21. From the station, az=290.3° and ze=93.2°.

Clicking [image] will make a copy of the displayed angles to the reference body in the Desired position boxes.

The Observatory control file contains the station location:

stationLatitude    37.958 // geodetic latitude in degrees: north positive
stationLongitude  -73.    // geodetic longitude in degrees; east positive
stationHeight    1090     // height of the observer in meters


Pulse and digital I/O

The FPI stations generally have a separate board or USB module for analog and digital I/O. Analog inputs are used to read sensors, such as temperature, and digital outputs control various attached apparatuses, such as a filter mechanism. Digital inputs are usually used for feedback from attached apparatuses. Counter/timer outputs produce pulse trains or count events.

Different I/O modules have different functionality. For instance, the Data Translation DT-300 board (PCI bus), which has 4 counter/timers, 16 single-ended or pseudo-differential analog input channels, or 8 differential analog input channels, and no analog output channels. The Data Translation DT-9812 module (USB) has 1 counter/timer, 8 single-ended analog input channels, and 2 analog output channels. For detailed information, see the user manuals for these products and note below.

Observatory provides access to analog and digital I/O in several ways:

  • Script command PULSE
  • Script command LEVEL
  • Script command MOVE_PH, if PH is Biondi
  • Script command EXTENDER
  • Script command GET_STATUS DIGITAL_INPUT or ANALOG_INPUT
  • Script command SELECT_FILTER FPI
  • Script command SELECT_SCENE
  • Script command SHUTTER
  • Manually from the Observatory front panel.

For flexibility, the digital and analog parameters are specified in the Observatory control file.

Parameter type | Description
Analog I/O
Channel | Which of the analog input or output wires is connected.
Type | How an analog input is connected: single-ended, differential, or pseudo-differential.
Range | The limits of the voltage that an analog input can handle, or an output can produce.
Conversion | Coefficients for linear conversion from analog value to voltage or other user units.
Pulse | Parameters relating to pulse generation using analog outputs: polarity, width
Counter/timer
Unit | Which of the counter/timer channels is used.
Rate | The rate at which the pulses are generated, their polarity and duty cycle.
External clock | Frequency of an external clock, if any.
Conversion | Coefficients for linear conversion of position error voltage to pulse train length.
Digital I/O
Channel | Which of the digital input or output wires is connected.
Expected value | For a digital input, 0 or 1 signal from an attached apparatus.

Digital I/O fron the front panel

The Observatory front panel can be used to set digital output levels, send pulses, and read the digital inputs. These functions are normally only used for testing.

To set a level | To send a pulse | To set 3-position filter | To read digital inputs
Choose the bit (channel). Select the level. | Choose the bit (channel). Set the pulse width and polarity. Click Send pulse. | Set desired filter value (0−3) Click Filter. The two channels used are those specified by DOut_FiltChoice0 and DOut_FiltChoice1 in the Observatory control file. | Click Read digital inputs. Input values will appear in the 15 boxes below.

Note on digital line numbering: The Observatory control file specifies digital I/O lines. Prior to v1.30 of Observatory, input and output lines were numbered together (e g, 0–7 for input and 8–23 for output). This was done because the Data Translation DT-302 allows configuration of its three digital ports to either input or output. Observatory took the line (bit) assignments in the control file and figured out how to set up the digital ports.

Starting in v1.30 (released 2011-5-25), the lines are numbered separately for input and output, and Observatory does not do the automatic configuration. The Data Translation modules are configured as

Module | Inputs |  | Outputs
 | How many | Numbering | How many | Numbering
DT-9812 | 8 | 0–7 | 8 | 0–7
DT-302 | 15 | 0–14 | 8 | 0–7

Although the DT-302 has three ports (8, 8 and 7 lines) which can be configured as either input or output, Observatory always configures port A as output and B and C as input. The user must set up the control file with appropriate bit assignments, and this will be checked by Observatory.

This table shows possible error messages resulting from digital I/O bit assignment checking. Not all the digital I/O lines are checked..

Symbol in error | Error value | Comment
Counter/timer (used for Biondi PH)
CTPlus_PHAz | 10+err |
CTMinus_PHAz | 20+err |
CTPlus_PHZe | 30+err |
CTMinus_PHZe | 40+err |
3-position filter slide
DIn_Filt557 | 160+err |
DIn_Filt630 | 170+err |
DIn_Filt0 | 180+err |
DIn_FiltMount | 190+err |
DOut_FiltChoice0 | 270+err |
DOut_FiltChoice1 | 280+err |
2-position filter
DIn_Filt630 | 100+err |
DIn_Filt732 | 110+err |
DOut_Filt630 | 200+err |
DOut_Filt732 | 210+err |
Arequipa (if apparatusType=1)
DIn_OPXin | 120+err | Optical extender parameters
DIn_OPXout | 130+err |
DIn_ScLaser | 140+err | Scene motor parameters
DIn_ScSky | 150+err |
DOut_ScLaser | 250+err |
DOut_ScSky | 260+err |
Miscellaneous
DOut_OPX | 230+err |
DOut_PHHtr | 240+err | Pointing head heater
FPI shutter
DOut_FPIShutter | 220+err |


Counter/timer

The FPI stations generally have a separate board or USB module for analog and digital I/O (see Pulse and digital I/O). Counter/timer outputs produce pulse trains or count events.

Different I/O modules have different functionality. For instance, the Data Translation DT-300 board (PCI bus) has 4 counter/timers, while the Data Translation DT-9812 module (USB) has 1 counter/timer. For detailed information, see the user manuals for these products.

Observatory provides access to the counter/timers in two ways:

  • Script command MOVE_PH, if PH is Biondi
  • Manually from the Observatory front panel.

For the Biondi PH, the counter/timers, and the analog inputs used to read the position, are controlled by these parameters in the Observatory control file:

  • CTPlus_PHAz, CTMinus_PHAz, CTPlus_PHZe, CTMinus_PHZe specify the counter/timer units to be used for position error (difference between the desired and actual position) + or − for each axis.
  • PPol_PHAz, PRate_PHAz, PWidth_PHAz and PPol_PHZe, PRate_PHZe, PWidth_PHZe are the pulse polarity, rate (Hz) and width for the pulse train.
  • StepsDeg_PHAz and StepsDeg_PHZe convert the position errors in degrees to the number of pulses required.
  • AInChan_PHAz and AInChan_PHZe are the analog input channels used to read the current position of each axis; AInType_PHAz and AInType_PHZe are the analog input type (see Analog input).
  • AInRangeMin_PHAz, AInRangeMax_PHAz, and AInRangeMin_PHZe, AInRangeMax_PHZe are the voltage limits for the analog inputs.
  • AInConvA_PHAz, AInConvB_PHAz and AInConvA_PHZe, AInConvB_PHZe are the coefficients for linear conversion of analog input voltage to axis position in degrees: degrees = a * voltage + b.
  • AInTolerance_PHAz and AInTolerance_PHZe are the allowable position error, in degrees.

Counter/timer operation fron the front panel

The Observatory front panel can be used to send pulse trains using the counter/timer. This is normally only done for testing.

Select the parameters for the desired pulse train,
then click Start pulse train.


Shutters

Observatory supports two types of shutters: an older model digital level shutter, which is opened or closed by setting the level on a digital output, and a newer model, the Picard Industries USB shutter, which is connected to a USB port. Observatory supports one digital level shutter, which is unnamed, and up to four USB shutters, which have user-assigned names of 1−7 characters.

The digital level shutter requires several parameters in the Observatory control file:

DOut_FPIShutter       PPol_FPIShutter       PWidth_FPIShutter
Level_FPIShutterOpen  Level_FPIShutterClose

The USB shutters are named in the Observatory control file, with lines such as

ShutterName Laser 111 // a shutter named "Laser", serial number 111
ShutterName White 222 // a second shutter, "White", serial number 222
for each shutter. When Observatory is started, the Observatory control file is read to get a list of the USB shutters’ names and serial numbers. Observatory then attempts to connect to each of them.

The name, serial number and availability (i e, whether Observatory was able to connect to it) of each USB shutter is listed in the Observatory log, which is shown on the front panel. Here is an excerpt from a log file:

23:07:14 Name    Serial number Available? State    4 USB shutters specified
23:07:14   Laser           111         yes C
23:07:14   White           222         yes O
23:07:14    Neon           333         no  ?
23:07:14    Oflo           555         no  ?

In addition, the list of USB shutters, their state and availability, are also shown on the front panel.

This shows the control file named four shutters, but only the first two are available (connected and operational). The shutter “Laser” is closed, and the shutter “White” is open.

Double-clicking Laser on the first line will tell the shutter Laser to invert its state, from closed to open.

The display is updated each time a shutter command is issued by Observatory. Note: this is not monitoring the shutter itself, so if the hardware is not working, the display may indicate incorrect or unknown state.

The state of any available shutter may be toggled by double-clicking its name. The new state and availability will be updated in real time for 5 seconds.

Shutters are normally controlled by a script, using the command SHUTTER.


Filter

An A3O station may contain one of three types of filters: an n-position color wheel, a three-position slide filter, and an older two-position rotary filter. Observatory can control any of these, and knows which kind is connected from the Observatory control file variable FilterType. The default if FilterType is omitted is the older 630-732 filter.

The control file parameters for the three-position filter are somewhat similar, but not the same, as for the older two-position (630 and 732 nm) filter. For the color-wheel filter, the set of parameters is different, because the color wheel is connected via USB, and has no digital outpus.

The control file should contain the appropriate set of filter parameters for the installed hardware. If there is no filter at all, no filter parameters are needed in the control file.

This is an excerpt from an existing control file, showing the parameters for the older two-position 630-732 filter:

// Filter parameters
DOut_Filt630		8	// Digital output channel
PPol_Filt630		hi	// Pulse polarity
PWidth_Filt630		1000	// Pulse width (0=level) in usec
DIn_Filt630		0	// digital input channel
MaxWait_Filt630		20	// maximum sec to wait for filter transition before declaring an error
DOut_Filt732		9	// Digital output channel
PPol_Filt732		hi	// Pulse polarity
PWidth_Filt732		1000	// Pulse width (0=level) in usec
DIn_Filt732		1	// digital input channel
MaxWait_Filt732		20	// maximum sec to wait for filter transition before declaring an error
DIn_Filt630_Value	1	// value of DIn when 630 filter is in place
DIn_Filt732_Value	1	// value of DIn when 732 filter is in place
This is how the control file parameters for the three-position slide filter mechanism will appear:
// Filter parameters
FilterType		3	// 3-position filter slide (this is new; if it is omitted, the older 630-732 filter is assumed
DOut_FiltChoice0	8	// Digital output channel, LSB  ** These channels must be in the same subsystem (port)
DOut_FiltChoice1	9	// Digital output channel, MSB  ** Channels 0-7 are port A, 8-15 port B.
DIn_FiltMount		3	// Digital input channel which has "filter mounted" asserted

DVal_Filt557		01	// Levels to be placed on output channels for filter 557 (binary notation)
DIn_Filt557		0	// digital input channel
MaxWait_Filt557		20	// maximum sec to wait for filter transition before declaring an error
DIn_Filt557_Value	1	// value of DIn when slide is positioned to 557 filter

DVal_Filt630		10	// Levels to be placed on output channels for filter 630 (binary notation)
DIn_Filt630		1	// digital input channel
MaxWait_Filt630		20	// maximum sec to wait for filter transition before declaring an error
DIn_Filt630_Value	1	// value of DIn when slide is positioned to 630 filter

DVal_Filt0		11	// Levels to be placed on output channels for filter OPEN (binary notation)
DIn_Filt0		2	// digital input channel
MaxWait_Filt0		20	// maximum sec to wait for filter transition before declaring an error
DIn_Filt0_Value		1	// value of DIn when slide is positioned to 0 (open) filter
You will have to fill in the correct digital input channels (DIn_Filt n) and output channels (DOut_Filt n) for your configuration. In this, the filters are assumed to be 557, 630 and 0 (open), corresponding to filter positions 1, 2 and 3. If you decide to use different filters in the future, the symbol names would remain the same.

This is how the control file parameters for a six-position color-wheel filter will appear:

// Filter parameters
FilterType	4	// color-wheel filter
FiltSlots	6	// the number of filter positions (referred to as 0-5)
MaxWait_Filt	5	// maximum sec to wait for filter transition before declaring an error


Analog input

Of the total of 16 possible analog inputs to the DT-302’s analog-to-digital converter, four have assigned uses, and 12 are available for other uses. The assigned inputs are

Pointing head azimuth*
Pointing head zenith*
Outdoor temperature
Atmospheric pressure

* If Biondi PH is in use; not assigned for SkyScan.

For the DT-9812, there are 8 single-ended analog inputs. Since the DT-9812 is not used with the Biondi PH, only two of the analog inputs have assigned uses:

Outdoor temperature
Atmospheric pressure

Values for all analog inputs in use will be stored in the image file.

The unassigned inputs are referred to as auxiliary inputs, and they are numbered 0−11. The numbering has no intrinsic significance and need not be consecutive. At the time of image acquisition, Observatory will sample each auxiliary input which is specified in the control file and store it in the corresponding image file.

Each analog input requires six parameters in the Observatory control file, namely

AInChan_input | integer | The A/D channel to use on the DT-302 (0−15, or 0−7 if differential)
AInType_input |  | One of sing (single-ended), diff (differential), or pseudoDiff (pseudo-differential). This value is ignored in versions of Observatory < 0.70.
AInConvA_input | real | Slope used to convert the observed voltage: user value = a × voltage + b.
AInConvB_input | real | Intercept used to convert the observed voltage: user value = a × voltage + b.
AInRangeMin_input | real | The minimum voltage expected. In conjunction with the maximum below, this will be used to set the A/D gain.
AInRangeMax_input | real | The maximum voltage expected. In conjunction with the minimum above, this will be used to set the A/D gain.

In the above, input is one of PHAz, PHZe, Temp, Press, or Aux(n) (n=0,...,11). Only the auxiliary inputs which are to be sampled need appear in the control file.


Pointing head position

The pointing head (PH) is the name for the mechanism that allows the Fabry-Pérot interferometer (FPI) to view a particular direction. Two different mechanisms for pointing head have been used in the existing stations: the Biondi pointing head, designed in-house, and the newer SkyScan (Keo Scientific).

From the user’s point of view, both types of pointing head operate the same way: the user specifies the desired angles (azimuth and zenith; see Coordinate systems ), and the pointing head moves to that position.

The PH is positioned by

  • On power up or (Skyscan only) Master script command SETUP FPI SkyScan, the PH moves to a “home” position.
  • On Master script command MOVE_PH azimuth, zenith .
  • On operator positioning manually using the front panel.

What Observatory does when it gets instructions to move the PH to (az, ze)

  1. Convert the angle to instrument measure by adding the corrections AzCorr and ZeCorr. These come from Observatory’s control file and are the difference between the installed station direction and true North.

  2. If the PH is SkyScan:
    1. Bring the resulting az into the range 0−180° (see Coordinate systems for how this is done).
    2. Convert the angles to counts, using the conversion factors azCountsPerRev and zeCountsPerRev. These come from Observatory’s control file, or from the SkyScan instrument itself if the control file values are 0, or, if the conversion factors are not seen in the control file, to 24,000 counts/revolution.
    3. Both the azimuth (motor 1) and zenith (motor 2) motors are started.
    4. The angles are checked every checkTime_SkyScan msec, for a maximum time of maxWait_SkyScan sec. These parameters come from Observatory’s control file. Typical values are 750 msec and 30 sec, respectively.

  3. If the PH is Biondi:
    1. Measure current position and, if not at the desired position, start a pulse train to move either Az or Ze. The criterion for being at the desired position is that the difference between the actual and desired angle is less than AInTolerance_PHAz or AInTolerance_PHZe.
    2. The number of pulses in the pulse train is the product of the difference and StepsDeg_PHAz or StepsDeg_PHZe. The pulses are sent on the counter/timer channel CTPlus_PHAz / CTMinus_PHAz or CTPlus_PHZe / CTMinus_PHZe if the difference is +/−. The polarity, rate, and pulse width are determined by PPol_PHAz, PRate_PHAz, PWidth_PHAz or PPol_PHZe, PRate_PHZe, PWidth_PHZe.
    3. The above steps are repeated a maximum of maxIterations_PHAz or maxIterations_PHZe times.

  4. Each time the position is measured, the angles and elapsed time are stored in the log and, for SkyScan only, displayed on the Observatory front panel.


Observatory Log

While it is running, Observatory produces a log, showing what actions it has taken, and their results. The log appears on the Observatory front panel, and is also periodically written to a file. The main purpose of the log is troubleshooting.

Here is an example of the log as shown on the screen:

Variables such as the station location are read from the Observatory control file, and appear in the log for verification. Other log entries come from detecting and initializing the hardware (for example, in the sample above, there was no analog/digital I/O module connected). Some values are generated by Observatory, such as the name of the log file (the log filename can be modified by script command LOG_DIRECTORY Observatory).

The log entries are displayed on the screen, and after every 1000 lines, written to the log file, or when Observatory is closed. Additionally, the log is copied to the disk file every LogWriteFreq msec, so that log data will be available in case of a power failure or program crash. When data is copied from screen to file, the log entries on the screen are cleared, and the lines like

[previous log written to file]            [UTC 2012-5-21  20:33:30]
Auto-write                                20:33:30 Auto-write
          Screen                                 Log file
will appear on the screen and in the log file.

The default name for an Observatory log file is Observatory_YYYYMMDDhhmmss.txt, and the default directory is the directory of the program (Observatory.exe).

LogWriteFreq is an optional variable in Observatory control file. If it is not present, the default value is 180,000 msec (30 min). It may not be set to less than 1,000 msec (1 sec).


Observatory's control file

Observatory’s control file

The control file is a text file, which you can edit with any text editor. Like the other control files used by A3O, each line has the general format symbol_name value.

The following table shows the possible parameters. Most are required; those that are optional have default values. In the table, “Ar” means Arequipa apparatus.

symbol_name | Data type | Required? | Meaning | Default value
General
apparatusType | integer | yes | 1 for Arequipa, 2 for Alaska |
DisableHRPC | integer | no | Disable the high-resolution performance counter, even if available. | 0 (do not disable)
DetailedLog | true/false | no | Record the details of communications between PC and apparatus (produces large log file). | FALSE
LogWriteFreq | integer | no | Maximum time between Observatory log writes to disk, msec. | 30*60*1000 (30 min)
DopplerShiftFSR | real | yes | Velocity due to free spectral range (peak spacing), m/s. |
Location and calibration of the PH (station)
stationLatitude | real | yes | Geodetic latitude in degrees: north positive. |
stationLongitude | real | yes | Geodetic longitude in degrees; east positive. |
stationHeight | real | yes | Height of the observer in meters above sea level. |
stationNumber | integer | yes | Number supplied by user to distinguish installations. |
AzCorr | real | yes | Degrees to add to user-specified Az to get PH direction. |
ZeCorr | real | yes | Degrees to add to user-specified Ze to get PH direction. |
SkyScanner angle calibration
azCountsPerRev | integer | no | Conversion between SkyScan azimuth revolutions and counts. | 24000
zeCountsPerRev | integer | no | Conversion between SkyScan zenith revolutions and counts. | 24000
Pointing head parameters
PHType | integer | yes | 0 for Biondi, 1 for SkyScan, 2 for no pointing head. For PHType=2, the angles in the image header will be (AzCorr, ZeCorr). |
SkyScan_model | integer | yes | 0 for early models SkyScan, 4 for SkyScan4. |
Serial communication parameters (used only for SkyScan PH)
PHCommPort | string | yes | The name of the serial port (e g, "COM1") through which SkyScan commununicates with the PC. |
Serial_baudRate | integer | yes | Bits/sec. |
Serial_nInputCharDelay | integer | yes | Number of character times to allow between characters. |
Serial_inputPerCharTimeout | integer | yes | For total timeout, the value per character requested, msec. |
Serial_inputAddlTimeout | integer | yes | For total timeout, the constant added to above, msec. |
SkyScan PH parameters
maxWait_SkyScan | integer | yes | Maximum time to wait for completion of a SkyScan motion, in sec. |
checkTime_SkyScan | integer | yes | Time between checks for completion of a SkyScan motion, in msec. |
maxWaitHome_SkyScan | integer | yes | Maximum time to wait for a SkyScan homing sequence, in sec. |
maxWaitImmediate_SkyScan4 | integer | no | Maximum time to wait for a SkyScan 4 “immediate” response, in msec. | 20
SkyScan PH manual positioning controls on the front panel
azCoarse | real | yes | Coarse azimuth adjustment, degrees. |
azMedium | real | yes | Medium azimuth adjustment, degrees. |
azFine | real | yes | Fine azimuth adjustment, degrees. |
zeCoarse | real | yes | Coarse zenith adjustment, degrees. |
zeMedium | real | yes | Medium zenith adjustment, degrees. |
zeFine | real | yes | Fine zenith adjustment, degrees. |
Biondi PH parameters
AInChan_PHAz | integer | yes |  |
AInType_PHAz | AITAnalog input type: one of sing (single-ended) diff (differential) pseudoDiff (pseudo-differential) | yes |  |
AInChan_PHZe | integer | yes |  |
AInType_PHZe | AIT | yes |  |
AInConvA_PHAz | real | yes |  |
AInConvB_PHAz | real | yes |  |
AInConvA_PHZe | real | yes |  |
AInConvB_PHZe | real | yes |  |
StepsDeg_PHAz | integer | yes |  |
StepsDeg_PHZe | integer | yes |  |
ExtClkFreq_PHAz+ | integer | no |  |
ExtClkFreq_PHAz- | integer | no |  |
ExtClkFreq_PHZe+ | integer | no |  |
ExtClkFreq_PHZe- | integer | no |  |
PRate_PHAz | integer | yes |  |
PRateMax_PHAz | integer | yes |  |
PRate_PHZe | integer | yes |  |
PRateMax_PHZe | integer | yes |  |
PWidth_PHAz | integer | yes |  |
PWidth_PHZe | integer | yes |  |
PPol_PHAz | PT | yes |  |
PPol_PHZe | PT | yes |  |
maxIterations_PHAz | integer | yes |  |
maxIterations_PHZe | integer | yes |  |
AInRangeMin_PHAz | real | yes |  |
AInRangeMax_PHAz | real | yes |  |
AInRangeMin_PHZe | real | yes |  |
AInRangeMax_PHZe | real | yes |  |
AInTolerance_PHAz | real | yes |  |
AInTolerance_PHZe | real | yes |  |
CTPlus_PHAz | integer | yes |  |
CTMinus_PHAz | integer | yes |  |
CTPlus_PHZe | integer | yes |  |
CTMinus_PHZe | integer | yes |  |
Filter parameters
RelayName | integer | for Ar |  |
PPol_Filt630 | PT | for Ar |  |
PWidth_Filt630 | integer | for Ar |  |
DIn_Filt630 | integer | for Ar |  |
DIn_Filt630_Value | integer | for Ar |  |
MaxWait_Filt630 | integer | for Ar |  |
DOut_Filt732 | integer | for Ar |  |
PPol_Filt732 | PT | for Ar |  |
PWidth_Filt732 | integer | for Ar |  |
DIn_Filt732 | integer | for Ar |  |
DIn_Filt732_Value | integer | for Ar |  |
MaxWait_Filt732 | integer | for Ar |  |
FilterType | integer | yes | Omit for 2-position, 3 for slide, 4 for color wheel. Details |
FiltSlots | integer | wheel only | Number of positions on wheel. |
MaxWait_Filt | integer | wheel only | Maximum seconds to allow for filter change. |
DOut_FiltChoice0 | integer | slide only |  |
DOut_FiltChoice1 | integer | slide only |  |
DIn_FiltMount | integer | slide only |  |
DVal_Filt557 | integer | slide only |  |
DIn_Filt557 | integer | slide only |  |
MaxWait_Filt557 | integer | slide only |  |
DIn_Filt557_Value | integer | slide only |  |
DVal_Filt630 | integer | slide only |  |
DVal_Filt0 | integer | slide only |  |
DIn_Filt0 | integer | slide only |  |
MaxWait_Filt0 | integer | slide only |  |
DIn_Filt0_Value | integer | slide only |  |
Optical extender parameters
DOut_OPX | integer | for Ar |  |
PPol_OPX | PT | for Ar |  |
PWidth_OPX | integer | for Ar |  |
DIn_OPXin | integer | for Ar |  |
DIn_OPXin_Value | integer | for Ar |  |
MaxWait_OPXin | integer | for Ar |  |
Level_OPXin | integer | for Ar |  |
DIn_OPXout | integer | for Ar |  |
DIn_OPXout_Value | integer | for Ar |  |
MaxWait_OPXout | integer | for Ar |  |
Level_OPXout | integer | for Ar |  |
Pointing head heater parameters
DOut_PHHtr | integer | for Ar |  |
PPol_PHHtr | PT | yes |  |
PWidth_PHHtr | integer | yes |  |
FPI shutter parameters
DOut_FPIShutter | integer | yes |  |
PPol_FPIShutter | PT | yes |  |
PWidth_FPIShutter | integer | yes |  |
Level_FPIShutterOpen | integer | yes |  |
Level_FPIShutterClose | integer | yes |  |
ShutterName | SHname serialNumber The name is 1−7 characters (case-sensitive, alphanumeric), and must differ from other shutter names. The serial number is printed on the label of Picard USB shutters. | no | Identifies a shutter connected via USB. There may be up to four of these variables. |
Relay (swing mirror) parameters
RelayName | REname serialNumber relayNumber The name is 1−7 characters (case-sensitive, alphanumeric), and must differ from other relay names. The serial number is printed on the label of Picard USB relay board, and the relay number indicates which relay on the board (0−3). | no | Identifies a relay connected via USB. There may be up to four of these variables. |
Scene motor parameters
DOut_ScLaser | integer | for Ar |  |
PPol_ScLaser | PT | for Ar |  |
PWidth_ScLaser | integer | for Ar |  |
DIn_ScLaser | integer | for Ar |  |
DIn_ScLaser_Value | integer | for Ar |  |
MaxWait_ScLaser | integer | for Ar |  |
DOut_ScSky | integer | for Ar |  |
PPol_ScSky | PT | for Ar |  |
PWidth_ScSky | integer | for Ar |  |
DIn_ScSky | integer | for Ar |  |
DIn_ScSky_Value | integer | for Ar |  |
MaxWait_ScSky | integer | for Ar |  |
Pressure sensing parameters
AInChan_Press | integer | yes |  |
AInType_Press | AIT | yes |  |
AInConvA_Press | real | yes |  |
AInConvB_Press | real | yes |  |
AInRangeMin_Press | real | yes |  |
AInRangeMax_Press | real | yes |  |
Temperature sensing parameters
AInChan_Temp | integer | yes |  |
AInType_Temp | AIT | yes |  |
AInConvA_Temp | real | yes |  |
AInConvB_Temp | real | yes |  |
AInRangeMin_Temp | real | yes |  |
AInRangeMax_Temp | real | yes |  |
Aux analog input parameters
AInChan_Aux | integer | no |  |
AInType_Aux | AIT | no |  |
AInConvA_Aux | real | no |  |
AInConvB_Aux | real | no |  |
AInRangeMin_Aux | real | no |  |
AInRangeMax_Aux | real | no |  |

Here is a complete sample control file for Observatory. Blank lines are ignored, and text following “//” are comments.

// ObservatoryControlFile.txt:

apparatusType	2 // Cape Verde apparatus = 2 for now

DopplerShiftFSR   6281.

stationNumber 8

RelayName sky   099 0   // swing mirror made flat to observe Sky direction
RelayName laser 099 1   // swing mirror pushed out to observe Laser calibration chamber

DetailedLog     F       // show detailed log (T for yes, F for no)

DisableHRPC     1    // non-zero to disable use of high-res counter, if present
ExtClkFreq_PHAz+		25000     //external clock rate for PH azimuth +C/T, Hz
ExtClkFreq_PHAz-		25000    //external clock rate for PH azimuth -C/T, Hz
ExtClkFreq_PHZe+		25000   //external clock rate for PH Zenith +C/T, Hz
ExtClkFreq_PHZe-		25000  //external clock rate for PH Zenith -C/T, Hz

PRate_PHAz	35	// desired pulse rate for azimuth motor, integer Hz
PRateMax_PHAz	1000 	// maximum pulse rate for azimuth motor, integer Hz
PRate_PHZe	35 	// desired pulse rate for zenith motor, integer Hz
PRateMax_PHZe	1000 	// maximum pulse rate for zenith motor, integer Hz

// entering data for MRH

stationLatitude        -11.958     //geodetic latitude in degrees: north positive
stationLongitude       -76.859     //geodetic longitude in degrees; east positive
stationHeight           1090.           //height of the observer in meters

PHType        1         // SkyScan is one, Biondi is zero
PHCommPort    "COM1"    // serial port through which SkyScan communicates with PC
SkyScan_model	4	// SkyScan4

AzCorr  0.2 //-1.27  //-4.83 //1.5 //-0.8    //-10.9    Add to user specified Az to get PH direction
ZeCorr  -1.54//-1.29//-7.29  //-4.75    Add to user specified Ze to get PH direction

Serial_baudRate 115200             //  Serial_ parameters are only for the SkyScan PH
Serial_nInputCharDelay  0     // # char times to allow between chars
Serial_inputPerCharTimeout  20 // for timeout, value per char request., msec
Serial_inputAddlTimeout 10    // for timeout, the const. added to above, msec;

maxWait_SkyScan 30     // maximum time to wait for a SkyScan motion, in sec
checkTime_SkyScan  750   // time between checks for SkyScan motion, in msec
maxWaitHome_SkyScan	60     // maximum time to wait for a SkyScan homing sequence, in sec
maxWaitImmediate_SkyScan4	20	// maximum time to wait for a SkyScan 4 "immediate" response, in msec

LogWriteFreq 1200000  // time between written log file entries msecs

// Arequipa Pointing head parameters

AInChan_PHAz	0	// analog input channel for PH azimuth angle
AInType_PHAz	sing	// analog input type for PH az angle (currently ignored)
AInChan_PHZe	1	// analog input channel for PH zenith angle
AInType_PHZe	sing	// analog input type for PH zenith angle (currently ignored)
AInConvA_PHAz	19.53	// conversion from azimuth voltage to angle in degrees
AInConvB_PHAz	0.304	// degrees=a*voltage+b
AInConvA_PHZe	10.0	// conversion from zenith voltage to angle in degrees
AInConvB_PHZe	 0.0	// degrees=a*voltage+b
StepsDeg_PHAz	10	// number of steps per azimuth degree
StepsDeg_PHZe	10	// number of steps per zenith degree
PWidth_PHAz	200	// desired pulse width for azimuth motor, integer usec
PWidth_PHZe	200	// desired pulse width for zenith motor, integer usec
maxIterations_PHAz	3	// maximum number of tries for the PH azimuth angle
maxIterations_PHZe	3	// maximum number of tries for the PH zenith angle
AInRangeMin_PHAz	0	// minimum possible volt from PH az position sensor
AInRangeMax_PHAz	10	// maximum possible volt from PH az position sensor
AInRangeMin_PHZe    -10	// minimum possible volt from PH ze position sensor
AInRangeMax_PHZe	10	// maximum possible volt from PH zenith position sensor
AInTolerance_PHAz	0.5	// desired positioning accuracy for PH az in degrees
AInTolerance_PHZe	0.5	// desired positioning accuracy for PH ze in degrees
CTPlus_PHAz	0	// counter/timer to be used to move PH az in + direction
CTMinus_PHAz	1	// counter/timer to be used to move PH az in - direction
CTPlus_PHZe	2	// counter/timer to be used to move PH zenith in + direction
CTMinus_PHZe	3	// counter/timer to be used to move PH zenith in - direction
PPol_PHAz       lo      // polarity of the pulse hi = positive, lo = negative
PPol_PHZe       lo

// Filter parameters
FilterType  3      // 3-position filter slide (this is new;
                  //if it is omitted, the older 630-732 filter is assumed

DOut_FiltChoice0	1	// Digital output channel, MSB
                               //** These channels must be in the same subsystem (port)
DOut_FiltChoice1	2	// Digital output channel, LSB
                              //** Channels 0-7 are port A, 8-15 port B.
DIn_FiltMount	3	// Digital input channel which has "filter mounted" asserted

DVal_Filt557	11	// Levels to be placed on output channels for filter 557 (binary notation)
DIn_Filt557	0	// digital input channel
MaxWait_Filt557	20	// maximum sec to wait for filter transition before declaring an error
DIn_Filt557_Value	1	// value of DIn when slide is positioned to 557 filter

DVal_Filt630	01	// Levels to be placed on output channels for filter 630 (binary notation)
DIn_Filt630	1	// digital input channel
MaxWait_Filt630	20	// maximum sec to wait for filter transition before declaring an error
DIn_Filt630_Value	1	// value of DIn when slide is positioned to 630 filter

DVal_Filt0	10	// Levels to be placed on output channels for filter OPEN (binary notation)
DIn_Filt0	2	// digital input channel
MaxWait_Filt0	20	// maximum sec to wait for filter transition before declaring an error
DIn_Filt0_Value	1	// value of DIn when slide is positioned to 0 (open) filter

// Arequipa Pointing head heater parameters
DOut_PHHtr	20	// Digital output channel
PPol_PHHtr	hi	// Pulse polarity
PWidth_PHHtr	1000	// Pulse width (0=level) in usec

// Laser shutter parameters
DOut_FPIShutter	4 	// Digital output channel
PPol_FPIShutter	lo	// Pulse polarity
PWidth_FPIShutter	0	// Pulse width (0=level) in msec
Level_FPIShutterOpen	0	// level to open the shutter
Level_FPIShutterClose	1	//       close

// USB shutters and relays
ShutterName  LASER 174 // shutter serial 174
RelayName	LMirror 77 0 // relay 0 on serial 77
RelayName	SMirror 77 1
RelayName	Rly02   77 2
RelayName	Rly03   77 3

// Arequipa Pressure sensing parameters
AInChan_Press	2	// Analog input channel
AInType_Press	sing	// Analog input type
// AInGain_Press	1	// Analog gain
AInConvA_Press	1.0	// Conversion from voltage to pressure in bars
AInConvB_Press	0.0	// bars=a*voltage+b
AInRangeMin_Press	0	// Minimum voltage expected
AInRangeMax_Press	10	// Maximum voltage expected

// Temperature sensing parameters
AInChan_Temp	3	// Analog input channel
AInType_Temp	sing	// Analog input type
// AInGain_Temp	1	// Analog gain
AInConvA_Temp	6.0	// Conversion from voltage to temperature in degrees C
AInConvB_Temp	0.0	// degrees=a*voltage+b
AInRangeMin_Temp	0	// Minumum voltage expected
AInRangeMax_Temp	10	// Maximum voltage expected

//  Definitions of increments for course, medium, and fine movements of the skyscanner
azCoarse	1.00	// coarse azimuth adjustment, degrees
azMedium	0.30	// medium azimuth adjustment, degrees
azFine	        0.10	        // fine azimuth adjustment, degrees
zeCoarse	1.0	// coarse zenith adjustment, degrees
zeMedium	0.3	// medium zenith adjustment, degrees
zeFine	        0.1	        // fine zenith adjustment, degrees

azCountsPerRev 19692
zeCountsPerRev 19692


Observatory Known Bugs

TO DO


Changes in Observatory v1.63 2014-12-8

  1. This version of Observatory must be used with updated versions of the other processes: Master v1.04 (new), Camera v1.34, Analyze v2.03 and Communicate v0.07, or later.

  2. For the SkyScan4 model only, when a script had a MOVE_PH command, it would return immediately and the Observatory log would contain an error, although there was none. This has been corrected.

  3. The color-wheel filter returns after a motion is complete, as before, but the log entry will now show completion after 0.0 sec.


Changes in Observatory v1.62 2014-11-18

  1. This version of Observatory must be used with updated versions of the other processes: Master v1.04 (new), Camera v1.34, Analyze v2.03 and Communicate v0.07, or later.

  2. Observatory now accepts script commands for selecting the filters on the color wheel. See Master / Script commands / SELECT_FILTER for details.

  3. The Observatory front panel now positions the caret at the end of the text after a position is entered.


Changes in Observatory v1.59 2014-11-8

  1. This version of Observatory must be used with updated versions of the other processes: Master v1.02, Camera v1.34, Analyze v2.03 and Communicate v0.07, or later.

  2. Support for the 6-position color wheel (Finger Lake Instrument model FL-CFW-6-6) has been added. To use this, different settings in the Observatory control file are needed, for example:
    // Filter parameters
FilterType	4      	// color wheel
FiltSlots	6	// number of positions on wheel.
MaxWait_Filt	5	// maximum seconds to allow for filter change.
    See Observatory control file and Filter for details.


Changes in Observatory v1.58 2014-5-16

  1. This version of Observatory must be used with updated versions of the other processes: Master v1.02, Camera v1.34, Analyze v2.03 and Communicate v0.07, or later.

  2. Position query for sky scanner models other than SkyScan 4 stopped prematurely with an error indication, although there was no error. This meant an incorrect angle was reported and stored in the image file header in some cases. This problem has been fixed.


Changes in Observatory v1.57 2014-5-9

  1. This version of Observatory must be used with updated versions of the other processes: Master v1.02, Camera v1.34, Analyze v2.03 and Communicate v0.07, or later.

  2. Position query reporting for SkyScan 4 was incorrect, leading to a buffer overflow. This has been fixed.

  3. The detail log gave a spurious error indication when reading the repsonse to "S?" for SkyScan 4. This has been corrected.


Changes in Observatory v1.56 2013-12-18

  1. This version of Observatory must be used with updated versions of the other processes: Master v1.01, Camera v1.29, Analyze v2.02 and Communicate v0.07, or later.

  2. Some debugging code accidentally left in v1.55 was removed.


Changes in Observatory v1.55 2013-12-16

  1. This version of Observatory must be used with updated versions of the other processes: Master v1.01, Camera v1.27, Analyze v2.02 and Communicate v0.07, or later.

  2. For SkyScan4, the handling of the position query (status) command has been corrected.


Changes in Observatory v1.54 2013-12-11

  1. This version of Observatory must be used with updated versions of the other processes: Master v1.01, Camera v1.26, Analyze v2.01 and Communicate v0.06, or later.

  2. The Observatory control file now has a new, optional, parameter: maxWaitImmediate_SkyScan4. This is the maximum time to wait for an “immediate” response to a SkyScan 4 command, in msec. If this parameter is not specified, a default of 20 msec is used.

  3. In SkyScan4 initialization, the identification string is now terminated when shown in the log.

  4. The problem which cause a buffer overflow assert when SkyScan 4 Home completes has been fixed.


Changes in Observatory v1.53 2013-12-4

  1. This version of Observatory must be used with updated versions of the other processes: Master v1.00, Camera v1.23, Analyze v2.00 and Communicate v0.06, or later.

  2. The Observatory control file now has a new, required, parameter: maxWaitHome_SkyScan. This is the maximum time to wait for a SkyScan homing sequence, in seconds.

  3. The display time for the “No Data Translation module found” message has been decreased from 60 sec to 15 sec. After this the message will disappear, as if user had clicked the OK button.

  4. In SkyScan4 initialization:
    1. The identification string is now requested and logged.
    2. The configuration parameters requested and logged are now C0, C1 and C2 (not C2(n)).

  5. For Skyscan4, the “input buffer cleanout” that occurs before each command is sent now does not wait for input. Previously, it waited 50*Serial_inputPerCharTimeout + Serial_inputAddlTimeout msec.


Changes in Observatory v1.52 2013-11-21

  1. This version of Observatory must be used with updated versions of the other processes: Master v1.00, Camera v1.23, Analyze v2.00 and Communicate v0.06, or later.

  2. An new variable, SkyScan_model, is required in the Observatory control file. This should be 4 for the SkyScan4, or 0 for earlier models.


Changes in Observatory v1.51 2013-10-31

  1. This version of Observatory must be used with updated versions of the other processes: Master v1.00, Camera v1.23, Analyze v2.00 and Communicate v0.06, or later.

  2. An new variable, SkyScan_model, is required in the Observatory control file. This should be 4 for the SkyScan4, or 0 for earlier models.


Changes in Observatory v1.50 2013-10-2

  1. This version of Observatory must be used with updated versions of the other processes: Master v1.00, Camera v1.23, Analyze v2.00 and Communicate v0.06, or later.

  2. The relay setup process no longer attempts to connect to multiple relays with the same board serial number.


Changes in Observatory v1.49 2013-10-1

  1. This version of Observatory must be used with updated versions of the other processes: Master v1.00, Camera v1.23, Analyze v2.00 and Communicate v0.06, or later.

  2. Control file lines which contain only blanks and tabs are now ignored. Previously, such lines caused spurious errors.


Changes in Observatory v1.48 2013-9-29

  1. This version of Observatory must be used with updated versions of the other processes: Master v0.99, Camera v1.22, Analyze v1.99 and Communicate v0.05, or later.

  2. The Observatory control file now optionally includes the characteristics of up to 4 USB relays, using the symbol RelayName.

  3. The Observatory front panel now shows USB relays. The list formerly labeled Shutters is now Shutters and relays.

  4. The state of each USB relay is toggled by double-clicking its name in the above list. Its new state (0=open, 1=closed) will be shown in the list.


Changes in Observatory v1.47 2013-9-24

  1. This version of Observatory must be used with updated versions of the other processes: Master v0.99, Camera v1.22, Analyze v1.99 and Communicate v0.05, or later.

  2. There are no changes in functionality from v1.46.


Changes in Observatory v1.46 2013-2-20

  1. This version of Observatory must be used with updated versions of the other processes: Master v0.98, Camera v1.21, Analyze v1.91 and Communicate v0.03, or later.

  2. There are no changes in functionality from v1.45.


Changes in Observatory v1.45 2012-11-8

  1. This version of Observatory must be used with updated versions of the other processes: Master v0.96, Camera v1.20, Analyze v1.90 and Communicate v0.01, or later.

  2. There are no changes in functionality from v1.44.


Changes in Observatory v1.44 2012-9-5

  1. This version of Observatory must be used with updated versions of the other processes: Master v0.94, Camera v1.19 and Analyze v1.88, or later.

  2. The Observatory log file can now be named more flexibly. See LOG_DIRECTORY for details.


Changes in Observatory v1.43 2012-8-24

  1. This version of Observatory must be used with updated versions of the other processes: Master v0.93, Camera v1.18 and Analyze v1.87, or later.

  2. When a reference body was selected on the Observatory front panel, the angles of that body from the station, at the current time, are displayed on the front panel. The current time is also displayed. Although the time said it was UTC, in fact it was local time. This has been corrected, so UTC time is shown.

  3. The Observatory log file can now be named more flexibly. See LOG_DIRECTORY for details.


Changes in Observatory v1.42 2012-5-1

  1. The warning message that appears if there is no DT module disappears after 60 seconds (earlier if OK is clicked). This allows Observatory to restart without operator intervention, assuming Master is running.

    If Master is not running, the “Observatory is running stand-alone” message appears, and that message requires the operator to click OK before proceeding.


Changes in Observatory v1.41 2012-4-19

  1. The Observatory front panel now has a display which shows the available shutters and their states, and allows changing the state.


Changes in Observatory v1.40 2012-4-18

  1. Support has been added for up to four Picard Industries USB shutters. In order to use these, a line ShutterName must be added to the Observatory control file for each USB shutter. For example,
    ShutterName Laser 111 // a shutter named "Laser", serial number 111
ShutterName White 222 // a second shutter, "White", serial number 222


Changes in Observatory v1.39 2012-1-19

  1. Observatory has been rebuilt to be compatible with Master v0.90.


Changes in Observatory v1.38 2012-1-17

  1. The zenith angle was not being reported correctly after a MOVE PH operation. This has been fixed.

  2. The fw version for the zenith motor was incorrectly labeled SmartMotor 1 response, rather than 2, in the log. This has been fixed.


Changes in Observatory v1.37 2012-1-16

  1. Corrections have been made so Observatory will operate properly with SmartMotors using the “class 5” firmware (model 2316). Observatory should also work properly with the older model 2315 motors, which have class 4 firmware.


Overview of Analyze

Analyze displays and processes images. It may be used as part of A3O, controlled by Master, or by itself (stand-alone).

Images are bitmaps with a header. Pixels in the bitmap are 16 bits, and so range from 0 to 216− 1 = 65,535. The image may be up to 2048 × 2048 pixels, and need not be square. Information on the dimensions is in the header.

Images are produced by Camera, and stored as files typically with .img extension, although the file names and extension are entirely controlled by the script run by Master.

The current convention is that image files are named type_letter date sequence.img, where type_letter is one of

type_letter | Meaning
B | Bias image
K | Dark image, sky
D | Dark image
L | Laser calibration image
Z | Sky image, zenith
N | Sky image
T | ?

The date field is yyyymmdd, and the sequence is three digits, with separate numbering used for each image type. For example, an image stored as L20111227003.img would be the third laser calibration image taken on Dec 27, 2011. The file naming scheme, though, is completely determined by the user, as a user-written script creates the entire filename. See SAVE_IMAGE for an example.

The image header, which is 1024 bytes long, contains information about the camera, detector, camera settings, the image itself, and state of the pointing mechanism. All this information is shown in the header detail window. Most of it is not needed for normal use.

When used stand-alone, an image may be displayed using File / Open..., or the Open button on the toolbar. When controlled by Master, the script command DISPLAY_IMAGE tells Analyze to open an image file. Typically, a script will have a DISPLAY_IMAGE after each image is acquired, so Analyze will display and process images in real time, for the benefit of an operator.

Images may also be opened and processed using the File / Batch process images. This function can only be initiated from the screen. See Batch processing images for details.

Many of the parameters which control the analysis and display of images are stored in a control file, which is called AnalyzeControlFile.txt, and must be in the same directory as the executable (Analyze.exe). This file is described in detail in Analyze’s control file.

Once an image has been opened, it is displayed according to the user’s chosen settings (see Image display), and processed as specified in the control file.

The results of processing are shown in the quick-look plots , annular integration window and cross-section windows.

Here is a sample image display:


Analyze’s control file

The control file is a text file, which you can edit with any text editor. Like the other control files used by A3O, each line has the general format symbol_name value.

The following table shows the possible parameters. Most are required; those that are optional have default values.

Many of these parameters can be changed on the fly by the user from a menu, toolbar, or window. In this case, the control file values are the initial choices when Analyze is started.

symbol_name | Data type | Required? | Meaning | Default value
Image display parameters
displayFreqX | integer | no | Frequency of points in x-direction to be shown in image. | 1
displayFreqY | integer | no | Frequency of points in y-direction to be shown in image. | 1
Image processing parameters
Process | Process | yes | Describes how each image type should be processed. See Image processing. |
nZonesX | integer | yes | Number of x zones for dark image smoothing. |
nZonesY | integer | yes | Number of x zones for dark image smoothing. |
darkImagesD | boolean | yes | Only D images used for background removal; else K images for laser. |
smoothDarkPasses | integer | yes | Maximum number of dark image smoothing passes. |
smoothDarkNStdDev | real | yes | In dark image, maximum allowed standard deviations from the mean before replacement with mean. |
smoothDarkAvg | boolean | yes | Replace every dark image pixel with mean of its zone. |
smoothPasses | integer | yes | Maximum number of smoothing passes during annular integration. |
noiseAnnAvg | boolean | yes | Replace noisy pixels during annular integration with mean of their annulus (noisy defined below). If this is FALSE, smoothing is done by replacing pixels differing by more than the spike limit with average of neighbors. |
smoothNStdDev | real | yes | Noisy pixels are those more than smoothNStdDev standard deviations from the mean of the annulus. |
Annular integration parameters
annIntPrefs | integer | no | Defaults for how the annular integration should be displayed | exp data: points only; Gaussian fit: lines only; Fourier fit: lines only
centerUsing | Centering | no | How image center is chosen for annular integration | LASER
nBrightnessCats | integer | no | Number of pixel brightness levels used for automatic center determination | 4
loBrightnessFrac | real | no | Fraction of total pixels taken to be minimum brightness | 2e-4
hiBrightnessFrac | real | no | Fraction of total pixels taken to be maximum brightness | 2e-4
imageCtrPxX | real | yes | Image center x (pixels) to be used if automatic centering is off |
imageCtrPxY | real | yes | Image center y (pixels) to be used if automatic centering is off |
nAnnuli | integer | yes | Number of equal-area annular zones to be used |
ff0 | real | no | Flat field corrections: the 1-D interferogram is multiplied by ff1*annulus+ff0. Ideally, ff0=1, ff1=0. | 0
ff1 | real | no | [see above] | 1
nPeaksExpected | integer | no | Number of peaks in annular integeral to be fitted | 0
peakRange[i] | Peak | no | Range of annuli for each sky image peak (i=0,1,...,nPeaksExpected−1 |
peakRangeLaser | Peak | no | Range of annuli for each laser image peak (i=0,1,...,nPeaksExpected−1 |
adaptivePeaks | boolean | no | Peak ranges are adjusted after each image according to actual peak locations | FALSE
Fourier analysis parameters
thickness | real | yes | Spacer gap in cm. |
indexRefraction | real | yes | Index of refraction for nitrogen within the etalon. |
lambdaLaser | real | yes | Laser wavelength in nm. |
lambdaSky | real | yes | Nightglow wavelength in nm. |
atomicWeight | real | yes | Emitter atomic or molecular weight in g/mol. |
nCoef | integer | yes | Number of Fourier coefficients to use for fitting | 0
sin_set | Real vector | yes | Normalized set of Fourier sine coefficients shifted so peaks are at beginning and end of free spectral range | 0
cos_set | Real vector | yes | Normalized set of Fourier cosine coefficients shifted so peaks are at beginning and end of free spectral range | 0
calcFSR | boolean | yes | FSR (K sky) is computed from the laser images |
FSR | real | no | If calcFSR is FALSE, this is the FSR to be used |
weight | boolean | no | Data is accorded a weight proportional to 1/value | TRUE
wtZero | integer | no | If weight, how to treat 0 points | Ignore 0 points
q1 | real | no | Used in the argument of the trig functions: arg=(2πn/K image)(q 1 U 3+k+q 0) | −1
q0 | real | no | [see above] | 0
dumpEval | boolean | no | Output Fourier model function and Jacobian to file for every iteration | FALSE
“Quick-look” parameters
QLPrefs | integer | no | Defaults for which fits appear on the quick-look graphs. | show Fourier, show Gaussian
zenith0 | real | yes | Maximum zenith angle for a zenith image. |
tempProcess | boolean | no | Calculate temperature from zenith images. | TRUE
write1D | boolean | no | Write the entire 1-dimensional interferogram (annular integration) into the quick-look output file. | FALSE
timeScale | Range list | no | List of scaling choices for time axis. | no choices
velScale | Range list | no | List of scaling choices for velocity axis. | no choices
intensScale | Range list | no | List of scaling choices for intensity axis. | no choices
tempScale | Range list | no | List of scaling choices for temperature axis. | no choices
dirAzTolerance | real | no | Angular difference in az to be considered a different direction for the quick-look plots. | 0.1
dirZeTolerance | real | no | Angular difference in ze to be considered a different direction for the quick-look plots. | 0.1
vSignAdj | boolean | no | Meteorology sign convention re speed is used | FALSE
vSignTol | real | no | If vSignAdj, the angle must be <vSignTol (in degrees) away from a cardinal angle to be considered a cardinal direction. | 0.3
Image generation parameters
sx | real | yes | Detector size in cm, x. |
sy | real | yes | Detector size in cm, y. |
px | integer | yes | Image pixels in x-direction. |
py | integer | yes | Image pixels in x-direction. |
bx | integer | yes | Binning in x-direction. |
by | integer | yes | Binning in y-direction. |
centerX | real | yes | x-coordinate of the generated image center. |
centerY | real | yes | y-coordinate of the generated image center. |
f0 | real | yes | Effective focal length of lens. |
d0 | real | yes | Etalon plate separation. |
mu | real | yes | Refractive index of the etalon medium. |
M | real | yes | Atomic weight of emitter. |
lambda0 | real | yes | Wavelength of interest, nm. |
deltaLambda | real | yes |  |
TF | real | yes | Transmission of filter at wavelength of interest |
temperature | real | yes | Temperature of emitting region, deg K |
D | real | yes |  |
Refl | real | yes | Etalon-plate reflectivity. |
a | real | yes |  |
K | integer | yes |  |
time | real | yes | Integration time, sec. |
v | real | yes |  |
y0 | real | yes |  |
T0 | real | yes |  |
Q | real | yes |  |
beta | real | yes |  |
sigma | real | yes |  |
R0 | real | yes |  |
dRdLambda | real | yes | Night sky continuum brightness. |
noiseFactor | real | yes |  |

The capitalized data types in the above table are

Data type | Format | Example | Remarks
Process | tag operationList | Process Z darkSubtract annularIntegrate peakLocate zenithProcess | tag is the user’s choice for image letter. Possible operations are darkStore, darkSubtract, annularIntegrate, peakLocate, zenithProcess,laserProcess and nightGlowProcess.
Centering | centerChoice | LASER | FILE: use the control file imageCtrPx{X,Y} values. LASER: determine the center from the most recent laser image. IMAGE: determine the center from every image, laser or sky.
Peak | start, end | 88, 115 | Symbol_name is peakRange[i] for the ith peak.
Real vector | x 1 x 2 ... | 1.1 2.2 3.3 | Each x i is a real.
Range list | lo[:hi] [*], lo[:hi] [*], ..., lo[:hi] [*] ["suffix"] | −200:200, −500:500*"m/s" | * marks initial default range. If :hi is omitted, the range will be 0–lo. If "suffix" is present, it will appear following the range in menus.

Here is a complete sample control file for Analyze:

//
//     Analyze Control File version 1.85
//   QL parameters

write1D          TRUE          //output 1D interferogram into QL file
nAnnuli          400          // # annuli to use for integration 2-D image to 1-D interferogram
nPeaksExpected    2          // # peaks to be used in the 1-D interferogram (0=unknown how many peaks)

// QL ring center parameters
centerUsing	LASER	// FILE=use the imageCtrPx{X,Y} values  LASER=determine the center from the most recent laser image  IMAGE=determine the center from every image, laser or sky
nBrightnessCats	4	// number of brightness categories altogether
loBrightnessFrac	2e-4	// fraction of pixels in the lowest brightness category
hiBrightnessFrac	2e-4	// fraction of pixels in the highest brightness category
// These fixed values for the image center are used only if centerUsing=FILE
imageCtrPxX      4.     // center of 630 image, units of pixels ->chip width of 256 taken as -128,128
imageCtrPxY      -5.

peakRange[0]    10, 50   //80,  120   // expected start/end position of 630 nm in pixels for peak 0
peakRange[1]    55, 87 //130,  170  // expected start/end position of 630 nm  in pixels for peak 1

peakRangeLaser[0]    50, 85 //8,22      // where to look for the peaks in the laser image
peakRangeLaser[1]    88, 115 //60,76

// Image processing table - determines how images are treated in real time

Process B annularIntegrate
Process K darkStore annularIntegrate
Process D darkStore annularIntegrate

Process L darkSubtract annularIntegrate peakLocate laserProcess
Process Z darkSubtract annularIntegrate peakLocate zenithProcess
//Process Z darkSubtract annularIntegrate

Process N darkSubtract annularIntegrate peakLocate nightGlowProcess
//Process N darkSubtract annularIntegrate

Process T darkSubtract annularIntegrate

vSignAdj     TRUE     // determine whether meteorology sign convention re speed is on (TRUE) or off (FALSE)
vSignTol     0.5

// Fourier model analysis
calcFSR	FALSE	// following value will not be used as FSR
FSR	53.6	// K_sky
nCoef	16	// number of sin/cos coeffs

// Fourier sine coefficients August 22 2010 values

 sin_set -0.03165960 -0.03945079 -0.04308171 -0.04135847 -0.03858673 -0.03428515  -0.02646727 -0.02130226 -0.01600892 -0.01242463 -0.01045229 -0.00508943 -0.00409458 -0.00144390 0.00017935 0.00090690

cos_set 0.86539167  0.63901639  0.45683286  0.31773764  0.21456432  0.13762896  0.08731046 0.05330927 0.02963613  0.01776144 0.00890885 0.00469484 0.00143433 -0.00048763 -0.00042802 -0.00059820

weight TRUE       // applies weighting of the values in accordance with the reciprocal of the variance.
wtZero   1      // governs the choice of the wt function 0 means ignore 0 points, 1 means the wt is 1, 2 means the wt is the half of the minimum of other wts, range=0-4, FALSE for weight means weight is 1

q1   -1.0    // parameters for the sin and cos args
q0   -0.

darkImagesD	TRUE      // if TRUE only D images would be used for background removal; if FALSE then K images for laser

    thickness        1.5          // spacer gap in cm
    indexRefraction  1.000297     // index of refraction for nitrogen within the etalon
    lambdaLaser      632.81644    // laser wavelength in nm
    lambdaSky        630.0030     // nightglow wavelength in nm
    atomicWeight     16           // emitter atomic or molecular weight in g/mol

// QL display parameters

displayFreqX         2   // controls sampling of image for display in X direction
displayFreqY         2
intensScale 1000,3000,10000,20000*,50000,100000, 200000, 300000
velScale -10:10, -20:20, -30:30, -50,50, -100:100, -200:200, -500:500*"m/s"
timeScale 0.5, 1, 2, 3, 5, 6, 12*, 24 "hr"
tempScale        500:900,600:1600*,700:1200// choices for temperature ranges

tempProcess    FALSE    //enable or disable temperature processing using Doppler widths
adaptivePeaks  FALSE    // turns on peak fitting processing

zenith0           1.5       // max |zenith angle| which is considered 0
dirAzTolerance    2.0      // tolerance in Az direction for repeated angles
dirZeTolerance    2.0     // tolerance in Ze for repeated angles

ff0     1.0     // flat-field correction, normalized to center of image
ff1     0.10   //  with 10% boost at edge of image for 120 annul

//   QL noise filtering parameters

// for smoothing dark images via a square/rectangular approach
nZonesX 8        // number of rectangular zones for smoothing
nZonesY 8
smoothDarkPasses         3        // max # of smoothing passes to be made (0=don't smooth)
smoothDarkNStdDev        3.0     // # of std dev for which points are smoothed during integration using the averaging method
smoothDarkAvg   FALSE            // replace all points in each block with the block average after smoothing

// for smoothing other images (laser,zenith,nightglow)
noiseAnnAvg TRUE   // noise via triple Annular averaging filtering rather than spike filtering removal
smoothPasses  3   // number of noise filter passes re comparison of pixel value with mean and std dev.
smoothNStdDev 3  // # of standard deviations for which points are smoothed by replacement with mean

// AnalyzeControlFile.txt: Parameters for the generation and fitting of images

sx	1.24	// detector width, cm
sy	1.24	// detector height, cm
px	1024	// detector width in pixels
py	1024	// detector height in pixels
bx	2	// binning width in pixels
by	2	// binning height in pixels
centerX	0.0	// x at center of image, pixels
centerY	0.0	// y at center of image, pixels
f0	50	// focal length, cm
d0	1.5	// etalon gap, cm
mu	1.0	// index of refraction within etalon gap
M	16	// atomic mass of emitting atom, g/mole
lambda0	630	// wavelength of emitting atom at rest, nm
deltaLambda	0.5	// bandwidth of the interference filter, nm
TF	0.70	// filter transmission
temperature	789	// nightglow temperature, K
D	0.01	// etalon imperfection broadening parameter
Refl	0.77	// reflectivity of the etalon mirrors
a	10	// etalon aperture diameter, cm
K	20	// number channels per ordervelScale

time	100	// integration time, s
v	2000	// relative velocity of the emission source, m/s
y0	0	// reference phase offset
T0	0.075	// system transmission
Q	0.95	// quantum efficiency of the detector, counts/photon
beta	0.0005	// dark count signal, counts/(s pixel)
sigma	4	// readout noise standard deviation, counts/pixel
R0	50.0	// source signal, Rayleighs
dRdLambda	0.075	// continuum background, Rayleighs/nm
noiseFactor	1.0	// multiplies SQRT(signal) for noise variance


Image processing

Analyze displays images as they are opened, and in addition, processes them. Which operations constitute processing is determined by a table in the Analyze control file.

The possible operations are

Operation name | Processing to be done
darkStore | Store this image as a dark image: sky if this image’s tag is D, else laser.¹
darkSubtract | Subtract the stored dark image from this image. Which dark image is subtracted depends on this image’s tag, and the override control file variable darkImagesD. If the tag is L and darkImagesD is false, the laser dark image is subtracted, otherwise the sky dark image.
annularIntegrate | Sum the values in annuli about the image center.
peakLocate | Fit the annular integration with a set of Gaussian peaks.
zenithProcess | This image is processed as a zenith image (details below).
laserProcess | This image is processed as a laser image (details below).
nightGlowProcess | This image is processed as a nightglow image (details below).
1. Two distinct dark images are stored: laser and sky.

Zenith image processing comprises the following steps:

  1. Normally, the steps darkSubtract, annularIntegrate and peakLocate will have already been done, per the table in the Analyze control file.
  2. Do a Fourier fit of this zenith image.
  3. Use the spacing (in annuli) between the first two peaks to get the Doppler shift conversion (dopplerShiftFSR / spacing in annuli).
  4. If this is the first zenith image, save the reference peaks and fitted values for U3 from the Fourier model.
  5. Otherwise, this is not the first zenith image; use that one as a reference.
    1. Calculate the shift in the first zenith peak (red shift if > 0).
    2. Convert the peak shift to velocity using the Doppler shift conversion.
    3. Also get the velocity from the Fourier fit.
  6. Get the intensity as the height of the fitted Gaussian to the first peak.
  7. Also get the intensity from U2 of the Fourier fit.
  8. If we’re processing temperature (control file variable tempProcess)
    1. Convert the Gaussian peak width to temperature.
    2. Also get the temperature from the Fourier fit of the first peak.
  9. Add a point to the quick-look plots and output file.
  10. If the Analyze control file variable write1D is true, write the entire 1-dimensional interferogram (annular integration) into the quick-look output file.

Laser image processing comprises the following steps:

  1. Normally, the steps darkSubtract, annularIntegrate and peakLocate will have already been done, per the table in the Analyze control file.
  2. Use the separation between the Guassian fit of the first two peaks to calculate K, the separation between peaks in units of spectral channels (annuli).
  3. Calculate the number of annuli expected in one order of the 1-D spectrum of a sky image, K sky:
  4. If the Analyze control file variable calcFSR is true, K sky is calculated as K sky = K laser (λ sky / λ laser )². Otherwise, the value from control file variable FSR is used.
  5. Δλlaser is computed as 1/(2*thickness) λ²laser . This will be used to determine the thermally-broadened width, which is used to convert peak width to temperature.
  6. If the Analyze control file variable write1D is true, write the entire 1-dimensional interferogram (annular integration) into the quick-look output file.
  7. Do a Fourier fit of this laser image.
  8. Add a point to the quick-look output file.

Nightglow image processing comprises the following steps:

  1. Normally, the steps darkSubtract, annularIntegrate and peakLocate will have already been done, per the table in the Analyze control file.
  2. Compare the peak positions to those of the zenith image, if we have one
  3. If there is a zenith image available, calculate the red shift of the first peak and use this to get the horizontal velocity. Use the height of the first peak to get intensity.
  4. Do a Fourier fit of this nightglow image.
  5. Get alternate estimates of the horizontal velocity and intensity from the Fourier fit.
  6. If the Analyze control file variable tempProcess is true, use the Gaussian and Fourier best-fit parameters to calculate the temperature.
  7. Add a point to the quick-look plots and output file.
  8. If the Analyze control file variable write1D is true, write the entire 1-dimensional interferogram (annular integration) into the quick-look output file.

Here is a sample table from a control file:

// Image processing table - determines how images are treated in real time

Process B annularIntegrate
Process K darkStore annularIntegrate
Process D darkStore annularIntegrate

Process L darkSubtract annularIntegrate peakLocate laserProcess
Process Z darkSubtract annularIntegrate peakLocate zenithProcess

Process N darkSubtract annularIntegrate peakLocate nightGlowProcess

Process T darkSubtract annularIntegrate


Batch processing images

When an image is loaded into Analyze, either manually from the front panel (File / Open...) or by Master running a script (DISPLAY_IMAGE image), the image data is displayed, and the image is analyzed, converting the 2-D interferogram to 1-D, fitting Gaussian functions to the peaks, and calculating temperature, intensity, and velocity (the “quick look” plots).

During normal data-taking, scripts cause each image to be processed as it is acquired. After a night of data-taking is complete, it is sometimes desirable to process all the images, to get, for example, the velocity as a function of time in each direction. These will be shown on the Analyze screen at the station, but batch processing allows you to re-create this plot by processing all images in a directory (folder) in order.

To batch process images, open the first image. Select Batch process images from the File menu.

After a delay of a few seconds, images in the directory of the loaded image will be processed in chronological order, starting with the loaded image. The date and time used for ordering is the acquisition start date and time from the image header, not the file create date and visible in Windows Explorer.

While images are being processed, you may see some momentary display of images, and Analyze will be unresponsive.

When the processing is complete, a message similar to this will appear. To process all the images in a directory, you have to load the earliest-acquired image before invoking batch processing.


Generating test images

Test images are known geometrical patterns used to demonstrate or test Analyze. To produce a test image, select one of the choices from File.

Here are samples for 256×256 displayed in color. Uncheck menu item Image / Show in color to display as grayscale.


Generating synthetic images

Analyze can generate several types of synthetic images. These are intended to look like actual laser or sky images, and have a large number of user-specified parameters. Analyze can also generate test images.

Two types of synthetic image are currently implemented: Analytical and Forward.

Choosing Generate image in the File menu brings up the image generation parameter window. The parameters input by the user are shown in white boxes. Those calculated from the user-input parameters are in yellow. The mouse positioned on any parameter gives its definition, and the formula used to evaluate it, if it is calculated .

When the box Output file is checked, generating an image will produce AdaptIntegrate.txt in the same directory as the log file (default is the directory of the executable, Analyze.exe). The filename cannot be changed, but if Master is running, a LOG_DIRECTORY in the script can be used to change the directory. Subsequently-generated images’ AdaptIntegrate.txts will be created in the new directory. Each AdaptIntegrate.txt silently overwrites the previous one in the same directory.

The start of this file contains all the parameters used to generate the image. Here is a sample from the file, with the control file parameter maxLinesPerChannel set to 10:

lambda0=  6.3003030000000001E+02  T_F_lambda0=  5.9999999999999998E-01  maxOrders=100
Refl=  7.7000000000000002E-01  D=  1.0000000000000000E-02  rR=  1.2994350282485875E-01
R0=  5.0000000000000000E+01  delta_lambda_T=  2.1424619281326402E-03  dRdLambda0=  5.0000000000000000E+00
mu=  1.0000000000000000E+00  deltaLambda0=  1.3231272630603001E-02  lambdaR=  6.3003030000000001E+02
f0=  3.1000000000000000E+01  rFSR=  2.0090779283044249E-01  K=40  loLimit=  6.2963030000000003E+02  hiLimit=  6.3043029999999999E+02
Coi=  2.3504170423975310E+02  Bi=  2.8140000000000001E+01
thickness=  1.5000000000000000E+00  finesse=  7.5657086710881849E+00  halfPhaseDiffCoeff=  9.4247705384007454E+07

This file: c:\A3O\Analyze\AdaptIntegrate.txt
Maximum lines shown per channel = 10

Solar intensity from file c:\A3O\Analyze\630nmSolarContBack.txt

Channel 1 yi=  2.5000000000000001E-02 theta_i=  1.2550202189606349E-03
Integrand for 2 values
               lambda(i)            T_F(lambda(i))            Psi(lambda(i))               Y(lambda(i))                Integrand
   629.6303000000000        0.4672804698428561        0.9394157351634805         5.167574361123672         2.268413352746414
   630.4303000000000        0.4672804698428561        0.1168061472615386         5.041369920401889        0.2751641780618622
   629.6531470337219        0.4804258234207179        0.2180774906874685         4.919294939340282        0.5153948162763754
   629.7037013557434        0.5078890287733752        0.1240977060538544         5.166792406115799        0.3256518859924196
   629.7735586630617        0.5412794705816933        0.4487806447086490         4.018731963526214        0.9762132880655664
   629.8514145639419        0.5707376553838110        0.2158297875561872         5.091746430244712        0.6272124604779165
   629.9357467201352        0.5916767178103085        0.4461388063212633         5.046990783764784         1.332253877647533
   630.0303000000000        0.6000000000000000        0.1820776258736357         285.5486983139837         31.19521743619031
   630.1248532798649        0.5916767178103085        0.1226256126844776         5.042067446911437        0.3658257919962961
   630.2091854360581        0.5707376553838110        0.2700433406866754         5.110085074953274        0.7875862570041878

N(1)=  1.2677120246293803E+03 Integral=  5.2738386519056251E+00

Channel 2 yi=  5.0000000000000003E-02 theta_i=  1.6202241357293750E-03
Integrand for 2 values
               lambda(i)            T_F(lambda(i))            Psi(lambda(i))               Y(lambda(i))                Integrand
   629.6303000000000        0.4672804698428561        0.8202084173747761         5.167574361123672         1.980562658644591
The Analyze control file parameter maxLinesPerChannel limits the number of integration step lines for each channel in the integrator output file. The purpose of this parameter is to avoid creating huge output files (~2 GB). To see every step of the numeric integrator, set maxLinesPerChannel to a large value (e g, 99999). To see only the parameters and result for each channel , set maxLinesPerChannel to zero.

An Analytical image calculates the number of counts in channel i, N i, using

[TO DO]

A Forward image calculates the number of counts in channel i, N i, using (L is the user-chosen limit of integration)

Those parameters derived from the user-input parameters are calculated by

    rmax = ½ min(s x, s y)
m = M / N Av
Δλ 0 = 10−7 λ 0² / (2μd 0)
G = π / c √(2kT / (10−3

 m)) (λ 0 / Δλ 0)
n = r²max d 0 / (10−7 λ 0 f 0²)
N ChannelsTotal = nK
M 0 = int(2 μd 0 / (10−7 λ 0))
y phase = y 0+M 0 v / c
r FSR = f0 √(10−7
 λ 0 / d 0)
A FSR = π r ²FSR
Ω = A FSR  / (f 0²K)
C oi = a² / 16 Ω t T 0 Q 106
A i = A FSR / K
A Ni = roundToInt((A i / (s x s y))((p x / b x)(p y / b y)))
B i = β t A Ni
Δλ T = √(2kT / (10−3 m)) (λ 0/c)


Operation

Analyze may be used stand-alone, or in conjunction with Master. When used stand-alone, the user has the ability to change various parameters interactively, and perform many operations not available from Master’s script.

Load an image from File / Open..., or the recent file list. Seven windows will appear, and defaults will be used for all parameters. The windows may not all be visible initially. You can move, close, maximize or minimize each window, or use Window / Cascade and Window / Tile to rearrange all the windows.

The windows are

  • Image: Displays the image pixels.
  • Image information: When the image was acquired, its charactistics, and conditions.
  • Annular integration: The 1-dimensional interferogram obtained by summing pixels in concentric rings.
  • Quick-look plots: Temperature, intensity, and velocity from multiple images in each direction.
  • Vertical cross-section: Pixel values along a vertical axis through the center of the image.
  • Horizontal cross-section: Pixel values along a horizontal axis through the center of the image.
  • Image header detail: Everything in the image header.

This is the toolbar at the top of the main Analyze window:

The purpose of each toolbar button:

The usual Windows file open dialog. Use this to select an image file to be displayed and analyzed.
Change the image scaling by powers of 2. This exists for historical reasons, and is not normally used.
Toggle between linear and log plot of image. The button shows the plot which will appear if you click it.
Set the minimum and maximum for the image plot (edit boxes) and replot (Plot). A color stripe to the right of the image shows pixel intensity vs display color.
Display details of the annular integration, and allow changing some integration parameters.
Subtract the bias image (only enabled when a bias image has been loaded).
Close this image, and move to the previous or next image in the same directory
Initialize the quick-look plots


Image display

Images are plotted in this window, with one screen pixel per image pixel. Although the window itself can be resized, the plot of the image remains unchanged.

The image pixels range from 0 to 216−1, and pixel intensity is converted to display color according to the user’s settings.

Here is a sample image, shown in color, linear, and the default scaling (determined by the range of values in the image). The corresponding image information window is at the right.

A portion of the same image in black-and-white:

The color stripe to the right of the image shows the maximum signal of 477 as white, and the minimum of 448 as black.

The green cross-hairs near the middle show the position of the image center, either as specified in the file, or determined automatically from the image (which way is shown in the status bar at the bottom of the window).

Menu items under Image allow you to turn off the grid or axes, as well as choosing color or monochrome intensity plot.

Another option in the image menu produces a reduced display: every 2nd, 3rd or 4th point, or even no plot. The purpose of these options is to lessen the amount of data required to paint the screen when operating with a remote desktop over a slow internet connection. This option does not affect any calculations on the image, only the display of the plot on the screen.

As an aid to determining the center manually, you can overlay and position a circle. The initial center of the circle is set by a mouse click in the image, and the initial radius is 10. Subsequent left mouse clicks add 10 to the radius, and right mouse clicks subtract 1. The center can be repositioned by using [image] , which move the circle 1 pixel at a time in the indicated direction. The 0 removes the circle, so you can start over. Note: For the circle to be visible, you must have Image / Show central circle checked. The position and radius are shown in the status bar at the bottom of the main window.

The central part of the above image, with a circle centered at the green cross-hairs (coincidentally—it can be centered anywhere). The status bar below shows its exact position and radius.

Other useful information on the status bar includes [image] the coordinates and intensity at the mouse cursor; image statistics [image] ; and centering data [image].

The last, centering data, shows first the center of symmetry of this image found by Analyze, then the center that will be used for this image, and how that center was found. In this example, the center which will be used for the annular integration came from image L...027. The control file specifies which of

  • the automatic center for the current image
  • the automatic center from the most recent laser image
  • a fixed value from the control file
will be used for the annular integration.


Image information window

The image information window is displayed when an image is loaded. It shows the most important values stored in the image header. To see all the values in the header, look at the image header detail window.

The name of the image file is at the top.

Acq start is the time at which image acquisition began. Acquisition is triggered by the script command TAKE_IMAGE.

Copy start is the time at which image readout from the camera began; data are transferred from the (typically CCD) camera's registers to the computer's memory. Image readout is triggered by the script command COPY_IMAGE.

az and ze are the azimuth and zenith angles reported by Observatory at the time the image was acquired.

T is the camera detector's temperature at the time the image was acquired.

Digital inputs are the values of the digital input lines monitored by Observatory. The meaning of these depends on the connections of the hardware.

Tag is the single character specified in the script's TAKE_IMAGE.

Exp rq / act are the requested and actual exposure times. Requested exposure time is set by the script's SET_PARAMETER CAMERA unitname, ExposureTime = value, with the default in Camera's control file. Actual exposure time is the camera's best choice for the requested exposure (usually these are the same).

The next line shows the image size and binning. These are controlled by the Camera parameters FullImageCol0, FullImageCol1, FullImageRow0, FullImageRow1, HorizonBin and VerticalBin. These are all settable using the script command SET_PARAMETER CAMERA. Defaults for these are in Camera's control file.

total image size is the number of image bytes stored in the disk file (each image pixel is two bytes). The image files also contain a header.

Etalon temperature and Etalon pressure come from the values of analog input lines monitored by Observatory.

Which lines and the analog input parameters are determined by the Observatory control file variables AInChan_X, AInChan_X, AInType_X, AInRangeMin_X, AInRangeMax_X, and the conversion from analog voltage to user units are controlled by AInConvA_X, AInConvB_X (X = Press or Temp).

If any auxiliary digital inputs are in use


Quick-look plots

The so-called quick-look plots show a summary of the data gathered in one session. Successive images displayed by Analyze (usually as a result of the Master script command DISPLAY_IMAGE) are used to plot wind velocity, intensity and temperature for each direction of observation.

The processing of the images for this display is governed by a number of Analyze control file variables, listed under Image processing parameters, Annular integration parameters, and Fourier analysis parameters. The display of the resulting graphs is controlled by Analyze control file variables in the section “Quick‑look” parameters.

The Analyze control file provides defaults for parameters, but some of these can be overridden from the Quick-look menu.

In this example, the possible scales for velocity (plotted on the y-axis) are shown. The choices in this menu come from the control file variables timeScale, velScale, intensScale and tempScale in the section “Quick‑look” parameters.

Here is an example of the quick-look plots generated from 474 images (one nights' worth), showing both the Gaussian and Fourier fits. The y-axis scales are v ±500 m/s, I 200,000, T 600–1600 K; x-axis is 12 hr. Expand the help window to magnify.

Each direction is a separate plot. Above the plots are buttons enabling results from the two different fits (Fourier and Gaussian peak modeling), and the origin of the time scale used for all plots (the scaling for time is a menu item, as shown above). Also, whether the meteorology sign convention for velocity is being used, and, if so, angle (in degrees) away from a cardinal angle to be considered a cardinal direction (Analyze control file variables vSignAdj and vSignTol).

The points are plotted as

Peak model | Velocity | Intensity | Temperature
Fourier fit | Black open square | Red solid square | Green solid square
Gaussian fit | Black solid dot | Red solid dot | Green solid dot
In order for these points to be displayed, the corresponding button (Fourier fit or Gaussian fit) must be depressed, and the specified quantity must be enabled in the Quick-look menu.

Here is the first directional plot from the example above, showing just the Fourier fit points (left), and just the Gaussian fit. Scaling is the same as above.


Log (quick-look output)

Produced by Analyze v1.89  9/12/12
Initial image    Analysis done at 2012-10-7 19:50:25 UTC
          Image file Type Dir      Az      Ze       tAbs, nsec/100  tRel, hr          v          I          T Peak#         Mean      Std dev     Baseline    Amplitude           U1           U2           U3           U4  v (Fourier)  T (Fourier) Conv
    D20100211001.img    D                       129102995518960000    0.0000 Gaussian
                                                                     Fourier
    K20100211001.img    K                       129102993565820000   -0.0271 Gaussian
                                                                     Fourier
    D20100211001.img    D                       129102995518960000    0.0000 Gaussian
                                                                     Fourier                                    0 0.000000e+000
   1 2.181912e+002
   2 3.625818e+002
...
 199 0.000000e+000
 200 0.000000e+000

    L20100211001.img    L                       129102997596460000    0.0289 Gaussian
                                                                     Fourier                                      1      37.7047       2.1401     377.1203    4202.4111    -252.7137     810.4988      17.9296       0.0000      -0.0000       0.0000 1
                                                                                2     114.2391       2.1620     163.4902    3070.7124    -434.4827     645.6487      14.5436       0.0278      -0.0000       6.7223 1
    X20100211001.img    Z   1    5.21    0.49   129102999706760000    0.0582 Gaussian          0   5.5e+003
                                                                     Fourier          0   2.4e+003                1      78.1322       5.6532     163.3811    5461.8340   -1213.0371    2378.1178      18.2209       0.2714      -0.0000     640.2384 1
                                                                                2     154.1395       5.4082     141.4714    4643.6281   -1102.9301    2005.0618      14.1483       0.2635      -0.0000     603.4841 1   0 0.000000e+000
   1 6.634407e+003
   2 6.740406e+003
...
 199 0.000000e+000
 200 0.000000e+000

    X20100211002.img    N   2   89.59   20.97   129103001760520000    0.0867 Gaussian         85   3.1e+003
                                                                     Fourier   4.5e+002   6.1e+002                1      77.8873       4.4654     -51.1725    3131.1086    -373.5277     605.5647      16.9280       0.0918     450.0307      73.1838 1
                                                                                2     153.9848       4.2954     -53.3225    2318.7112    -256.4838     398.2792      13.7594       0.0637     135.3531      35.2384 1   0 0.000000e+000
   1 4.046002e+003
   2 3.967308e+003
...
 199 0.000000e+000
 200 0.000000e+000

    X20100211003.img    N   3   74.09   33.17   129103003756760000    0.1144 Gaussian         74   1.8e+003
                                                                     Fourier   2.5e+002   1.8e+002                1      77.8062       3.7164     -32.9877    1840.2554    -117.8195     177.8818      17.1225       0.0000     250.0005       0.0000 1
                                                                                2     153.8862       3.2690     -19.1274    1187.6505     -51.3121      72.1599      14.0006       0.0000      33.6107       0.0000 1   0 0.000000e+000
   1 2.669106e+003
   2 2.626458e+003
...
 199 0.000000e+000
 200 0.000000e+000

    X20100211004.img    N   4   89.99   41.40   129103005749580000    0.1421 Gaussian         89   1.1e+003
                                                                     Fourier         77         62                1      77.6615       2.9938     -10.9221    1117.2862     -43.5197      62.1177      17.8133      -0.0000      76.7635       0.0000 1
                                                                                2     153.6200       2.6425      -6.7007     523.9148     -16.0088      20.7047      13.2956       0.0000     160.5945       0.0000 1


Annular integration window

TO DO


Image header detail window

TO DO


Cross-section windows

TO DO


Analyze Known Bugs

TO DO


Changes in Analyze v2.03 2014-3-7

  1. This version of Analyze must be used with updated versions of the other processes: Master v1.02, Camera v1.27, Observatory v1.55, and Communicate v0.07, or later.

  2. The Master script function ImageProperties(x0, y0, xSize, ySize, xBin, yBin, nBuckets, buck0, buck1, &count, &min, &max, &avg) has changed to allow computation of a histogram, as well as the statistics, of an image displayed by Analyze. Details.


Changes in Analyze v2.02 2013-12-16

  1. This version of Analyze must be used with updated versions of the other processes: Master v1.01, Camera v1.27, Observatory v1.55, and Communicate v0.07, or later.

  2. There are no functional changes from v2.01.


Changes in Analyze v2.01 2013-12-6

  1. This version of Analyze must be used with updated versions of the other processes: Master v1.00, Camera v1.23, Observatory v1.48, and Communicate v0.06, or later.

  2. This version supports changes in the image files produced by Camera.


Changes in Analyze v2.00 2013-10-1

  1. This version of Analyze must be used with updated versions of the other processes: Master v1.00, Camera v1.23, Observatory v1.48, and Communicate v0.06, or later.

  2. Control file lines which contain only blanks and tabs are now ignored. Previously, such lines caused spurious errors.


Changes in Analyze v1.99 2013-9-24

  1. This version of Analyze must be used with updated versions of the other processes: Master v0.99, Camera v1.22, Observatory v1.47, and Communicate v0.05, or later.

  2. There are no changes in functionality from v1.98.


Changes in Analyze v1.98 2013-9-2

  1. This version of Analyze must be used with updated versions of the other processes: Master v0.98, Camera v1.21, Observatory v1.46, and Communicate v0.03, or later.

  2. Generate image has an option Output file. When this box is checked, generating an image will produce AdaptIntegrate.txt in the same directory as the log file (default is the directory of the executable, Analyze.exe).

    The start of this file contains all the parameters used to generate the image (see Generating synthetic images).

  3. The Analyze control file now requires one additional parameter:
    maxLinesPerChannel	10	// limit the number of lines in the integrator output file
    The purpose of this parameter is to avoid creating huge output files (~2 GB). There is a line of output produced for each integration step, but most of this is only useful for checking the numeric integrator.


Changes in Analyze v1.97 2013-8-15

  1. This version of Analyze must be used with updated versions of the other processes: Master v0.98, Camera v1.21, Observatory v1.46, and Communicate v0.03, or later.

  2. The forward model for generation of synthetic images has been revised to

    1. Include a Gaussian filter function.
    2. Have the option to use a solar background. To do so, a file named 630nmSolarContBack.txt must be in the same directory as the Analyze control file. The contents of this file must be (wavelength in Å, relative intensity). For example,
      6295		9872
6295.002	9872
6295.004	9871
6295.006	9870
6295.008	9870
      Future versions of Analyzewill allow user choice of different solar intensity files, and other file formats.

    3. Run faster, and show image progress (progress bar at the bottom of the image parameters window).

    The equations used are in Generating synthetic images.

  3. The Analyze control file now requires another two additional parameters:
    lambdaF	630.0303	// center wavelength of filter, nm
deltaTFilter	0.8		// full width at half maximum of filter, nm


Changes in Analyze v1.96 2013-7-15

  1. This version of Analyze must be used with updated versions of the other processes: Master v0.98, Camera v1.21, Observatory v1.46, and Communicate v0.03, or later.

  2. In the Image parameters window the tooltip for variable, ΔλT was shown incorrectly. This has been fixed. which defines it, and, if it is calculated from other parameters (yellow box), shows the formula used.

  3. Synthetic image generation in Analyze now has choice of a forward model, which uses numerical integration. See Generating synthetic images for details.

  4. The Analyze control file now requires two additional parameters:
    modelType          forward    // "analytical", "Fourier" or "forward"
integrationWidth   0.4        // forward model integrates lambda0 ± integrationWidth nm


Changes in Analyze v1.95 2013-6-5

  1. This version of Analyze must be used with updated versions of the other processes: Master v0.98, Camera v1.21, Observatory v1.46, and Communicate v0.03, or later.

  2. For annular integration, the limits on the number of annuli (rings) has been changed:

    Previously: 2 < rings ≤ minimum(ny/4, 512)
    Now: 2 < rings ≤ minimum(ny/2, 512)

    ny is the y-dimension of the image, in pixels.

  3. Image generation now uses numeric integration over λ to compute the filter transmission function, T F(λ), instrument transfer function, Ψ(λ) , and the spectral distribution of the source, Y(λ). The limits of integration are currently fixed at λ0 ± 4 nm.

  4. A new control variable, ΔλT, is shown in the Image parameters window. This value is used in calculating Y(λ).

  5. A new checkbox Output file is available in the Image parameters window. If this box is checked, generating an image using numerical integration will produce an output file AdaptIntegrate.txt containing λ, T F(λ), Ψ(λ) , Y(λ) and the integrand T F(λ) Ψ(λ) Y(λ).

  6. Each of the variables in the Image parameters window now has a tooltip which defines it, and, if it is calculated from other parameters (yellow box), shows the formula used.

  7. For generated images, often the color scaling for the image display will not be useful, because the (usually) circular image is surrounded by 0 or noise pixels. Therefore, the scaling will use 0 or noise as the minimum. You must set the minimum and maximum intensities for plotting (toolbar at the top) manually.


Changes in Analyze v1.94 2013-4-9

  1. This version of Analyze must be used with updated versions of the other processes: Master v0.98, Camera v1.21, Observatory v1.46, and Communicate v0.03, or later.

  2. Note: There is no change log for Analyze v1.93, which was an intermediate release.

  3. Analyze is now is able to generate or process images up to 4096 × 4096 pixels.

  4. The Generate image window now has a box for the image type tag, with a default of N (nightglow). The processing of the various image types is specified in the Analyze control file.

  5. Generated images are now processed in the same way as loaded images, so all the windows (image, cross-sections, headers, annular integration and quick-look) will be filled in. The processing depends on the image type tag.

  6. A number of bugs connected with image generation have been fixed. These generally occurred when intermixing generating, saving and loading.

  7. The Prev and Next image arrows did not work correctly for images in an “unexpected” directory. This has been fixed.


Changes in Analyze v1.92 2013-4-5

  1. This version of Analyze must be used with updated versions of the other processes: Master v0.98, Camera v1.21, Observatory v1.46, and Communicate v0.03, or later.

  2. In the Image header detail window, the horizontal binning was incorrectly shown as 0 (the correct value appeared in the Image information window). The Image header detail display has been corrected.

  3. Large images (either dimension > 2048) gave an error message “BAD IMAGE error code 5”, even if they were binned so the image was reduced below 2048. For example 2160 × 2160 binned 6 × 6 has 360 × 360 pixels, yet because the camera image was originally 2160 > 2048, this error occurred. The check has been corrected to take account of the binning.


Changes in Analyze v1.91 2013-2-20

  1. This version of Analyze must be used with updated versions of the other processes: Master v0.98, Camera v1.21, Observatory v1.46, and Communicate v0.03, or later.

  2. There are no changes in functionality from v1.90.

  3. The version number which showed at the top of the main window for Analyze was wrong for previous releases of Analyze, v1.88–1.90. These all incorrectly displayed v1.87.


Changes in Analyze v1.90 2012-11-8

  1. This version of Analyze must be used with updated versions of the other processes: Master v0.96, Camera v1.20, Observatory v1.45 and Communicate v0.01, or later.

  2. There are no changes in functionality from v1.89.


Changes in Analyze v1.89 2012-9-12

  1. This version of Analyze must be used with updated versions of the other processes: Master v0.94, Camera v1.19 and Observatory v1.44, or later.

  2. The Next image and Previous image buttons now allow different formats of image names. The next/previous image is the one that is next/previous in collating order, where non-digits are held constant. If there is no next/previous image, there is a warning message and the display will not change.


Changes in Analyze v1.88 2012-9-5

  1. This version of Analyze must be used with updated versions of the other processes: Master v0.94, Camera v1.19 and Observatory v1.44, or later.

  2. The Analyze log file (“quick-look” file) was not working, causing Analyze to crash when the first image was opened. This has been fixed.

  3. The log file may be named more flexibly than the default by means of the script command LOG_DIRECTORY.


Changes in Analyze v1.87 2012-8-24

  1. This version of Analyze must be used with updated versions of the other processes: Master v0.93, Camera v1.18 and Observatory v1.43, or later.

  2. The Analyze log file (the “quick-look” output) can now be named more flexibly. See LOG_DIRECTORY for details.

  3. Image generation now works again. It shows a choice for the image model (Analytical, Fourier or Forward), but this is not yet implemented; only the analytical model is available.


Changes in Analyze v1.86 2012-4-18

  1. Analyze has been rebuilt to be compatible with Master v0.91.


Changes in Analyze v1.85 2011-12-29

  1. Online help has been added to A3O (this is it). At the moment, this is barely started, but should get filled out in future. An updated copy of the help files will ship with each new release of any of the programs.

  2. When a bias image is in use, and the actual image has a pixel that is less than the corresponding bias pixel, Analyze could crash. This has been fixed.

  3. An automatic center-finding algorithm has been added. The control file has new optional variables that control it: centerUsing, nBrightnessCats, loBrightnessFrac, hiBrightnessFrac. You can try it without changing the control file, as defaults will be used. See Image display, near the end.

  4. Image generation has been temporarily removed from Analyze. Using the File / Generate image will give an all-black image.


Analyze Changes v0.60–v1.84

Analyze v0.60 2003-8-5
Analyze v0.62 2003-9-2
Analyze v0.69 2003-10-7
Analyze v0.96 2006-2-26
Analyze v0.97 2006-2-27
Analyze v0.98 2006-3-3
Analyze v0.99 2006-3-16
Analyze v1.00 2006-3-18
Analyze v1.01 2006-3-18
Analyze v1.03 2006-4-22
Analyze v1.04 2006-5-3
Analyze v1.05 2006-5-4
Analyze v1.06 2006-5-5
Analyze v1.08 2006-5-10
Analyze v1.09 2006-6-6
 Analyze v1.10 2006-6-17
Analyze v1.11 2006-7-2
Analyze v1.12 2006-7-12
Analyze v1.14 2006-7-31
Analyze v1.15 2006-8-8
Analyze v1.17 2006-11-25
Analyze v1.19 2006-12-16
Analyze v1.20 2006-12-18
Analyze v1.21 2006-12-20
Analyze v1.22 2006-12-30
Analyze v1.23 2007-1-3
Analyze v1.24 2007-1-10
Analyze v1.25 2007-1-14
Analyze v1.26 2007-1-30
Analyze v1.29 2007-3-8
 Analyze v1.30 2007-3-9
Analyze v1.31 2007-5-16
Analyze v1.32 2007-6-15
Analyze v1.33 2007-7-4
Analyze v1.34 2007-7-6
Analyze v1.35 2007-7-14
Analyze v1.36 2007-9-24
Analyze v1.37 2007-10-1
Analyze v1.38 2007-10-15
Analyze v1.39 2007-11-6
Analyze v1.40 2007-11-10
Analyze v1.41 2007-11-29
Analyze v1.43 2012-12-22
Analyze v1.44 2008-1-22
Analyze v1.45 2008-2-3
 Analyze v1.46 2008-2-20
Analyze v1.47 2008-12-23
Analyze v1.48 2009-1-9
Analyze v1.49 2009-1-10
Analyze v1.50 2009-2-9
Analyze v1.51 2009-2-18
Analyze v1.52 2009-3-5
Analyze v1.53 2009-3-6
Analyze v1.55 2009-5-1
Analyze v1.56 2009-6-9
Analyze v1.57 2009-6-10
Analyze v1.58 2009-6-13
Analyze v1.59 2009-6-13
Analyze v1.60 2009-6-13
Analyze v1.61 2009-6-16
 Analyze v1.62 2009-6-20
Analyze v1.63 2009-6-24
Analyze v1.64 2009-7-6
Analyze v1.65 2009-7-10
Analyze v1.66 2009-7-14
Analyze v1.67 2009-7-17
Analyze v1.68 2009-7-19
Analyze v1.69 2009-7-22
Analyze v1.70 2009-7-29
Analyze v1.71 2009-8-6
Analyze v1.72 2009-8-10
Analyze v1.73 2009-8-11
Analyze v1.74 2009-9-16
Analyze v1.75 2009-10-4
Analyze v1.76 2010-2-13
 Analyze v1.77 2010-3-13
Analyze v1.78 2010-3-15
Analyze v1.79 2010-3-24
Analyze v1.80 2010-6-2
Analyze v1.81 2010-8-23
Analyze v1.83 2011-1-28
Analyze v1.84 2011-3-25

Analyze v0.60 2003-8-5

This is an updated version of Analyze (formerly DataPlot). It has the following changes:

  1. There is the same delay mechanism for starting as in Camera and Observatory, so you can add it to the batch file without getting an error message and going into standalone mode.

  2. 1024 x 1024 images are now displayed correctly (before you got only the upper left quadrant). The images are likely to be larger than the screen, and therefore must be scrolled to be viewed.

  3. The default is to display in color. This can be changed from the View menu. We may want to change the color scheme.

  4. The azimuth and zenith are displayed to a single decimal place.

  5. The cross-sectional plots are scaled to the max of the actual data. I left the min at 0, not knowing whether that was what you wanted, or whether you wanted to show only the top portion. Let me know if you want this changed.

  6. I labeled the min and max on the sectional plots.

  7. The cursor now appears as cross-hairs, and when you are in the main plot, the pixel coordinates and pixel value are shown in the status line at the bottom. The pixel coordinates are relative to the center of the plot.

  8. When you open an image file from the menu, the files listed are of type .img only (you can look at all files by changing the filename filter). There seems to be a problem with this not returning to the previous directory, which I will fix later.

Analyze v0.62 2003-9-2

This version of Analyze has the maximum and minimum pixel value adjustments working. The directory is displayed in the title bar.

  • Click the "log" button to toggle between a linear and log color scale.
  • Click the "plot" button or press ENTER to replot the screen using the new minimum and maximum.
  • Minimum and maximum are the pixel values (before scaling) that will correspond to the ends of the color scale. Pixels which are outside this range will be black or white.
  • At the bottom of the color stripe, the values displayed for a and b are the conversions used for pixel value to color value. These are just there to help understand the color conversion. For linear, v = p*2^scale scale=0, -1, ... , -15 log, v = log2(p*2^scale) = log2(p) + scale B/W: gray scale = a * v + b, limited to 0-65535 (previously was 0-255). The screen will only display 256 different shades of gray, though. Color: a * p*2^scale + b, limited to 0-65535. The color scale is an arbitrary table ranging from black to white.

Analyze v0.69 2003-10-7

This should correct the "slicing" of the display. You may want a different orientation.

Analyze v0.96 2006-2-26

This version of Analyze adds the ability to generate an image from the white paper eq (9).

Select the file menu option "Generate image". A "Generate image parameters" window will appear, with default values for all the parameters (you may want some of these changed; the next version will allow you to save your preferred set). Change whichever you like, then click "Generate". The generated image will appear.

Notes:

  • Some of the user interface features are incomplete.
    a) There is a green tinge on some of the legends
    b) The center is always (0,0).
    c) There is no error-checking of the parameters you enter. Some values will cause crashes (e g, large values for Coi).
    2) The image is only generated to the a maximum radius equal to the half-side of the square, plus a little, so the corners will appear black (zero).

  • The values for Coi and Bi are constant (i e, independent of i).

  • You can move the "Generate image parameters" window around by grabbing its title bar with the mouse.

  • The plot parameters can be adjusted as for any other image.

    Analyze v0.97 2006-2-27

    Some user interface changes:

    1. A_FSR is now calculated from values you enter for lambda, f0 and d0. Units for these are nm, cm, cm and A_FSR is cm2.
    2. Pressing the Enter key after entering parameters is the same as clicking Generate. Enter replots when the focus is in the main window.
    3. The scrolling operation now works correctly for 1024 x 1024. In the previous version, you could not scroll all the way down after generating an image.

    Analyze v0.98 2006-3-3

    This version arbitrarily uses 100 terms for n, and fixes NAi at 20. The value for A_FSR, and therefore the values for d0, f0 and lambda, are ignored.

    Analyze v0.99 2006-3-16

    This version should be complete according to the WP eqn 9. It includes sinc, exp of D and G, and cos terms.

    Analyze v1.00 2006-3-18

    This version has the velocity-dependent part of the phase corrected. It is now

    yPhase=y0+M0*v/cLight
    and for each channel i
    yi=i/NAi
    arg of cos for order n is 2*pi*n*(yPhase+yi)

    Analyze v1.01 2006-3-18

    This version has the sign of the channel-dependent part of the phase phase reversed. It is now

    yPhase=y0+M0*v/cLight
    and for each channel i
    yi=i/NAi
    arg of cos for order n is 2*pi*n*(yPhase-yi)

    Analyze v1.03 2006-4-22

    The only known change in this version is that it doesn't crash when noisy images are displayed.

    Analyze v1.04 2006-5-3

    1. The Image generation dialog window is now 900 pixels high, so it will fit on your MacBook screen. You can use the larger window in v1.03 by using Enter to start generation, rather than clicking the Generate button. You can also drag the image generation dialog up a few mm to bring the Generate button onto the screen.
    2. I have removed the ASSERT; this was caused by a condition under which the center finding will not work. Now at least it will not "crash".

    Analyze v1.05 2006-5-4

    The image generation has been restored. A change made to accomodate the fitting accidentally disabled it.

    Analyze v1.06 2006-5-5

    1. You are now required to have a control file for Analyze; I have attached a sample, containing the defaults that were previously written into Analyze. These are used for the starting values for image generation (those that appear on the screen when you select Generate image from the menu).
    2. The pixel values shown on the screen for generated images are now N[i]/(number of pixels in annulus i), rather than N[i]. You probably want to change some of the default parameters to account for this.
    3. Poissonian noise is added to the signal (noiseFactor in the control file specifies the default amount). You can change the noise factor from the generation parameters window. The noise added to a pixel s is SQRT(s)*noiseFactor*RandomGaussian, where RandomGaussian is normally distributed with mean 0 and variance 1.

    Two hints for using the image generation:

    • Initiate generation by typping Enter after setting the desired parameters. This is the same as clicking Generate if the Image parameters window has the focus.
    • You can move the Image parameters window by dragging it, or hide it by clicking the upper right X, without altering any of the parameters.

    Analyze v1.08 2006-5-10

    1. The display of y in the Image parameters window now tracks y0, etc.

    2. The noise cannot reduce the signal to less than 0 (i e, numbers like 2^16-10).

    3. The maximum number of annuli has been increased from 200 to 500, and you will get a warning if the number is exceeded, rather than a crash. The MiniMe parameters you gave me specified 281 channels for K=20.

    Analyze v1.09 2006-6-6

    This version is compatible with Master 0.52 et al. This version of Analyze has the same center-finding algorithm as v1.08; it has not been fixed, although it has been changed slightly.

    1. The automatically-found center is now shown by green crosshairs.

    2. The noise cannot reduce the signal to less than 0 (i e, numbers like 2^16-10).

    3. The maximum number of annuli has been increased from 200 to 500, and you will get a warning if the number is exceeded, rather than a crash. The MiniMe parameters you gave me specified 281 channels for K=20.

    Analyze v1.10 2006-6-17

    This version will not hang on the image you sent, X20060615002. There was an error if a ring was cut off at the edge of the image.

    It does not find the correct center.

    Analyze v1.11 2006-7-2

    This version of Analyze displays SBIG images.

    1. There is a button labeled "Hdr". This toggles a display of the entire image header; it is for debugging. You will probably never need to use it.

    2. The SBIG images are not being rotated at present. That means (I think) that the image's x-axis runs vertically on the screen. If necessary, I will fix this later.

    Analyze v1.12 2006-7-12

    The only change in Analyze is to avoid the "possibly incompatible" message.

    Analyze v1.14 2006-7-31

    1. The automatic center-finding algorithm has been removed from this version; this will probably fix your crashes when observing SBIG images.

    2. The entire SBIG image should now show on the screen.

    Analyze v1.15 2006-8-8

    This update of Analyze that writes the annular integration to a text file.

    There is a new button on the integration dialog, "Write table to file". Clicking on this will write a table consisting of the first ("i") and last ("Normalized sum") columns of the table displayed on the screen. For example,

           1    25841.2
       2    28344.0
       3    36039.5
       4    51598.4
       5    46443.2
       6    44182.8
       7    43112.9
...

    The output will appear in a file _1D.txt, where is the name of the image. The output file will be in the same directory as the image file. For instance, if the image file is C:\Images\L20060504001.img, then the 1-D interferogram (annular integration) will be C:\Images\L20060504001_1D.txt.

    At present there is no header information in that file, and each click of the "Write" button will overwrite any previous file without warning.

    Analyze v1.17 2006-11-25

    This version of Analyze integrates each incoming image, using the integration parameters in AnalyzeControlFile.txt. It shows the 1-D interferogram in black, and the fitted Gaussian in red. The parameters of the Gaussian are shown at the upper left. The Gaussian used is

    Emacs!

    You should try Analyze with some images, and check that the annular ring element shifts are reasonable. Then we can discuss how to specify and input the conversion factors to wind velocity. I didn't understand your explanation of the relation between direction and peak shift; maybe I misunderstood.

    For the images you sent, I get (subtracting the dark image D20061106003)

    X20061106030 35.064 (zenith image)
    31 35.607

    This version of Analyze also looks for tags on the images, to tell it which type. I haven't sent you the new versions of Master and Camera that do this, so the image type is determined from the filename initial letter and the zenith angle.

    New lines that you will need in the control file are

    zenith0 0.5 // max |zenith angle| which is considered 0
    imageCtrPxX -3.0 // center of image, units of pixels
    imageCtrPxY -5.0
    nAnnuli 120 // # annuli to use for integration 2-D image to 1-D interferogram
    nPeaksExpected 1 // # peaks to be used in the 1-D interferogram (0=unknown how many peaks)
    peakRange[0] 10,60 // expected start/end position in pixels for peak 0

    Right now, only a single peak is accomodated. Because I gave a range of 10-60, it was the first peak.

    Analyze v1.19 2006-12-16

    This version of Analyze has the sign correction, as well as the sine correction.

    1. The zenith angle in degrees has been converted to radians by dividing by 2*pi.

    2. If Analyze is fed a dark image, then a zenith image, then nightglow image(s), the wind velocity will be shown, calculated from
      dopplerShiftConv = DopplerShiftFSR/((x1,zenith - x0,zenith))
dAnnuli = x0,zenith - x0,nightglow
Vel = dAnnuli * DopplerShiftConv
HVel = Vel / sin(|ze/2*pi|)
      ze=zenith angle in degrees

    Analyze v1.20 2006-12-18

    This version of Analyze has the correct conversion of the zenith angle.

    1. The zenith angle in degrees has been converted to radians by dividing by 360/(2*pi) (i e, multiplying by pi/180).

    2. You now have a button for previous image. You need to be careful when using this, because if you back up over a zenith image, the previous image will be compared to it, when it should be compared to the next earlier image. For example, if you are viewing 071, and you back up to 069, the most-recently-viewed zenith image is 070, so 069 will be compared to 070, when it should be compared to 065.

    Analyze v1.21 2006-12-20

    This version of Analyze uses the filename method of image type recognition for any untagged image, not just the old-format ones.

    Nonetheless, you should start tagging your images fairly soon.

    Analyze v1.22 2006-12-30

    This version of Analyze implements a flat-field correction to the peak-finding. At the moment, the 1DI that is used to fit the Gaussians for the wind velocity is the only place where it is applied.

    1. The correction is of the form
      sumCorrected(i)=sum(i) * (ff1*(i/nAnnuli) + ff0)
      sum(i)=normalized sum of annulus i sumCorrected(i) is used for the 1DI

      The values for ff0 and ff1 come from the Analyze control file, and have default values of 1 and 0 (i e, no correction).

      Here are sample control file lines

      ff0	1.0	// flat-field correction, normalized to center of image
ff1	0.2	//  with 20% boost at edge of image for 120 annuli

      I tried these settings on a zenith image, and the difference between the two peak positions was 0.01 (out of 45.5), so it doesn't seem to make much difference, which is what I would expect.

    2. A default was added for the number of peaks to be processed by the quick-look. If you had left this out of the control file, you could have gotten a crash.

    Analyze v1.23 2007-1-3

    1. Changes in the quick-look plots:
      • The "Hdr" button and display had some minor problems, which have been fixed.
      • The manual center selection buttons have been moved to the left side, to make room for the plots.
      • The data scaling indicator is now blue for unscaled and red for scaled. You probably don't use scaling at all any more.
      • The linear/log scaling has been moved to just under the image. The linear/log button gave the wrong picture for log; that has been corrected.
      • The spacing of the descriptive text on the right has been changed, and the auxiliary inputs are not displayed if they are all 0.
      • The image tag is shown in the descriptive text, if available.
    2. The quick-look will be disabled if the number of peaks expected (from the Analyze control file) is 0.

    3. The list of recent files in the File menu has been increased from 16 to 30.

    4. Wind velocities are plotted as a function of time. In this implementation
      a) Scaling is fixed, at x=0-600 min and y=-300 m/s - +300 m/s.
      b) Each graph has x-coord relative to the time of its first point. Therefore you cannot compare the graphs directly, since they will be offset slightly in time.
      c) Background color is ugly pink.
      d) Points are hollow dots. Note the first point will be a semi-circle.
      e) There can be up to 10 plots, but you can only see 6 complete and 2 partial plots. A new plot is started for each new direction, and a new direction is (az,ze) where either differs by more than 0.1 deg.
      f) The plots are labeled to the nearest deg.
      g) Scrolling the window messes up the plots. This is a bug, but I want to get you this version so you can try it.

    Analyze v1.24 2007-1-10

    This version has some user interface improvements:

    1. The list of recent files in the File menu has been decreased from 30 back to 16. It turns out that when there are 30 in the list, 17-30 can't be recalled.

    2. For the quick-look velocity plots:
      a) All the plots have the same origin and scale for time. The origin is the earliest image, which is plotted as 0 hours.
      b) The scaling and choice of grid or ticks, whether to show the x-axis, are settable from the "Velocities" menu.
      i) The plot will display a grid or ticks on either axis. To turn both off, click on the one that is currently turned on.
      ii)Initial settings are x-ticks, x-axis on, y-ticks, x scale=12 hours, y-scale=+-200 m/s. In the future, these initial values will come from the Analyze control file; at the moment, they are fixed.
      c) A new "Image" menu contains the plotting options for the FPI image. These options were previously in the "View" menu.
      d) The plot point symbol has been changed from a hollow circle to a solid black circle.
      e) The tick and grid color has been changed to light blue. The x-axis, if shown, is black.

    There are still some problems related to scrolling: if the window is scrolled down when a new velocity plot is created, it will appear in the wrong place. A work-around is to create all the velocity plots while the scroll bar is at the top, then scroll it down to look at the lower ones.

    There are also some display problems, due to the small size of the graph. Labels on the ticks and grid lines can overlap when the spacing is too small.

    Analyze v1.25 2007-1-14

    A single change:

    Images tagged S (or if untagged, in files whose initial letter is S) will not be processed for the velocity display.

    Analyze v1.26 2007-1-30

    1. A new button, Clear, appears on the top toolbar. When it is clicked, it does the following:
      a) Removes the stored dark image.
      b) Removes the stored zenith image.
      c) Removes all the wind velocity plots, including forgetting their directions.
      After clicking it, you will be in the same state as when Analyze is first started. That means the next dark image processed is stored, the next zenith image processed is peak-fitted and subsequent nightglow images are peak-fitted and compared to the zenith peaks, with the results plotted.

    2. The time origin is shown when there are one or more plots.

    3. A new Image menu entry, "Plot as", allows you to set the plot resolution, or disable the image plot. The way this is done is that every n-th point is plotted, for your choice of n=1, 2, 3 or 4. n=1 plots every point (as in previous versions of Analyze), n=2 plots 1/2 x 1/2 = 1/4 of the points, so you see a fainter image on the white background, etc.

    4. I increased the width of the wind velocity plots, which should be suitable for a 1200-wide screen.

    5. The height of the window has been adjusted to accomodate all the velocity plots; you should be able to scroll down to see all 5 rows (currently the maximum is 5 rows of 2 plots). Also, if the window is scrolled when a new plot is created, it should appear in the correct place; this was a bug in v1.25.

    Analyze v1.29 2007-3-8

    1. The peak-fitting has been improved. All the Arequipa images were fit, except a few very noisy ones, using fixed peak ranges of 5-25 and 25-55. I didn't try the adaptive method.

    2. The batch processing allows you to pause or interrupt. You do this by typing on the keyboard while the processing is running.
      TYPE      MEANS
C or c    Continue processing.
Q or q    Stop processing.
1-9       Process 1-9 more images, then pause and wait for another instruction.
          IMPORTANT: While you are paused, the menus are inactive, so you cannot,
          e g, change the scaling at this point. This shortcoming may be fixed later.

      For example, after starting batch processing, typing 1 repeatedly on the keyboard will do 1 image at a time. Typing C will do all the rest; typing Q will end the processing.

    3. Although L images are integrated and peak-fitted (always failing, because the peak positions are different), they are not processed for the velocity plots. Y images are now treated the same way (i e, integrated and peak-fitted, but not included in the velocity plots).

    4. A bug crashed Analyze if there were more than 10 different directions was fixed. There were strict criteria for deciding if a direction is new (az or ze differs by 0.1 deg).

    Analyze v1.30 2007-3-9

    This version fixes the inverted gaussian problem, caused by an incorrect expression for the initial guess for std dev of the gaussian, 1/12*(xMin+xMax) instead of 1/12*(xMax-xMin). This didn't matter in most cases, because the iteration for best fit converged to the correct value. However, in the ones that failed, because of a larger number of rings, xMin+xMax was large, and so far from the correct value that Analyze converged to another local minimum, which was not the desired one.

    Analyze v1.31 2007-5-16

    1. The center coordinates are now all real numbers, rather than integers. This includes the image center in the control file (imageCtrPxX, imageCtrPxY) and the expected peak ranges (peakRange). Existing control files will continue to work.

    2. When you are using the white circle to locate the center, the initial clicking on the image locates the center at the pixel clicked, which will be integer coordinates. Subsequent left-clicking will increase the radius by 10, and right-clicking will decrease it by 1 (these are the same as in previous versions). What is new is that shift-right-clicking will decrease the radius by 0.1 pixel, and shift-clicking an arrow moves by 0.1 pixel.

    3. The quick-look now produces an output file. This file, named Quick-look output.txt, is in the same directory as the initial image. Successive images are appended to the file. Restarting Analyze will not overwrite existing image info.

      An example of the data for a single image is
      Image C:\A3O\Camera\X20061112051.img
      Dir Az Ze t v I T
      0 0.00 44.99 0.0000 32.11 20998.92 0.000000
      1 90.00 -45.01 0.0371 -84.07 15872.65 0.000000
      2 90.00 45.01 0.0739 1.81 20341.56 0.000000

    4. Quick-look changes
      a) The menu has been renamed from "Velocities" to "Quick-look".
      b) The line "dPeak = xxx annuli Vel = xxx m/s HVel=xxx m/s" now only appears for images of type N, since it is meaningless for Z and L images.
    5. Temperature plotting in quick-look
      a) The Analyze control file contains the choice of ranges that appear in the Velocities menu. In the control file, you give the lower and upper limit for each possible range. For example, if you want the temperature axis on the quick-look graphs to run either from 100 to 300 deg K, or from 100 to 500 deg K, the control file would contain the line
      tempScale 100:300,100:500 // choices for temperature ranges
      and then the Velocities/Scaling for temperature submenu would look like
      100 : 300
      100 : 500
      The default scale is the first one in the list.
      b) There is a new quick-look menu choice for enabling or disabling the temperature plots.
      c) Temperatures are plotted as solid blue dots (somewhat difficult to distinguish from black velocity dots).
      d) A plot with only temperature shows for the zenith images.
      e) Several new control file variables are required. Here is an example of each.
      peakRangeLaser[0]    5,25  // where to look for the peaks in the laser image

      peakRangeLaser[1]   25,45

      thickness       1.0          // spacer gap in cm

      lambdaLaser     632.81644    // laser wavelength in nm

      lambdaSky       630.0030     // nightglow wavelength in nm

      atomicWeight    16           // emitter atomic or molecular weight in g/mol
    6. The Generate image function has been fixed so it does the binning. First, the image is generated at the full resolution (e g, 1024 x 1024). Noise is added to each point. Then the binning takes place, by summing bx x by pixels to form superpixels (e g, if bx=by=2, the displayed image is 512 x 512 pixels). No check is made for pixel oflo during the summing.

    7. Generated images can be integrated without crashing. The fitting of Gaussians does not take place for generated images.

    Analyze v1.32 2007-6-15

    1. Temperature processing can be disabled entirely. A control file variable determines this. If there is no entry in the control file, temperature processing is enabled.
      tempProcess	TRUE	// enables processing temperature from peak broadening
      If temperature processing is disabled, the menu item Quick-look/Plot temperature cannot be set.

    2. In case the laser peak is wider than the nightglow peak (probably due to a bad fit), the temperature is set to 0.0. This will avoid the negative square root issue.

    3. The test for a new direction (for quick-look) now has two parameters, may be in the control file; if not, the default for these is 0.1. A direction is the same as a previous direction if
      |azAngle-velPlotAz|<dirAzTolerance AND |zeAngle-velPlotZe|<dirZeTolerance

      where (velPlotAz, velPlotZe|) is the previous direction and (azAngle, zeAngle) is the new direction.

      The control file lines look like

      dirAzTolerance	3.0	// variation allowed in az angle to be considered same quick-look direction
dirZeTolerance	3.0	// variation allowed in ze angle to be considered same quick-look direction
      Right now, the first (az, ze) seen for a direction is displayed on the quick-look graph. You may want to use the average of all the points for that direction, or maybe even a rounded value (e g, round to nearest 5 deg). possibly controlled by a file variable.

    4. The maximum number of quick-look points has been increased to 400 per direction.

    Analyze v1.33 2007-7-4

    1. The message at the end of batch processing now indicates if images earlier than the selected starting images were skipped. Batch processing expects images in the order dark, laser, zenith, nightglow (i e, a dark image should precede all other images to remove background; a laser image should preceed all sky images to calculate temperature; a zenith image should precede all non-zenith images to calculate velocity).

    2. The quick-look file format has changed:

      Initial image C:\Miscellaneous\Meriwether\A3O\Camera\Images 2005 04 05_6\D20050406001.img Analysis done at 2007-7-4 20:42:23 UTC
      Image file Type Dir Az Ze tAbs, nsec/100 tRel, hr v I T Peak# Mean Std dev Baseline Amplitude
      X20050406001.img N 1.78 60.16 127573072570150000 0.0000 1 23.2984 1.9816 3137.6579 1241.9080
      2 47.3926 2.5317 3152.1813 1015.9652
      X20050406002.img N 90.33 61.08 127573075318280000 0.0000 1 23.9546 2.0694 2114.7569 1541.3789
      2 47.0664 2.3850 2270.7530 1501.1411
      X20050406003.img Z 90.33 0.39 127573078027500000 0.0000 1 23.8333 3.3352 1848.3067 772.7499
      2 47.3120 1.6410 1994.2271 903.4010
      X20050406004.img N 1 2.02 -60.25 127573080775620000 0.0000 -133.70 6297.12 1 24.1214 1.9939 2452.0804 6297.1181
      2 47.5309 1.9980 2610.8291 6283.0926
      X20050406005.img N 2 90.33 -59.42 127573086271240000 0.0763 -638.42 3175.75 1 25.1975 1.3898 2938.9451 3175.7513
      2 47.6383 2.0504 2869.5331 1610.6492
      X20050406006.img Z 1.64 -0.15 127573091767800000 0.1527 1 24.2441 1.9369 1692.6268 1291.5118
      2 47.7711 1.9861 1862.0049 1198.8069
      X20050406007.img N 3 1.64 60.25 127573103424060000 0.3146 -30.92 1258.91 1 24.3109 1.9295 3300.8692 1258.9083
      2 47.9007 2.4691 3390.3212 1197.2291
      ...
      L20050406006.img L 127573175102180000 1.3101 1 13.5097 1.3976 6359.1330 167264.2346
      2 37.1215 1.5037 6272.6848 155557.3004
      X20050406019.img N 3 2.16 60.11 127573181538740000 1.3995 -51.70 5471.48 927.9436 1 24.6489 2.2168 4144.3129 5471.4802
      2 48.1824 2.1013 4562.6143 5576.9077

      The Gaussian fit parameters are shown for all the peaks, although only the first is used for velocity and temperature determination. Inapplicable fields are left blank (e g, direction and angles for laser images; temperature for sky images when laser image did not precede it). The intensity is only shown for nightglow images images preceded by a zenith image, although it is the same as the amplitude of the fitted Gaussian.

      In the above example, images X1 and X2 don't have v or I shown, because there is no preceding zenith image. Since these are not plotted, their relative time is also shown as 0; image X3 is the time origin for all the relative times.

    3. All velocity, intensity and temperature points now have a common time origin, which is the time of the first zenith image processed.

    Analyze v1.34 2007-7-6

    The quick-look file can now be opened and closed from a script

    1. Two new script commands have been added: LOG_OUTPUT ANALYZE, x (x=OPEN or CLOSE).

      OPEN tells Analyze to create a new quick-look output file, in the same directory as the currently-displayed image; if no image is being displayed by Analyze, the command is ignored. The name of the file will be Analyze_yyyymmddHHMMSS.txt (e g, Analyze_20070706213159.txt), where the date/time is UTC at the time the script command is executed by Master.

      CLOSE tells Analyze to close any open quick-look output file; no error occurs if there is none. After the CLOSE, subsequent quick-look data will be written into a new file.

      The proper script sequence then should be
      TAKE_IMAGE
      DISPLAY_IMAGE (to load an image (presumably a dark image) into Analyze)
      LOG_OUTPUT ANALYZE, OPEN
      [take more images; their quick-look output will be in the file]
      LOG_OUTPUT ANALYZE, CLOSE
      If batch processing is used, the quick-look output file is opened automatically, and closed only when Analyze is exited.

      A revised script language document is attached.

    2. The start for relative time is now the first image processed (usually a dark image). All relative times are relative to this image. "First" here means the image with the earliest acquisition time. Resetting the velocity plots with SETUP ANALYZE will cause the first subsequent image processed to be used as a time base.

    3. Dark images are now listed in the quick-look file.

    Analyze v1.35 2007-7-14

    The only change is that illegal angles in the image header are treated as (0,0) for analysis. You can see the actual angles using the "Hdr" button.

    Analyze v1.36 2007-9-24

    The only change is that images tagged 'B' are ignored by Analyze, except to display them. The same has always been true of 'S' images.

    Analyze v1.37 2007-10-1

    The quick-look plotting has been corrected and enhanced. Changes affect only the screen display.

    The choice of plot ranges is now user-selectable, by lines in the Analyze control file.

    You select the ranges, the default range, and a suffix to appear after the numeric range. The range can be either a value R, meaning the range is 0 - R, or a pair of values Rlo:Rhi, meaning the range is Rlo - Rhi. The default range is indicated by "*" following the range. If you don't have a default, the first range is used. The suffix is optional, and is just a character string to appear after every menu entry. If you use it, it must be at the end of the list, in quotes.

    Here are the lines from my control file, which create the same choices as in v1.36:

    velScale     -10:10,-20:20,-50:50,-100:100,-200:200*,-500:500," m/s"  // choices for velocity scaling
intensScale   1000,3000,10000,20000*,50000,100000,200000,300000       //             intensity
tempScale     500:900*,700:1400                                       //             temperature scaling (ranges)

    If the velScale, intensScale, or tempScale lines are missing from the control file, the quick-look plots will not work, and the menu will show a message indicating the lines are missing.

    Also note that the axis and grid are correct for velocity; this can be a little confusing. But in all cases, the bottom of the graph is the low value for the range, and the top the high value.

    Analyze v1.38 2007-10-15

    This version plots the "velocity" for zenith images:

    The peaks for the initial zenith image are stored; its velocity is set to 0.
    Subsequent zenith images have velocity computed as

    dAnnuli=zenithPeak0[0]-zenithPeak[0]; // red shift if >0
    apparentVel=dAnnuli*dopplerShiftConversion;
    vel=apparentVel;
    where
    zenithPeak0[0] is the peak position of the first peak in the initial zenith image.
    zenithPeak[0] is the peak position of the first peak in the current zenith image.
    dopplerShiftConversion is the value from the current zenith image of dopplerShiftFSR/(zenithPeak[1]-zenithPeak[0]).
    zenithPeak[1] is the peak position of the second peak in the current zenith image.
    vel is what is plotted.

    Analyze v1.39 2007-11-6

    None of the items in the "Smoothing" box are active yet

    1. Pixel data is smoothed during the annular integration, but only for determining the value of the integral. The old method (replace spikes with the average of their nearest neighbors) has been replaced by the following:
      1. Compute the mean and sample standard deviation for each annulus.
      2. Replace any pixel > 3 std dev from the mean for its annulus with the mean.
      3. Repeat steps (1) and (2) until the sum of all pixels (integral) doesn't change, or until the maximum number of passes is reached (this is currently 13, and quick tests stopped at 5).
      The "replacement" is done by altering the integral, not the pixels in the image. This means that some deviant pixels will be replaced during each pass. It can be proved that for a single pixel changed in this way during some pass, it will also be changed during all subsequent passes. I haven't yet proved this works for multiple pixel changes, but I am reasonably confident this is also true.
    2. This smoothing is active during both the integration which is done for peak location, and integration which is initiated by clicking the "integrate" button.
    3. The integration dialog has been expanded to show the mean, std dev and number of points replaced, all for the final pass.

    Analyze v1.40 2007-11-10

    1. The crash during integration of a noisy image has been fixed.

    Analyze v1.41 2007-11-29

    1. The intensity for zenith images is now plotted in the QL graphs.

    2. The Analyze control file has optional variables displayFreqX and displayFreqY, which control the spacing between pixels shown on the screen. The default is (1,1), meaning show every image pixel. From the front panel, you can change to (2,2), (3,3) or (4,4) to show 1/4, 1/9 or 1/16 of the pixels. From the control file, the default may be set to any value (dx,dy), where 1<=dx,dy<=8. Note that most of the possible displays are not accessible from the front panel.

    3. The 1-D interferogram produced by the automatic integration used for QL can optionally be output to the QL file. That file now looks like
      Initial image    Analysis done at 2007-11-29 20:24:05 UTC
          Image file Type Dir      Az      Ze       tAbs, nsec/100  tRel, hr          v          I          T Peak#         Mean      Std dev     Baseline    Amplitude
    X20070928091.img    Z   1   -0.00    0.01   128354078747700000    0.0000       0.00  -11979.50                1      14.2446       0.1925 1179108.4103  -11979.4968
                                                                                2      35.3216     126.1807 1939417.4019 -688571.3238   0 0.000000e+000
   1 1.134659e+006
   2 1.135028e+006
...
  90 1.377366e+006
    4. A new optional control file variable, write1D, controls whether the 1-D interferogram is written. The default is FALSE (not written).
      write1D	TRUE	// puts 1-D interferograms into the QL file
      No header info is included in the QL file at present.

    Analyze v1.43 2012-12-22

    1. The display at the bottom of the screen showing the peak ranges now shows fractional annuli. If "adaptive peaks" is in use, these numbers will show how the range for the peak location is being changed over time. If If "adaptive peaks" is not being used, the ranges will remain the initial values from the control file.

    2. The non-linear least-squares fit to the Gaussians has been made more robust, and can no longer crash due to a std dev of 0.

    3. A bad image may move the peaks out of range. More thought should be given to how much drift is allowed. Now the algorithm is
      1. Following each fit, find the limits that include 99.9% of the peak area (+-3.29 std devs).
      2. Adjust the range to match these limits, but don't change more than 2 annuli.

      This doesn't work well if there is no fit, so we need some criterion for "fit was achieved". Also, 2 annuli seems like way too much change for a single image.

    Analyze v1.44 2008-1-22

    1. Dark images are smoothed as determined by a new set of five control variables (those in gray were already required):

      // For smoothing dark images
      nZonesX 8 // number of rectangular zones for smoothing
      nZonesY 8
      smoothDarkPasses 3 // max # of smoothing passes to be made (0=don't smooth)
      smoothDarkNStdDev 3.0 // # of std dev for which points are smoothed during integration using the averaging method
      smoothDarkAvg TRUE // replace all points in each block with the block average after smoothing
      // For smoothing other images (laser, zenith, nightglow)
      noiseAnnAvg TRUE // noise via triple Annular averaging filtering rather than spike filtering removal
      smoothPasses 3 // number of noise filter passes re comparison of pixel value with mean and std dev.
      smoothNStdDev 3 // # of standard deviations for which points are smoothed by replacement with mean

      Notice that the dark image smoothing is controlled separately from the other image smoothing. You can try with and without replacing all points in a block with their average. Also note that the average that points are replaced with during the smoothing is an integer, which can matter when the range of all the points is small.

      The smoothing algorithm is for each of the nZonesX x nZonesY blocks, the mean and std dev of points in the block are computed. Then pixels that are >
      smoothDarkNStdDev std dev from the mean are replaced with the mean. This process is repeated a maximum of smoothDarkPasses times, or until no points in the block are replaced.

      Then, if smoothDarkAvg is true, all points in the block are replaced by the mean.

      If smoothDarkPasses=0, no dark image smoothing is done, and the results should be the same as with Analyze 1.43.

    2. The Image/"Plot as" menu has been changed so the selected plot is bulleted. This was an oversight in the prior versions.

    3. Some modifications in plot scaling have been made to accomodate the constant pixel value that results from using the dark image mean everywhere.

    Analyze v1.45 2008-2-3

    1. The calculation of std dev in dark image smoothing has been made more robust (this was the cause of the error message Shaun sent on Feb 2).

    2. The control file read section has been made more robust; it failed on the Analyze control file sent with 1/28 images, because they had lines terminated with CR-CR-LF, rather than the usual LF.

    3. The integrated image (1-D spectrum) is now stored in the QL output file if write1D in the Analyze control file is TRUE, regardless of whether peak-fitting is enabled.

    4. The QL output file has an additional line at the start showing the version of Analyze that produced it.

    Analyze v1.46 2008-2-20

    1. The QL output file will be opened properly regardless of whether peak fitting is on, and whether a dark image has been processed first.

    Analyze v1.47 2008-12-23

    The major change in this version is the windowing scheme. Each part of the display is in a separate window. This version is not a finished product; it has not been tested sufficiently to use as a production version.

    The time origin is missing from the QL plots, and needs to be fixed.

    1. Two dark images are maintained: one for sky and one for laser. These are distinguished by their image types (D=sky, K=laser). The new control file variable darkImagesD is TRUE if only D images are to be used (see figure below).

      The relative time starts when the dark image is loaded. When using D and K images, the start time will be whenever the last of these is loaded. If that isn't satisfactory, I will have to make some further modifications.

      Reinitializing with SETUP ANALYZE or using the Clear button on the front panel removes both dark images.

    2. New control file variables nCoef, sin_set and cos_set have been added for the Fourier model analysis. These are optional, but if they are not present, the Fourier analysis will not be done. Existing variables lambdaLaser and lambdaSky are used to calculate K_sky from K_laser. Remember that K_laser is only available if the peak-locating is enabled. (see figure below)

      The results from the Fourier analysis appear on the annular integration screen. They are not in the Analyze output file; this will be changed shortly.

    3. The image display did not show the last pixel in the +x direction, so for a 512 x 512 image, the display was 511 x 512. This has been fixed.

    4. The icons for Analyze and its windows have been redone.

    5. The Analyze main window will start as the "restored" size, rather than maximized.

    6. There is a new arrangement of windows.
      a) Analyze starts with a main window that is empty. When a image is loaded, seven windows will appear within the main window, each containing one part of the display. These individual windows can be moved, resized, minimized, or closed.
      b) There is a new menu, Window, which allows you to switch between windows, or arrange them all as tiled (all shown at once) or cascaded (layered).
      c) The graphs have been modified. They are larger, and the annular integration shows individual points (as hollow circles) connected by lines. Formerly we just showed the lines.
      d) There are several things about the new window arrangement that either don't work properly, are unfinished, or haven't been implemented yet.

      i) The initial arrangement of windows is not correct. Eventually, the preferred initial arrangement will be remembered and used each time Analyze is started.
      ii) Although you can resize the windows, the plots within them don't change size. This is an improvement which will be added later.
      iii) The Fourier model fits are being shown as the U_i, not converted to v and T.
      iv) The names of the windows only appear in the Window menu for the first image loaded. This is a bug.
      v) Selecting Cascade from the Window menu changes the size of all the windows, making some too large and some too small.
      vi) The New Window option in the Window menu needs to be removed. It will create a new window, but that can't be used for anything.
      vii) The image generation and test image options in the File menu are grayed out until the first image is loaded.
      viii) The image name doesn't show in the main title bar.
      Here is an example of the new lines for the control file

      // Fourier analysis
calcFSR FALSE   // following value will be used as FSR
FSR     41.77   // K_sky
nCoef   16      // number of sin/cos coeffs
// Fourier sine coefficients
sin_set    -0.131796    -0.140904    -0.112894    -0.103813   -0.0908205   -0.0742134   -0.0701661   -0.0522044   -0.0412150   -0.0340287   -0.0269390   -0.0210721   -0.0146484  -0.00956312  -0.00550300  -0.00443464
// Fourier cosine coefficients
cos_set      0.740765     0.394518     0.269715     0.190429     0.124508    0.0911150    0.0579157    0.0384405    0.0269235    0.0151834   0.00731469   0.00262180 2.72505e-006-7.56467e-005 -0.000793489  0.000107915
darkImagesD     TRUE

    Analyze v1.48 2009-1-9

    The QL plots still show only the Gaussian fits.

    Known bugs:

    1. The "Windows" menu doesn't work properly. You can tile or cascade the windows, but the list only shows for the initial image.
    2. The scaling for QL plots doesn't appear until an image has been loaded. Instead, a "missing line in control file" appears.
    Changes:
    1. The QL plots have been modified
      a) The time origin is now visible at the top.
      b) The arrangement of the plots has been changed from 2 to 3 columns.
      c) The spacing between plots has been increased slightly.
      d) The temperature now appears as an open blue circle, rather than a solid dot. This makes it easier to distinguish on poor-quality monitors such as mine.
      e) The legend for each plot has been fixed so that last few characters aren't cut off.

    2. The station #, latitude, longitude and height have been added to the image header window. These are only available in newer images (later than 2007-2-1).

    3. The quick-look plots now have a user-chooseable time scale, of up to 10 possible values. Here is the required control file line, for the 6 time scales that have been previously used:
      timeScale 0.5, 1, 2, 6, 12*, 24 " hr"
      The suffix (in this case " hr") will appear after each entry in the list. Usually the suffix will begin with a space.

    4. Changes to the control file
      a) A new required value, indexRefraction, has been added. This is the index of refraction of the etalon medium.
      b) The variables thickness,lambdaLaser, lambdaSky and atomicWeight are now required. In v1.47 they were optional. These are used for the Fourier model fitting.

    5. The Fourier model fit values now appear in the QL output file. Here is a sample. The columns headed U1-U4 are the Fourier fit best-fit values, and v and T (Fourier) are the values computed from delta-U3 and U4, respectively. The final integer is an indication of why the LM fit terminated.
                Image file Type Dir      Az      Ze       tAbs, nsec/100  tRel, hr          v          I          T Peak#         Mean      Std dev     Baseline    Amplitude             U1             U2             U3             U4    v (Fourier)    T (Fourier)
    D20080311004.img    D                       128496537107170000    0.0000
    L20080311004.img    L                       128496539926230000    0.0392                                      1      15.7008       2.2165    2243.2480    8637.2769  5.701678e+003 -1.921945e+003  2.270936e+001  0.000000e+000  0.000000e+000  0.000000e+000 1
                                                                                2      52.1300       2.5403    2314.4099    6172.9714  5.482656e+002  2.841964e+003  4.500618e+001  1.695968e-001  0.000000e+000  1.111412e+002 1
                                                                                3      88.6430       2.7085    2190.2796    5191.7532 -6.441216e+003  8.856451e+003  8.857034e+001  2.673808e-001  0.000000e+000  2.762486e+002 1
    X20080311031.img    N   1    0.00   44.96   128496542596230000    0.0762                        1474.2409     1      23.9187       5.4868    1462.4621    2072.2830  5.179071e+002  1.619804e+003

    Analyze v1.49 2009-1-10

    Known bugs:

    1. The "Windows" menu doesn't work properly. You can tile or cascade the windows, but the list only shows for the initial image.
    2. The scaling for QL plots doesn't appear until an image has been loaded. Instead, a "missing line in control file" appears.
    Changes:
    1. The maximum number of Fourier coeffs has been increased from 16 to 25. If you exceed 25 on the control file line, you will get a warning and the extra values will be ignored.

    2. The annular integration window now show the Fourier model fits, in blue. The toolbar buttons at the top allow you to turn off either or both model plots. The current default is to show them both.

    3. Tooltips have been added to all the buttons on the three toolbars (the main one, at the top; the center-adjusting one, in the image window; and the plot one, in the annular integration window).

    4. The QL file format has been changed to show the Fourier fit parameters in the same format as the Gaussian fit (i e, no exponents). The same change has been made in the annular integration window.

    Analyze v1.50 2009-2-9

    Known bugs:

    1. The "Windows" menu doesn't work properly. You can tile or cascade the windows, but the list only shows for the initial image.
    2. The scaling for QL plots doesn't appear until an image has been loaded. Instead, a "missing line in control file" appears.
    Changes:
    1. A new control file variable, weight, determines whether statistical weighting is to be applied to the Fourier fit.

      weight TRUE // statistical weighting (1/variance) is to be used for the Fourier model fit

    2. Coefficients q1 and q0 in the control file set the argument of the sin and cos in the Fourier series expansion.
      arg=(2*pi*n/K_image)*(q1*U(3)+k+q0)
      To get the previous behavior, q1=-1 and q0=0. If the variables q1 and q0 are not in the control file, these values are used as defaults.
      q1      -1.0    // parameters for the sin and cos args
q0      0.0
      3.

    3.  An error in the computation of the Jacobian was fixed; the argument of the trig functions was -k+U(3), not -U(3)+k. This error would only have affected the rate of convergence, not the best-fit results.

    Analyze v1.51 2009-2-18

    Known bugs:

    1.  The "Windows" menu doesn't work properly. You can tile or cascade the windows, but the list only shows for the initial image.
      2.

    2.  The scaling for QL plots doesn't appear until an image has been loaded. Instead, a "missing line in control file" appears.

    Changes:

    1.  The set of buttons on the annular integration window controls the appearance of the plot. There is one button for the experimental data (annular integration), one for the Gaussian fit, and one for the Fourier model fit.

Clicking any of these buttons cycles through the four possibilities

      No plot

      Plot as points only

      Plot as line only

      Plot as line with points

      The default is line with points.

  Experimental data

  |  Gaussian fit

  |  |  Fourier model

  |  |  |

  Emacs!

 No plot    Points    Line    Line with

             only     only     points

      2.

    2.  When you start Analyze, it no longer says "Analyze v0.8" before you loaded any images.

    Analyze v1.52 2009-3-5

    Known bugs:

    1.  The "Windows" menu doesn't work properly. You can tile or cascade the windows, but the list only shows for the initial image.
      2.

    2.  The scaling for QL plots doesn't appear until an image has been loaded. Instead, a "missing line in control file" appears.

    Changes:

    1.  The weighting of zero-valued points has changed. There is now a choice of

      a) 0 ignore 0 points

      b) 1 weight them as 1

      c) 2 weight as 1/2 the minimum weight of the non-zero points

      d) 3 use a small, but non-zero, weight (currently 1e-4)

      e) 4 use the average weight of all non-zero points

      The choice is set by a new control file variable, wtZero, which is 0-4, as indicated above. If 'weight' is FALSE, non of these applies, as all points will be weighted 1.

    Analyze v1.53 2009-3-6

    Known bugs:

    1.  The "Windows" menu doesn't work properly. You can tile or cascade the windows, but the list only shows for the initial image.
      2.

    2.  The scaling for QL plots doesn't appear until an image has been loaded. Instead, a "missing line in control file" appears.

    Changes:

    1.  The weighting has been corrected so the same weights are used for the function and its derivatives. This could have caused fits to take longer, or, in extreme cases, to diverge, resulting in a crash.

      2.

    2.  The version number that comes up on starting the pgm has been updated.

    Analyze v1.55 2009-5-1

    1.  If the number of points in the QL plots exceeded 400, the earliest points were removed to make room for newer points. However, this did not work correctly for the intensity and temperature plots, only for velocity. This error has been fixed.

      2.

    2.  The quick-look plot window now has a toolbar with two buttons, which turn the plots of v, I and T on or off for Gaussian and Fourier model fits. The Fourier model values are shown as squares, and the Gaussian as circular dots. The color for intensity has been changed from blue to green, to make it more distinguishable.

      For the Fourier model, the value for intensity is the parameter U_2. Tthe calibration factor can be added later, if necessary.

    Analyze v1.56 2009-6-9

    1.  The Fourier fit computation for velocity has changed. The new method is

      if(isZenithImage)

      {

      zenithU3[iPeak]=fourierParams[iPeak][3-1];

      if(zenithImageAvailable) dU3=zenithU3[iPeak]-zenithU30[iPeak];

      else dU3=0.0;

      }

      else

      {

      if(zenithImageAvailable) dU3=zenithU3[iPeak]-fourierParams[iPeak][3-1];

      else dU3=0.0;

      }

      vFourier[iPeak]=-dU3*dopplerShiftFSR/K_sky;

      This should reference nightglow images to the latest zenith image, and senith images to the first zenith image.

    Analyze v1.57 2009-6-10

    1.  The Fourier fit computation for velocity has changed. The new method is

      if(isZenithImage)

      {

      zenithU3[iPeak]=fourierParams[iPeak][3-1];

      if(zenithImageAvailable) dU3=zenithU3[iPeak]-zenithU30[iPeak];

      else dU3=0.0;

      }

      else

      {

      if(zenithImageAvailable) dU3=fourierParams[iPeak][3-1]-zenithU3[iPeak];

      else dU3=0.0;

      }

      vFourier[iPeak]=-dU3*dopplerShiftFSR/K_sky;

      The highlighted part is the change from v1.56.

    Analyze v1.58 2009-6-13

    With this version of Analyze, in order to activate the directional sign reversals, you have to add one or two new control file variables.

    Specific changes:

    1.  The Fourier fit computation for velocity is now corrected from line-of-sight wind to horizontal flow by dividing by sin(|ze|*(pi/180))). This is the same correction now being applied to the Gaussian fits.

      2.

    2.  The signs of the wind velocity are adjusted before plotting/file output if the new control file variable vSignAdj=T. If this variable is not present, vSignAdj defaults to F (no adjustment). The same processing is done for both Gaussian and Fourier fits.

      a) (az,ze) is reduced to the range 0<=ze<=90 and 0<=az<360 by applying the transforms

      i) If ze<0, ze <- -ze and az <- az+180.

      ii) If az<0, az <- az+360; if az>=360, az <- az-360 (i e, az is taken mod 360).

      b) The direction is identified as one of

      northward   360-e < az  or 0 <= az < e

      eastward     90-e < az <  90+e

      southward   180-e < az < 180+e

      westward    270-e < az < 270+e

      other       any other az

      e is a tolerance from the new control file variable vSignTol. If not present, e defaults to 0.3 deg.

      c) If the direction is westward or southward, the sign of the wind velocity is reversed before plotting and reporting.

    Analyze v1.59 2009-6-13

    1. The coloring of the points is: v (black), I (red) and T (green); Fourier are square, Gaussian are round.

      2.

    2.  The signs of the wind velocity are adjusted if the direction is westward or southward. In 1.58 it was mistakenly eastward instead of westward. Here is the code which converts LOS ("apparent") velocity to horizontal (same for both Gaussian and Fourier):

      v=apparentVel/sin(fabs(zeAngle*(pi/180)));

      if(vSignAdj)

      {

      // (az,ze) is reduced to the range 0<=ze<=90 and 0<=az<360

      az=azAngle,ze=zeAngle;

      if(ze<0) {ze=-ze; az+=180;}

      if(az<0) az+=360; // get az mod 360

      if(az>=360) az-=360;

      // The direction is identified as one of N, S, E, W or other

      if(az>(360-vSignTol) || az<vSignTol) dir='N';

      else if(fabs(az-90)<vSignTol) dir='E';

      else if(fabs(az-180)<vSignTol) dir='S';

      else if(fabs(az-270)<vSignTol) dir='W';

      else dir='O';

      if(dir=='S' || dir=='W') v=-v; // reverse sign of velocity for these directions

      }

      2) The text at the top of the QL plot window shows whether the meteorological convention ("vSignAdj" above) is active, and if so, the tolerance.

    Analyze v1.60 2009-6-13

    1.  The LOS to horizontal correction is not applied to Fourier velocities. This was an error, which made Fourier velocities be off the plot.

      2.

    2.  The points in QL plots for Fourier velocities are hollow squares, rather than solid, to make them easier to distinguish from the Gaussian points.

    Analyze v1.61 2009-6-16

    1.  The scaling for time, velocity, intensity and temperature for the QL plots now persists from image to image.

      2.

    2.  The choice for Fourier/Gaussian fit for the QL plots now persists from image to image.

    Analyze v1.62 2009-6-20

    The only change is that it has been rebuilt to eliminate the compatibility error message.

    Analyze v1.63 2009-6-24

    The only change is the handling of SETUP ANALYZE. Previously Analyze crashed if there was no image being displayed while this command was given. Now the command is just ignored if no images have been processed.

    BUG: When you have done batch processing in Analyze, giving this command does not clear the plots. You shouldn't have any need to do this in the field, but if you do, just use the "Clear" button on the Analyze front panel to reset the plots.

    Analyze v1.64 2009-7-6

    1. This version should drastically reduce the number of crashes you have. Analyze is not bulletproof, though, if random images are used as input, or the control file parameters significantly mismatch the images.

      With this version, you can batch process all the 2008-11-07 images without error.

      2.

    2.  Internal change for better debug output. This should not affect you.

      3.

    3.  The only image types which are processed are D, K , L, Z, and X. All other types are ignored. Other known image types are B, S and Y (these are types for which Analyze has specific "ignore" code, because it was assumed someday we might want to process these).

      Note that the image type is set by the script; it is not necessarily the first letter of the image filename.

      Also, the image count shown at the end of batch processing is the total number of images that were obtained on or after the initial image. Some of these will be ignored.

      4.

    4.  The L-M fit has been made more robust (less likely to fail in case of bad data).

    Analyze v1.65 2009-7-10

    1.  If a laser image had a bad fit, Analyze could have corrupted memory. It is not too likely you would have noticed this, but in any case, it has been corrected.

      2.

    2.  How Analyze processes each image is now controlled by a table of processing steps. You must create this table by statements in the Analyze control file. See the attached document for how to do this.

    Analyze v1.66 2009-7-14

    This version of Analyze should fix some display problems.

    1.  Scaling for the annular integration plot now uses the observed data, and the Gaussian and Fourier fits (if any). Scaling does not change when what is displayed on the plot is changed; the plot is always scaled as if all three were being shown.

      2.

    2.  Some spurious numbers for dark images have been removed: the values for Gaussian peak position and Fourier parameters are no longer displayed when peak fitting was not done.

    Analyze v1.67 2009-7-17

All TRACE statements have been commented out. TRACE statements are a debugging aid. When you run Analyze they are still created, but not displayed. Apparently some combination of circumstances generates trace output that exceeds the maximum characters (512).

    Analyze v1.68 2009-7-19

Analyze v1.68 has two sets of changes: one that will help isolate the crash, and one that may stop them.

    1.  A large number of ASSERTs have been added, to check at different stages of the code that things are working. If a problem is detected, you will get as ASSERT message which will have the location of the error condition. This may assist in determining its cause.

      2.

    2.  The pgm has been relinked with a different (and more appropriate) library. It is remotely possible this may have been the cause.

    Analyze v1.69 2009-7-22

    1.  DCs are being recycled to stop the resource leak.

      2.

    2.  Large numbers (which usually result from bad fits) are being displayed and written to the output file in exponential notation, to avoid long strings of digits (and possible crashes).

    Analyze v1.70 2009-7-29

    1.  Analyze no longer does the check for missing or garbage angles. Previously, it did the following check on the values sent by Observatory and stored in the image header by Camera.

      if(azAngle>=-180.0 && azAngle<=+180.0 && zeAngle>=-180.0 && zeAngle<=+180.0) // angles OK

      else azAngle=zeAngle=0.0;

      Apparently one of your angle corrections, count discretization error, or round-off error, was putting an angle to slightly outside the +-180 range.

    Analyze v1.71 2009-8-6

    1.  The maximum number of annuli has been increased from 256 to 512. Also, if your control file specifies more than that (or too few) you will receive an error message.

    Analyze v1.72 2009-8-10

    1.  An oversight when changing the maximum number of annuli from 256 to 512 made the peak fitting not work. A second error in the plotting used the wrong scale in this case.

    Analyze v1.73 2009-8-11

    1.  Another oversight when changing the maximum number of annuli from 256 to 512 made the peak fitting not work for N images. Fixed.

    ">Analyze v1.74 2009-9-16

    1.  Giving the script command LOG_OUTPUT ANALYZE,OPEN or CLOSE before displaying any images no longer causes a crash. It is not necessary to open the Analyze log, unless you have previously closed it, but now doing so will not cause any problems.

    Analyze v1.75 2009-10-4

    1.  Analyze now responds to the LOG_DIRECTORY script command (see document LogFiles.rtf).

    Analyze v1.76 2010-2-13

    1.  The defaults for log file name and start time weren't being set properly, so the filename was incorrect. This has been fixed.

    Analyze v1.77 2010-3-13

     The only change is the timestamp causing the "possibly incompatible" message has been fixed.

    Analyze v1.78 2010-3-15

    1.  If a second instance of Analyze is started, you will receive an error message and be prohibited from continuing.

    Analyze v1.79 2010-3-24

    1.  If Master was started when Analyze was already running stand-alone, Master would not appear at all on the screen, even though it was running. This has been corrected.

    Analyze v1.80 2010-6-2

    1. This is the first release built with new compilers. There is a large number of small changes, due to potential errors found by the new compilers. Therefore, you should check it out carefully.

      2.

    2. This release must be used with Master v0.80, Camera v1.05 and Observatory v1.22, unless you intend to run Analyze stand-alone.

      3.

    3.  The image size Analyze can handle has been increased from 1024 x 1024 to 2048 x 2048.

    Analyze v1.81 2010-8-23

    You will need to install Master v0.84, Camera v1.07, Observatory v1.23 and Analyze v1.81 together as a set.

    There should be no visible difference in the operation of this version of Analyze.

    Analyze v1.83 2011-1-28

    1. This should be used with Master v0.87, Camera v1.13 and Observatory v1.26.

      2.

    2.  The header detail window has been updated to show the new camera parameters related to EM.

    Analyze v1.84 2011-3-25

    The only difference with this version is its compatibility with Observatory v1.27.
This should be used with Master v0.88, Camera v1.14 and Observatory v1.27.


Overview of

Overview of Communicate

Communicate is used to transmit information between A3O computers on a network. It can also be used to transfer files between an A3O machine and any other machine with an ftp server.

Another function of Communicate is data compression. Files can be replaced with their compressed versions, or an existing file can be transmitted in compressed form to a remote machine, and stored there in either compressed or uncompressed form.

Communicate can also send simple email messages to anyone connected to the Internet, using a remote SMTP (Simple Mail Transport Protocol) server.

The Communicate control file contains a default list of remote machines, the network list. Each entry in this list is (name, userName, password, server URL, protocol, etc).

Although Communicate has some stand-alone functions, it is used mainly to carry out script commands issued by Master.

Communicate uses File Transfer Protocol (ftp) to send and receive files from other nodes. Communicate also uses ftp for messages between A3O processes on different nodes of the network.

Inter-node messages are created and sent by Communicate on one node (usually initiated by a script command in Master), and received by Communicate on another node. The Communicate process that receives a message may initiate a data file transfer, or make the message available to Master running on the same node.

The inter-node messages are stored as files in a dedicated directory, specified by the Communicate control file.


Communicate control file

The Communicate control file contains default values for parameters controlling Communicate’s operations. In the present implementation, there is no way to change these parameters dynamically.

Parameter | Meaning | Req? | Default
Description | A comment line describing this Communicate control file. It must be the initial line in the control file. | yes |
MessageDirectory | Path to the temporary directory on the local machine where Communicate stores message files. Required, but not yet used. | yes |
NetworkEntry | Specifies a node on the A3O network; see below for format. There will be one NetworkEntry line for each node on the network; these are all included in the network list. | yes |

Each network entry line has the form

NetworkEntry [*] "name" "serverName" "userName" "PWRemote" "PWLocal" "defaultTo" "defaultFrom" privRemote privLocal

Field | Description | Type | Example
* Marks the entry for the local node. Exactly one network entry will have it. literal *
name | How scripts refer to this node. | string | "EKU"
serverName
or
protocol:serverName 		The URL of the server. The name or IP address may optionally be preceded by the transfer protocol (presently ftp, sftp or smtp). string "ftp.A3ONode18.MyUniversity.edu"
"ftp:ftp.A3ONode18.MyUniversity.edu"
"sftp:111.222.33.44"
"smtp://myISP.net:587" (the final number is the port)
userName | The user name needed to log onto the server. | string | "A3Ouser"
PWRemote | The password needed to log onto the server. If no password is required, this should be null string (""). | string | "ic75&&3W"
defaultTo | Email address for recipient if none is given in script. Used only for SMTP; null string ("") for other protocols. | string | "My_labMachine@MyUniversity.edu"
defaultFrom | Email address for sender if none is given in script. Used only for SMTP; null string ("") for other protocols. | string | "My_email@MyISP.net"
Fields required, but not presently used
PWLocal | The password other nodes need to log onto this node. If no password is required, this should be null string (""). | string | "UR here"
privRemote | What operations the local node can perform on the remote node. | integer | 12345
privLocal | What operations the remote node can perform on the local node. | integer | 678

Here is a sample Communicate control file:

// Specify 4 nodes on an A3O network, referred to as "thisNode", "USR", "USR-A3O", and "Me"
NetworkEntry * "thisNode" "server name0" "user name0" "remote PW0" "local PW0"  "[toAddrDefault unused]" "[fromAddrDefault unused]" 12300 45600 // this is the local node
NetworkEntry  "USR" "ftp.ces.college.edu" "anonymous" "" "local PW1"  "[toAddrDefault unused]" "[fromAddrDefault unused]" 12301 45601
NetworkEntry  "USR-A3O" "ftp.somewhere.org" "auser" "user_password" "local PW2"  "[toAddrDefault unused]" "[fromAddrDefault unused]" 12302 45602
NetworkEntry  "Me" "smtp://MyISP.net:587" "myUsername@MyISP.net" "myPassword" "[local PW unused]" "myLab@Univ.edu" "myEmail@MyISP.net" 12303 45603

MessageDirectory "NOT YET IMPLEMENTED" // required, but not used yet
The final NetworkEntry is for email. Order of entries doesn’t matter, and, except for the initial comment line, all entries are optional, although without an entry for a particular protocol, Communicate won’t be able to use it.


Network list

Communicate’s network list is an internal structure which defines the remote machines with which an A3O machine can exchange information. There may be up to 64 entries in this list, and each entry consists of

Field | Description | Type
Name | The name by which a script refers to this entry. Valid names follow the same rules as script variables, but have a maximum length of 32 characters. | string
Protocol | The file transfer protocol to be used. Currently, only ftp, sftp and smtp are supported. | string
Server name | The Internet address (URL) of the remote server. | string
User name | User name to be used for ftp/sftp connection to remote machine. | string
Password for remote | Password required for ftp/sftp connection to remote machine. Null string if no password is required (i e, anonymous ftp). | string
The following are used only for SMTP (email):
Default recipient address | “To” email address, if none is specified in a script. | string
Default sender address | “From” email address, if none is specified in a script. | string
The following are not yet in use:
Password for local | Password which remote must use for ftp/sftp to local machine. | string
Privileges on remote | [not yet implemented] | integer
Privileges on local | [not yet implemented] | integer
Number of transmissions | Count of data transmissions by Communicate from the local node. | integer
Number of transmit errors | Count of data transmission errors originating from the local node. | integer
Last transmit time | Date and time of the most recent data transmissions by Communicate from the local node. | time value
Number of receptions | Count of data receptions by Communicate at the local node | integer
Number of receive errors | Count of data reception errors at the local node. | integer
Last receive time | Date and time of the most recent data reception by Communicate at the local node | time value

The Communicate control file contains a default list of remote machines. The list may be altered by Master script commands NETLIST_UPDATE (not yet implemented).


Email operations

Communicate may be used to send email, to anyone with an email address, providing that the local computer (the one running A3O) is connected to the Internet. Email may be sent from a script under control of Master (see EMAIL_SEND), or a test email may be sent from the Communicate front panel.

Here is what will be needed for you to send email from Communicate to anywhere:

  1. Access to one or more SMTP servers (usually these are furnished by your Internet service provider [ISP]). For example, AT&T is one ISP.

  2. The settings your ISP uses for an email client (a client is an email program that runs on your local computer, such as Eudora, Outlook or Thunderbird). These settings include

    • Server address (e g, "smtp://outbound.att.net").
    • Port to be used for TLS (transport layer security), e g 587.
    • Authentication credentials (user name and password) required by your ISP.
    • The “From” email address to be used. Servers can require a “known” address here.
    • Certificate information (see below).
These settings are included in the Communicate’s control file.

You can send an email to a single recipient, with a copy (“CC”) to another email address, using EMAIL_SEND in Master. The size of the email body text is limited to 10 lines of 99 characters each. It is not yet possible to send any attachments.

For emails sent from a script, you control the fields to, from, cc, subject, and the text in the body of the message. The format of each of these fields is the same as in any other email system. The date and time will be added by CC, and also the message-id, although the latter will normally be replaced by the SMTP server. See EMAIL_SEND) for details.

Communicate can send a test message from the front panel, even if running standalone. The message will be sent using the default SMTP server specified in the control file, to the recipient given in the default recipient field of that network entry. The email should look like this:

Date: Mon, 23 Sep 2013 11:36:57 -0800
To: [default recipient]
From: [default sender]
Subject: Communicate test email

    The Germ

A mighty creature is the germ,
Though smaller than a pachyderm.
His customary dwelling place
Is deep within the human race.
His childish pride he often pleases
By giving people strange diseases.
Do you, my poppet, feel infirm?
You probably contain a germ.

One current sticking point is the certificate information. Email is sent in an encrypted form, using SSL (secure socket layer), and when a connection is established, both sides present certificates to prove their identity. To work properly therefore, Communicate must receive a valid certificate from the SMTP server. This feature is currently disabled; we accept the ISP’s certificate without verification. The authentication credentials and message text are still encrypted using SSL, but if a bad actor presents a bogus certificate, he will also have the keys to decrypt the email.


File transfer operations

The script commands FILE_SEND and FILE_FETCH initiate file transfer (via ftp or sftp) between the local machine and another node on the A3O network. File-handling operations discusses file handling on a local machine.

For these commands one of the nodes is always the local machine. Communicate must be running on the local machine, and the remote machine must be an FTP/sFTP server. It is not necessary that Communicate be running on the remote machine. Which protocol is used is determined by the serverName field in the Communicate control file.

FILE_SEND sourceDirectory, sourceFilename, destNodeName, destDirectory, destFilename. Here source is the local node, amd dest the remote node.

FILE_FETCH sourceNodeName, sourceDirectory, sourceFilename, destDirectory, destFilename. Here source is the remote node, amd dest the local node.

When the named file already exists on the destination node, it will be overwritten.

Communicate transfers files one at a time, so it is possible for a script to start multiple transfers (FILE_FETCH and FILE_SEND do not wait for the transfer to complete). Communicate may or may not have multiple transfers running in parallel. The status of the most recent 10 file transfer requests may be obtained using FileXferStatus(order).

To set up a Windows XP Professional machine to act as an FTP server, you configure Internet Information Services (IIS) to include File Transfer Protocol (FTP) Service. This will create an FTP site for the directory C:\inetpub\ftproot. Contents of that directory, and any of its subdirectories, will be available for FTP transfer. See here for detailed instructions. sFTP is not supported by Windows, so it requires separate software.

Note that the default is to allow anonymous FTP (i e, no password required), so your FTP root directory is accessible to anyone for reading or writing. You can set the FTP server to require a password, but since the password is sent as cleartext in FTP messages, it is not secure. Even worse is the option to use your Windows XP account passwords, because those will give access to your entire system, not just the FTP tree.

Remedying this security hole will require having Communicate running on both the local and remote nodes, and using anonymous FTP to pass encrypted passwords and files, or using a protocol other than FTP. These features are not implemented in A3O at present.

Alternatively, the sFTP (secure FTP) protocol uses SSH2 (Secure Shell) to encrypt all communications, and is therefore reasonably secure.


File-handling operations

Communicate has three file-handling functions: move, copy, and delete. All operate on a local A3O node. The corresponding script commands are FILE_MOVE, FILE_COPY and FILE_DELETE.

Each of move, copy and delete specifies a source directory, which must already exist, and a pattern. The pattern determines a group of source files to be processed. Patterns are either a filename, or a partial filename including the wildcards “*” and “?”. The pattern is interpreted by the Windows file system, which uses “*” to mean any number of characters (including 0), and “?” to mean a single character.

Examples:

Pattern | Typical files matching pattern
?KU_*.img | NKU_L_20121004_050722_012.img, SKU_X_20121004_050701_015.img, EKU_L_20121004_050726_005.img, WKU_L_20121004_050725_005.img
PKR* | PKR_20121003200416_Analyze.txt, PKR_B_20121004_040407_001.img, PKR_D_20121004_040416_001.img
*.img | PKR_B_20121004_040407_001.img, PKR_D_20121004_040416_001.img

Move and copy specify a destination directory, which also must exist. All files matching the pattern in the source directory are moved or copied to the destination directory. File times (creation, modified, and accessed) are preserved. If the destination directory already contains a file with the same name as one being moved or copied, the existing file is silently overwritten.

The source directory can be read-only, but the destination directory must be read-write, and not a system directory.

A directory should be a complete path, e g, C:\A3O\Image data. Relative directories are possible, but they are tricky and unpredictable, so you should avoid them. A directory may optionally include the trailing “\”; thus, C:\A3O\Image data and C:\A3O\Image data\ are equivalent.

For delete, all files matching the pattern in the source directory are permanently removed (they will not be in the recycle bin).

At present, the only file operations which involve a remote A3O node are the script commands FILE_SEND and FILE_FETCH.

Also see File compression operations.


File transfer operations

File compression operations

The script commands FILE_COMPRESS and FILE_UNCOMPRESS initiate compression or uncompression of files on the local machine. Often compression is used prior to file transfer to another node on the A3O network.

For these commands Communicate must be running on the local machine.

Compression uses the zip file format (here) and the zlib library. Compression is done using the default compression level (see the benchmark below).

Compress 526 525,312-byte image files into a single zip archive file. 2.8 GHz Pentium, WinXP32.
 | Z_BEST_SPEED | Z_BEST_COMPRESSION | Z_DEFAULT_COMPRESSION | WinZip 10.0 normal
Time MM:SS | 00:35 | 26:40 | 01:45 | 00:38
Compressed size | 63 MB | 46 MB | 51 MB | 53 MB


Changes in

Changes in Communicate v0.07 2013-12-16

  1. This version of Communicate must be used with updated versions of the other processes: Master v1.01, Camera v1.27, Observatory v1.55, and Analyze v2.02, or later.

  2. The front panel now has a minimize button (_ at upper right).


Changes in

Changes in Communicate v0.06 2013-10-1

  1. This version of Communicate must be used with updated versions of the other processes: Master v1.00, Camera v1.23, Observatory v1.48, and Analyze v2.00, or later.

  2. There are no changes in functionality from v0.05.


Changes in

Changes in Communicate v0.05 2013-9-24

  1. EMAIL_SEND allows you to send compose and send email messages from a script. Email operations describes Communicate’s email capabilities. control file.

  2. The Communicate control file now optionally includes an entry for the SMTP server (necessary for email).


Changes in Communicate v0.04 2013-4-30

  1. FILE_SEND and FILE_FETCH now support transfers using either ftp or sftp. Which of these protocols is used is determined by the serverName field in the Communicate control file.

  2. The Communicate control file now has the network information encrypted. The encryption is done by a separate program, CommunicateControlFile_Setup, which is described in a separate document.

    For security, only the encrypted copy of the control file should be resident on the station computers.


Changes in Communicate v0.03 2013-2-20

  1. Uncompression of zip files has been added (using the script command FILE_UNCOMPRESS) to extract files from a compressed archive.

  2. Three file-handling functions have been added: file move, file copy, and file delete. All operate on a local A3O node. The corresponding script commands are FILE_MOVE, FILE_COPY and FILE_DELETE.


Changes in Communicate v0.02 2013-1-18

  1. Communicate now does file compression (produces zip files). See FILE_COMPRESS.