README.TXT July, 2000 Camera Initialization ("INI") Files Apogee Instruments, Inc. ----------------------------------------------------------------------- CONTENTS OF THIS DOCUMENT: Part I.....................................................Introduction Part II.........................................Installing the INI file Part III..................................Important INI file parameters Part IV...................................Description of all parameters Part V...................................................Software Notes Part VI.................................................Sample INI File Part VII.................................................System Support ----------------------------------------------------------------------- [Part I. -- Introduction] The files on this diskette contain vital information for the initialization of Apogee Instruments cameras. All Windows 95/NT camera-control software packages use these INI files to link to the camera. INI file parameter values differ by sensor geometry and a few other operational factors, which will be discussed later in this document. Except for the parameters discussed in Part III, there is no need to modify the INI files on this diskette. ----------------------------------------------------------------------- [Part II. -- Installing the INI file] The camera INI files on the accompanying diskette have been named by camera model (e.g., AP1.INI is for an AP1 camera, regardless if it is UV-coated or a new Kodak KAF-0400 "E" sensor). Choose the file that matches your camera and copy it into your camera-control software directory. In the case of the Image-Pro Plus camera driver from CRI, the camera INI file must be renamed APCCD.INI and placed in the C:\IPWin3 directory. Other applications allow the user to select the INI file they need to use, independent of the file name or location. NOTE: If you have properly connected the camera to your computer but it cannot be found by the control software, the most common reason is a conflict with the base address. See Part IV for a description of the base= parameter. ----------------------------------------------------------------------- [Part III. -- Important INI file parameters] There are only a few instances when you will need to alter the INI file for your camera before using it for the first time. These are described below. See Part IV for a complete description of all parameters. [system] ecp=OFF Parallel Port Cameras Only: This parameter should be set to off if your computer BIOS has an option of "bi-directional" or "PS/2" for the parallel port (e.g., LPT1). If your computer BIOS does not have either of those options but instead has "ECP" or "ECP/EPP", select one of these modes and set "ecp=ON" in the INI file. [system] base=290 Apogee cameras use a base address but not an IRQ. For cameras that use an ISA-bus controller card, the base address for the camera is set by a jumper on the card. The INI file base= parameter value must match the setting on the card. If the card's default setting of 290 conflicts with other devices on the computer, the jumper may be moved to one of the other settings (390, 310, etc.), in which case, the base address value in the INI file must be changed to match the address of the card. Parallel-port cameras use the base address of the parallel port. If the computer's parallel port is not 378, the INI file must be changed to match the parallel port's base address. [system] trigger=OFF This parameter is currently supported only in PMIS, MaxIm DL CCD, and MicroCCD. Default setting is off. If you are using the remote trigger port, use trigger=ON. [system] cable=SHORT The two valid parameter values are "SHORT" and "LONG". Standard camera systems may include a 10-foot, 15-foot or 25-foot cable. These are all considered "short" in the camera INI file. Custom length cables up to about 200 feet may be ordered. For 16-bit cameras, cable longer than 115 feet is considered "long." For AP10 systems, over 35 feet is "long." In KX and 14-bit AP systems, above 25 feet is considered long. In these systems, you may have to modify the test= and mode= parameters. See the detailed description of the cable= parameter later in this document for instructions on choosing the appropriate cable= parameter value. [temp] cal=165.000000 To ensure proper reporting of the CCD temperature by the sofware, the value of cal= should match the "Zero" value in the Temp Calibration section of the test data sheet shipped with your camera. A value of cal=165.000000 is nominal. ----------------------------------------------------------------------- [Part IV -- Description of all parameters] Below is a detailed explanation of each parameter used in the camera INI file. The parameter values shown are taken directly from the sample INI file found at the end of this document. [system] base=290 Most critical for camera recognition is the base address. All Apogee cameras (except parallel port cameras; see note below) are configured for a default base address of 290. If this address causes a conflict on your computer, you can change the base address by resetting the jumper on the ISA-bus controller card (see the instruction sheet entitled "Installing the PC ISA-Bus Interface Card"). After making the jumper change on the controller board, be sure to make the "base=" line in the INI file correspond to that address. NOTE: For parallel-port cameras the INI file default is "base=378", which is typically the base address of the computer's parallel port (usually LPT1). In some cases, the computer's parallel port base address is 278 or 3BC. If so, the INI file base= parameter should be modified to match it. Sometimes a second parallel port (LPT2) is added to the computer. Make note of which port the camera is connected to and set the INI file's base= parameter accordingly. mode=1 The mode value is used to invoke special operating modes in some cameras. The setting for most cameras is "mode=1". AP7B cameras use "mode=8". AP7P and AP8P cameras use "mode=0" or "mode=2" (mode=0 is normal; mode=2 eliminates horizontal bleeding from bright objects, such as bright stars in an astronomical image). KX and 14-bit AP cameras (except AP10s) use various mode values, depending on cable length (see the "cable=" parameter below). test=4 In most cameras, the default is test=4. The test value is used to invoke special operating modes in some cameras. These are as follows: Flush Frequency matching (AP7B only): For AP7B users with controller firmware S16H and above, the test value can be used to "tune" the flush frequency to eliminate bright lines(rows) when other programs are running in the background during image readout. The default value is 10. The range is 1-15. Lowering the number will result in brighter lines during readout, while raising the number will result in darker lines during readout. VDD Inversion: Some Cameras, such as older AP7s required an inverted control signal for the CCD output amp drain supply. Cable Extension: The KX and 14-bit AP series (except AP10) cameras use this bit to extend the maximum cable length to 200 feet. This parameter and the mode= parameter are used in conjunction with the cable= parameter. Cable length is discussed in detail there. Timer Resolution: Changes operation of the exposure timer to give 0.001-second resolution. At 0.001-second resolution, the minimum exposure time is 0.002-second (instead of 0.02-second) and the maximum becomes 1040 seconds (instead of 10,400 seconds). The advantage is that exposures can be set for 0.001-second intervals rather than 0.01 second intervals in normal mode. Not all software packages support this mode, although all of them can be "fooled" by entering an exposure value 10 times higher when in this mode (thus, 0.02 in the software becomes actual 0.002). The table below lists the possible values for test=. The final value is the sum of the options desired. For example, if cable extension AND 0.001 second timer resolution is desired, the final value for test is 4+1+8=13. Operation Test=[4 + option below] ------------------------------------------------------------------ Default, no optional values: add 0 Vdd control inversion option: add 2 Cable Extension (long KX cables) option: add 1 0.001 Timer resolution option: add 8 Controller cards with Q or QRX1 firmware: subtract 4 [test=0] shutter=ON trigger=OFF These are used by the application to enable the shutter during exposures and to allow triggered exposures. Shutter is normally left ON. Trigger is normally set to OFF. Trigger should be ON if you are using the trigger port with PMIS or MaxIm DL CCD. caching=ON All cameras are now shipped with cached fifo memory on the controllers, and should have this value set to ON. Older AM and AP series 16-bit controllers did not have caching capability; caching should be turned off for those systems. Memory caching improves throughput, especially on the 12- and 14-bit systems. This parameter can be set to OFF with caching controllers, but the download speed will be slower. cable=SHORT Sets the expected cable length range for the system (except for parallel-port cameras - they use the c0_repeat= parameter discussed later in this document). An incorrect setting of the cable= parameter will cause corrupted data. A clue that this has happened is the abrupt data changes by some power of 2. The KX systems use cable= in conjunction with the test= and mode= parameters to extend the range. The table below shows the possible cable length ranges and their test=, mode=, and cable= settings. Note that the test values are written as if no other options of the test= parameter are desired (see the test= parameter description above). * 16-bit AP Systems and SPH Systems: For 1-115 feet of cable: cable=SHORT, test=4 For 125-250 feet of cable: cable=LONG, test=4 * 14-bit AP10 Systems: For 1-35 feet of cable: cable=SHORT, test=4 For 65-100 feet of cable: cable=LONG, test=4 * 14-bit KX and AP Systems (must be using K14N or higher firmware): For 1-25 feet of cable: cable=SHORT, mode=1, test=4 For 26-55 feet of cable: cable=LONG, mode=1, test=5 For 65-75 feet of cable: cable=SHORT, mode=5, test=4 For 85-115 feet of cable: cable=LONG, mode=5, test=5 For 115-135 feet of cable: cable=SHORT, mode=9, test=4 For 145-165 feet of cable: cable=long, mode=9, test=5 For 175-200 feet of cable: cable=long, mode=13, test=5 data_bits=14 Set for the number of bits in the system. The typical values are 14 or 16. Some software applications ignore these values. port_bits=8 The output port now has 8 bits, but some older controllers had 6 bits. This is only used by applications that allow manipulation of the open-collector output port, such as PMIS. tscale=1.000000 This is a calibration of the timer with respect to the master oscillator on the controller boards. The application software uses this value to adjust the ACTUAL value written to the timer to compensate for faster or slower oscillators. The default value is 1.000000 when used with a 16.257 MHz Oscillator. NOTE: KX85 cameras use "tscale=10.000000" gain=OFF This parameter was created for dual-gain 12-bit camera systems, which are now obsolete. It should be turned on only when using 12-bit (dual-gain) cameras running with PMIS or MaxIm DL CCD software. When turned on, the software allows you to set the camera for high (32 e-/ADU) and low (15 e-/ADU) gain. Use high gain if you wish to increase your dynamic range under bright light conditions. Use low gain to distinguish subtle details in low-light conditions. See the [camreg] section near the end of this document for setting the default gain in the selector box. c0_repeat=1 For parallel port cameras only. This is equivalent to the "cable=" parameter. For up to 60 feet of cable, use c0_repeat=1. Beyond that length, increase the value in increments of 1 if data dropouts appear in the images (these may appear as a scattering of hot pixels across the image). [geometry] rows=521 columns=792 imgcols=768 imgrows=512 These parameters are used to set the chip geometry, i.e., the number of rows and columns. The total number of columns (columns=) and rows (rows=) includes a border of non-imaging columns (or "overscan and underscan") and rows around the imaging area, which is defined by imgcols= and imgrows=. The non-imaging regions can be supressed by making use of bic and bir (discussed in the following section). The camera will not initialize if bic+skipc+imgcols is greater than or equal to the value of "columns." Likewise, bir+skipr+imgrows should not equal or exceed the value of "rows." When describing a CCD array (e.g., 1536x1024), the first number is the number of columns (the long side of a non-square CCD). bic=12 bir=6 Bic= sets the imaging offset in columns and can be set to ignore the pre-scan columns. The minimum number allowed is bic=2. Bir= sets the imaging offset in rows and can be set to ignore the pre-scan rows. The minimum number allowed is bir=2. Note that the rows= and columns= values are not constrained by the actual sensor. For instance, an AP1 camera with 768x512 imaging pixels can be fooled into taking a 1024x1024 image, by setting the geometry section to mimic an AP6. The resultant image will show the 768x512 image, with extended bias filling out the remainder of the 1024x1024 array. The table below lists array sizes for sensors used in Apogee cameras. Remember that the physical array is only a ballpark figure and can be increased in order to accommodate before-imaging and after-imaging offsets. Camera Array (Phys.) Array (Imag.) BIC BIR SKIPC SKIPR Col Row ImgCol ImgRow ------------------------------------------------------------------ AP/KX260 531 x 521 509 x 511 14 7 7 2 AP1, KX1 792 x 521 768 x 512 12 6 6 2 AP6 1040 x 1034 1024 x 1024 9 7 6 2 KX85 1335 x 1039 1300 x 1030 26 6 8 2 KX14 1349 x 1044 1317 x 1035 23 6 8 2 AP2, KX2 1560 x 1033 1536 x 1024 12 6 6 2 AP4, KX4 2067 x 2058 2048 x 2048 12 6 6 2 AP7 532 x 532 512 x 511 12 3 6 2 AP8 1043 x 1033 1024 x 1024 12 6 6 2 AP9 3095 x 2057 3072 x 2048 14 6 8 2 AP10 2081 x 2058 2048 x 2048 26 6 6 2 hflush=4 vflush=4 The hflush= and vflush= values define the binning used for flushing between images and for row and column skipping for subframe operation. The binning used for flushing and subframe can be different than that used for the region-of-interest data. This can be a very useful tool for increasing the speed of subframes for focus mode. The parameter values can be as high as hflush=8 and vflush=63, but generally little speed is gained above values of hflush=8 and vflush=8. skipc=6 skipr=2 These parameters throw out the first number of rows and columns specified before displaying a region of interest. Some systems produce non-data artifact rows, typically in rows 1 or 2. Eliminating them helps auto-scaling routines function properly. Both skipc= and skipr= parameters must be greater than 1. Additionally, skipr= must be less than the value for bir=. Since the digitization process always produces 2 non-data rows along the upper portion of the image, skipr= can always be set to 2, thus forcing bir= to always be at least 3. Upon inspection of the images produced by your camera, you may notice dark or bright columns and/or rows at the edges of the frame. Bic=, bir=, skipc=, and skipr= work together to eliminate unwanted pre- imaging and post-imaging columns and rows, but some trial and error may be necessary to eliminate them completely. A logical sequence for setting these parameters is to set bic=2, bir=3, skipc=2 and skipr=2. Take a subframe and zoom in on the top and left edges of the frame. Set skipc= and skipr= in the INI file to values equal to the number of bad columns and rows seen at the edges of the image. Next, increase bic= and bir= until all the unwanted pre-imaging columns and rows are suppressed in a full-frame image. It may be necessary to increase the total physical columns and rows in order to accommodate higher values of bic=, bir=, skipc=, and skipr=. [temp] target=-10.0 cal=165.000000 scale=2.100000 backoff=2.0 The application uses these parameters to program the temperature controller used for cooling the CCD. The target= value is used to establish a default target. Not all applications may use this value, but may instead remember the last value entered by the user. The cal= and scale= factors are used to calibrate the controller. The cal= is a decimal number from 0-255, which corresponds to the digital byte written to the controller that produces a CCD temperature of 0 degrees C. The old typical value for cal= was 100, while the newer systems are being set for 165. Scale= determines the weighting of each digital count, as referenced to 0 degrees C. The typical value is scale=2.1. The application software uses backoff= to determine how many degrees to reset the controller if a maximum temp delta flag is detected. For example, if the user programs the CCD for -20 C, but the controller can reach only as low as -15 C, the application will reset the temperature at -13 C if backoff=2. This ensures that the controller will always regulate temperature properly. [camreg] gain = 0 opt1 = 0 opt2 = 0 The gain= parameter is only for 12-bit cameras, now obsolete. Used with "gain=ON" parameter in the [system] section, the [camreg] gain= parameter sets the default gain used by the software. In [camreg], the 2 choices for gain= are 0 (normal) and 1 (high). The "opt1=0" and "opt2=0" parameters are optional camera register bits used by Apogee for special test purposes. Leave these set to 0. ----------------------------------------------------------------------- [Part V -- Software Notes] Camera (for Linux) from Clear Sky Institute: The INI files on the accompanying diskette cannot be used directly with Camera. However, the contents of the INI file for your camera will be helpful when building the Linux camera driver. CCDSoft from Software Bisque: CCDSoft versions prior to 4.00.021 used a DLL that did not make use of some of the INI file parameters discussed here. In those versions, the INI file had to be called APCCD.INI and it had to be located in the CCDSoft directory. In 4.00.021 and higher versions, the INI file can have any valid filename and its location can be in any directory on your computer. However, when upgrading to version 4.00.021 from prior versions, you must click the "Settings..." button in the camera setup window and select the INI file you wish to use. You should also refresh your INI file by deleting the APCCD.INI file in your CCDSoft directory and recopying the INI file for your camera from the accompanying diskette. If you are using an older copy of CCDSoft, it is recommended that you upgrade to version 4.00.021 or higher. Software Bisque offers free upgrades on their web site. You can download the current version of CCDSoft by visiting http://www.bisque.com and navigating to the "Downloads" section. Image-Pro PlusTM capture driver from CRI: The camera initialization file should be renamed to APCCD.INI and placed in the IPP directory prior to installation of the capture driver from CRI. The installation program will abort of it doesn't find the APCCD.INI file in the IPP directory. Also, the data_bits parameter value may need to be increased if the range of the image pixel values is lower than expected. KestrelSpec from Catalina Scientific: KestrelSpec comes with its own INI file for Apogee CCD cameras. Some of the required INI file parameters for KestrelSpec do not exist in the INI files provided by Apogee Instruments. Therefore, do not replace the KestrelSpec INI file with an Apogee INI file. MaxIm DL CCD from Diffraction Limited: MaxIm DL CCD remembers the location of the INI file after initializing the camera the first time. Thereafter, clicking the "Restart" button in the Setup tab of the camera-control window will establish a link to the camera. PMIS from GKR Computer Consulting: There are 3 common error messages in PMIS camera control, related to CCD format, image size, and sometimes, the INI file. It is helpful to know which of these is caused by an incorrect INI file, and which is caused by program settings: % CLI - Error, Camera interface error, bad load. This message is usually due to a mismatch in the INI file geometry parameters. The sum of imgcols+bic+skipc must be at least 1 less than columns=; likewise, the sum of imgrows+bir+skipr must be at least 1 less than the value of rows=. Additionally, the value of skipr= must be 1 less than the value of bir=. If any of these rules is broken, a "bad load" message will occur. %CLI - Error, CCD format incorrectly defined. This is not the result of a faulty INI file. Go to the "Acquisition Area..." window in the "Camera" menu. Click "Full Camera" and then click "OK" and open a new image window. % CLI - Error, Image size or offset illegal or inconsistent, image size and CCD format incompatible. This is not the result of a faulty INI file. Close the current image window and open a new one before attempting to take an exposure. Besides the camera INI file, the PMIS.INI file (located in the PMIS directory) has camera parameter entries. Generally, the PMIS.INI file takes precedence when entries exist in both INI files. ----------------------------------------------------------------------- [Part VI. -- Sample INI file] [system] ecp=OFF -- Parallel port cameras only base=290 -- Parallel port cameras use the address of the parallel port mode=1 test=4 shutter=ON trigger=OFF caching=ON cable=SHORT data_bits=14 port_bits=8 tscale=1.000000 gain=OFF c0_repeat=1 -- Parallel port cameras only [geometry] rows=521 columns=792 imgcols=768 imgrows=512 bic=12 bir=6 hflush=4 vflush=4 skipc=6 skipr=2 [temp] target=-10.0 cal=165.000000 scale=2.100000 backoff=2.0 [camreg] gain=0 opt1=0 opt2=0 ----------------------------------------------------------------------- [Part VII -- System Support] Contact Apogee Instruments for technical support of your Apogee CCD camera system: Apogee Instruments, Inc. 1350 N. Kolb Road, Suite 120 Tucson, AZ 85715 By phone: (520) 290-8887 By fax: (520) 290-9324 By email: support@apogee-ccd.com By WWW: http://www.apogee-ccd.com/tech_support