 FrmUtility 1.0.1.3/24-Aug-2004 Help Index

Purpose:

FrmUtility handles many of the mundane frame file operations, such as file format conversion, importing of third party frame files, correcting known frame header issues, updating frame headers, re-applying frame corrections, etc. As such, it is intended to replace the utilities: Frm2Frm, Shrink, ToASCII, FrmFix and FrmRename. ToSAXII has not been replaced as it converts XENGEN format to Bruker format.

How To ...

Rename frame file sets.

Handle multiple frame files.

Unwarp multiple frame files.

Convert frame file format in batch files.

General

Input files

Tab

Convert format tab

Import defaults tab

Update header tab

Fixup header tab

Convert orientation tab

Apply corrections tab

Unwarp frames tab

Appendices

Bruker frame file format

Bruker ASCII frame file format

Release notes


Input files

Project directory:

Input filename (wildcards are OK)

Wildcards are permitted in filename inputs. You can use either single character wildcard '?' or multiple character wildcard '*'. You can use multiple wildcards.

You can use wildcards to change the file naming conventions as in:

    filename IN:    base*.*

    filename OUT:   base_*_*.sfrm

You can use wildcards to change the number of characters in frame number field.

    filename IN:    base01.A??

    filename OUT:   base_01_10??.sfrm

[Exit]	Terminate FrmUtility program.

[About]	Display copyright information.

[Help]	Display this help file and release notes.

[Browse]	Search for folder and starting frame filename.


Tab: convert format

Converts to and/or from:

•	Bruker frame format (ASCII header, BINARY counts, ASCII overflow table).

•	Bruker/BIS frame format (ASCII header, BINARY counts, BINARY tables).

•	Bruker ASCII frame format (ASCII header, ASCII counts).

•	TIFF (CHESS or Other format) (BINARY header, BINARY counts).

Can also convert to (but cannot read these file formats):

•	small Bruker frame format (half-size, ie 1K -> 512).

•	small Bruker/BIS frame format (half-size, ie 1K -> 512).

•	JPEG (curtesy of Larry Finger)

Can also convert from (but cannot write these file formats):

•	APS frame format (ASCII header, BINARY counts)

•	TIFF (MMX/MarCCD frame format) (BINARY header, BINARY counts).

•	SPEC (Roper WinSpec files) (BINARY header, BINARY counts).

Input file(s):

Project directory

Input filename (wildcards are OK)

For imported frames only:

[ ] Trim to Bruker size	Allow any frame dimension in import frame file and trim image dimensions to Bruker dimensions (512, 1024, 2048, 4096, etc.).

[ ] Allow any 512 multiple	Allow frame dimensions in multiples of 512, instead of 512*2^n (512, 1024, 2048, 4096). (SAINT currently does NOT support these odd frame dimensions of 1536, 3072, and 6144).Note: see import defaults tab to define values for missing header items.

Output file:

Filename (wildcards are OK)

(*) Bruker format

( ) small Bruker format

( ) Bruker ASCII format

( ) TIFF format

( ) JPEG format

( ) Bruker/BIS format

( ) small Bruker/BIS format

( ) imageNCIF format

Bruker and Bruker/BIS formats

[ ] 2-byte (MOSFLM)	Force Bruker format files to be 2-byte images for 3rd party software that cannot handle 1-byte frames. File is saved with an overflow table. You may wish to “unwarp” frame images BEFORE converting with MOSFLM option.

TIFF format

Bytes	Force output frame file to be 1, 2 or 4 bytes per pixel. (file is saved without an overflow table).

(*) CHESS

( ) Other

JPEG format

Min	[0]	JPEG min and max scaling for output image. Default is 0:255.

Max	[255]

[Convert]

Current limitations (ignored fields in file header of various frame formats):

    *) Bruker: Defaults to version 8 frame headers with 4096-byte overflow

    *) Bruker ASCII: Each line is limited to 80 characters plus terminators.

    *) TIFF: Reading TIFF files has many limitations:

         TIFF must be a single, full-size, monochrome, & uncompressed image.

         File headers are defaulted to best guess values.

         CHESS: private tags are not translated.

           Numerous frame header items are defaulted to best guesses.

         MMX/MarCCD: handles only omega or phi scan series.

           Assume angles are already in Bruker conventions, except for chi

             (CHImar + 90.0 = CHIbruker). This works for frame series collected

             at 2t=0, Om=0, phi, Ch=0, which convert to 0, 0, phi, 90 in

             Bruker angle conventions.

           Frame number and Number of frames in series are not converted.

           CCD temp is not converted.

           Detector roll pitch yaw are not converted.

           NEXP & CCDparms are not converted.

         Roper: All frame header information is defaulted.

    *) APS: Read only; FRM2FRM cannot write this frame file format.

    *) APS: angles in frame header are not converted to Bruker conventions.

    *) SPEC: Read only.

    *) imageNCIF: (n.y.i.)

Note: For compatibility with software requiring 512-byte overflow table, use the environment variable: "SET SAXI$512MAXOVF=1".


Tab: import defaults

Descriptions:

User:

Site:

Model:

Filter:

X-rays:

Target:

Kavg:

Kalpha1:

Kalpha2:

Kbeta:

Generator:

kV:

mA:

Monochromator:

Angle:

Roll:

Goniometer:

Starting	Ending

2theta:

Omega:

Phi:

Chi:

Scan axis.

Scan width [  ] deg.

Distance [  ] cm.

Total number of frames

Detector:

Flood:

Spatial:

Detector constants

PIXPERCM

CMTOGRID

DetectorCenter

X

Y

Detector mounting

Pitch

Roll

Yaw


Tab: update header

Allows one to update a frame header or set of frame headers to Bruker File Format Version 11. Missing items are either defaulted or set to user input values. Updating file headers is very useful when reading frame(s) into a program that cannot handle missing header items, such as APEX2 and PROTEUM2. (added in 1.0.0.8/02-Jun-2004)

Note: See BCP help files: Detector > Settings for more information.

Version 4 to 7 items:

Detector mounting:

Pitch	Typically 0.0

Roll	Typically 0.0

Yaw	Typically 0.0

Detector type:	Only three Bruker detectors did not place a string into DETTYPE: frame header line. These are HI-STAR (Multiwire), SMART-1K (CCD-PXL), and SMART-2K (CCD-PXL-2K). All other Bruker detectors should already be using Version 9 or higher frame headers.

CCD parameters

Num of exposures:	How many images where combined to single frame image.

Fixed BIAS

Baseline	Typically 0, 32, or 64.

Readnoise	See your detector parameter sheet.

e/ADU	See your detector parameter sheet.

e/Photon	See your detector parameter sheet.

Full scale	Dynamic range potential of frame (not image).

Version 8 to 11 items:

Detector parameters

PixPerCm	Number of 512-mode pixels per cm.

CmToGrid	Distance from front of detector to detection layer.

[ ] Circular shape

CCD chip temp

PreAmp gain

PreAmp speed

Experiment temp

Accurately timed

Brass hole spacing

Be window thickness

Monochromator

Angle

Roll

Update:


Tab: fixup header

Corrects known issues and / or overrides other frame header items. (Replaces FRMFIX)..

Known issues:

1.	Convert frames taken on MICRODIF for DOS from Version 6 (obsoleted) to Version 8 headers. New version 8 header items are set to default values. XYZ, ZOOM values are moved to AXES2 and ENDING2 lines. (MICRODIF for DOS will no longer be able to read these frames).

2.	Correct frame headers taken by GADDS for WNT version 3.300 to 3.302. Under these "beta" NT releases, the "AXES2:" and "ENDING2:" lines were incorrectly located at records 076 & 077 and the "FILENAM:" record contained garbage.

3.	Correct 2K CCD frame headers taken on large CCD with SMART V4.040 (requires the switch /BIGCCD). Note: This is not yet implemented! PROGRAM: SMART V4.040, DETTYPE:CCD-PXL-2K, some frames are missing “-2K”.

4.	Correct DOS frame headers with negative scan time bug. These frames were taken for over 12 hours and overnight under programs for DOS.

5.	Correct frame headers with 360 degree scan width bug. These frames were taken in "STEP" mode under GADDS for DOS or GADDS for NT prior to version 3.310.

6.	Correct frame headers for incorrect LINEAR values. The first LINEAR frame header parameter having a value that is below 1.0. This is incorrectly stored as the reciprocal of the true value. So far, this problem has only been seen on 2K CCD systems when using 512 frame size, but theoretically could occur on any area detector system.

7.	Correct SMART 5.056 and earlier frame headers for OCTMASK parameters on CCD frames to be used by GADDS.

8.	Correct SMART 5.0?? frame headers for angular modulus 360 error in lines ANGLES: & ENDING:. SAINT could not handle these frames.

9.	Correct frame headers for unreasonable scan times when external trigger was used. ELAPSDA and CUMULAT values are less than 0.05 seconds. Just uses ELAPSDR as the scan time.

10.	Correct frame headers taken on prototype BIS (version says 1, but is really 10).

11.	WARPFIL: or CORRECT: set to blank or C:\path\LINEAR, not LINEAR. (added in 1.0.0.8 / 02-Jun-2004)

12.	Version 11 headers: Correct DETTYPE having blank detector string. Remove path from “CORRECT:”, “WARPFIL:” and “DARK   :” lines.

Override-able settings:

13.	Correct frame headers collected on systems where the phi axis was configured to rotate in the wrong direction (Phi should rotate clock-wise).

14.	Correct frame headers taken with improper fixed angle settings.

15.	Correct frame headers taken with improperly aligned scan axis.

[x] Fix known header issues:	Automatically checks for known issues listed above and fixes them.

[x] Update description fields:	Overrides frame header items with values in “Import defaults: Descriptions” tab.

[x] Update x-ray fields:	Overrides frame header items with values in “Import defaults: X-ray” tab.

[x] Update detector distance, center, mounting fields.

Overrides frame header items with values in “Import defaults: goniometer and detector” tabs.

Update axis

Axis:	Axis number to reset. Set to 0 to skip this feature.

[ ] Negate	Check to negate this axis’ values inside frame header

Value:	Fixed axis value for non-motorized axis.

Starting axis value for motorized axis.

This feature is particularly useful for manually adjustable chi stages, where a scan series was collected while the program contained the wrong fixed chi setting.

As the program executes, FRMFIX will display messages stating what was fixed or the message:

frame.000: Frame header is OK; no fix-up was required.


Tab: convert orientation

Allows one to change the readout orientation option after collecting frames. The Bruker readout convention is that frame are view from the sample to the detector face with “up” direction being the goniometer “up” direction. For horizontally mounted goniometers, “up” is vertically up. For vertically mounted goniometers, frame “up” is horizontal.

Usually, this option is rarely used. Bruker manufacturing may use it when setting up detectors. Once the orientation is correctly save in BIS’ BrukerInstrument.ini configuration file, you will no longer need this tab control.

Note: Very useful for PROTEUM detectors, which have strange mounting options.


Tab: apply corrections

Allows one to apply corrections after collecting a data set. Useful when flood is accidentally set to LINEAR or to the wrong flood field table. Frames are corrected and saved with the same file name, but the original frame files are save with a *.bak extension.

Accuracy: If the old flood was LINEAR, the accuracy is 100% identical to BIS applying the correct flood field table. Otherwise, the accuracy is within 1 ADU (additional noise added) for flood or 2 ADU for dark or dark/flood.

Usage: Copy your old and new correction files (darks and floods) to the same folder as your frame set. Place check marks next to the corrections that you wish re-applied. Enter the filenames for the requested fields. Press “Process” button.

Dark current

Old	Select the old dark current or select NULL.

New	Select the old dark current or select NULL.

Flood field

Old	Select the old flood field table or select LINEAR.

New	Select the new flood field table or select LINEAR.

Spatial

New	Spatial only updated the spatial filename in the frame header. It does NOT unwarp your image.


Tab: unwarp frames

Allows one to apply unwarping correction after collecting a data set. Frames are unwarped and saved with the same file name, but the original frame files are save with a *.bak extension. (added in 1.0.0.8 / 02-Jun-2004).

Accuracy: For single crystal data frames, one achieves the most accurate results when reflections are harvested off the raw images, and then this list of reflection positions are corrected for spatial distortion. This is the tactic used by all Bruker data reduction programs, such as SAINT. As many third party packages only handle fully corrected images, Bruker provides a means of unwarping a frame or set of frames for importing into these third party packages. Just don’t expect the reflection positions to be as accurately determined as from SAINT.

Usage: Copy your spatial correction file (*._ix) to the same folder as your frame set. For older spatial tables, the effective hole spacing is missing from the *._ix file and must be recalculated using the detector constants: PixelsPerCm and CmToGrid. For version 6 or 7 spatial files,  the ._ix file contains all information needed to regenerate the spatial correction tables and the detector constants are not used. Be safe and enter your detector constants, select your spatial index file (._ix) and press [Load] button. The spatial indexes are read and the spatial correction table is generated. For older spatial index files, you will see the message:

Warning: Effective hole spacing is missing from spatial file (*._ix).

Assuming detector parms are correct and calculating a value.

Verify the spatial index file was taken at the same readout (framesize) as your data file or data set. For multiwire images, also verify the detector distance is the same as your data frames. Press “Unwarp” button.

Note: Unwarp frames is only available on Bruker distributed versions of this utility program. The spatial correction algorithms are considered proprietary and are not distributed. So if you rebuild FrmUtility from distributed sources, you will not have the Unwarp frames tab.


HowTo: rename frame file sets

Simply use the convert frame format tab and select your input and output filenames using wildcards. Check the same file format type as your input frame file set. When the first frame cannot be converted to the requested frame file format (because it’s already in that format) you will be prompted “ Do you wish to just rename frame files? Yes/No. Answer Yes and the frame file set filenames will be renamed.

Wildcards are permitted in filename inputs. You can use either single character wildcard '?' or multiple character wildcard '*'. You can use multiple wildcards.

You can use wildcards to change the file naming conventions as in:

    filename IN:    base*.*

    filename OUT:   base_*_*.sfrm

You can use wildcards to change the number of characters in frame number field.

    filename IN:    base01.A??

    filename OUT:   base_01_10??.sfrm


HowTo: handle multiple frame files

Wildcards are permitted in filename inputs. You can use either single character wildcard '?' or multiple character wildcard '*'. You can use multiple wildcards.

You can use wildcards to change the file naming conventions as in:

    filename IN:    base*.*

    filename OUT:   base_*_*.sfrm

You can use wildcards to change the number of characters in frame number field.

    filename IN:    base01.A??

    filename OUT:   base_01_10??.sfrm


HowTo: unwarp multiple frame files

FrmUtility cannot unwrap frame images. For Bruker frame file formatted files, use either GADDS or SMART to unwarp your frames. For Bruker/BIS, use APEX2 or collect your frames unwarped.


HowTo: convert frame file format in batch files

Converting file frame format within a batch file is rarely done. Currently, FrmUtility does not operate in batch mode, only in GUI mode. See Frm2Frm.exe, which while older, still runs in batch mode (all commands can be given on the command line).


Appendix B: Bruker ASCII Frame File Format

Frame header is written with <CR> <LF> termination and the frame data is written in column format. The number of columns in the ASCII file is dependent upon the maximum pixel value for that frame. The possibilities are:

Columns	Characters	MaxValue

5	16	2 to the 32nd power

8	10	999,999,999

10	8	99,999,999

11	7	9,999,999

13	6	999,999

16	5	99,999

20	4	9,999


Release notes

FrmUtility release notes:

  Replaces the older Frm2Frm, FrmFix, and FrmRename utilities.

History:

1.0.1.4 05-Oct-2004

Fixed issue of new TITLE[7] overwriting NCOUNTS line.

1.0.1.3 24-Aug-2004

Fixed compilation switch so “Unwarp” is working again (Load issue).

1.0.1.2 08-Jul-2004

Fixed Tab Fixup headers: Added issue #12. Fixed issue #3 and #9.

1.0.1.1 01-Jul-2004

Fixed writing 2-byte, new format BIS files.

1.0.1.1 29-Jun-2004

Fixed ASCII format to read headers with nulls and <ctrl-z><ctrl-d> characters.

1.0.1.0 16-Jun-2004

Fixed DETTYPE issues in update header tab.

Fixed counts correcting to negative value in re-apply corrections tab.

1.0.0.9 04-Jun-2004

Minor changes: Corrected header lines for DARK, CORRECT for re-apply corrections tab.

1.0.0.8 02-Jun-2004

Added unwarp frames tab and update headers tab.

1.0.0.8 27-May-2004 (internal release)

Fixed overflow table pre-cleared to zeros (SAINT issue) in Bruker/BIS format.

1.0.0.7 19-May-2004

Fixed using “?” as wildcard character in filenames.

1.0.0.6a 05-Mar-2004

1.0.0.6 18-Feb-2004

        Fixed issue with Browse button and invalid project folder (Browse refused to display).

        Added simple rename file set feature to Format convert routine.

        Fixed handling BIS format frame file when overflow table is completely full.

        Fixed stray null character in frame header when converting between the two Bruker formats.

        Added monochromator angle and roll to frame header fix-up tab.

1.0.0.5 21-Jan-2004

        Fixed issues with nested tab controls.

        Added MOSFLM support to file format conversion tab.

        Added frame header fix-up tab.

1.0.0.4 06-Jan-2004

        Added Reapply corrections tab.

1.0.0.3 16-Dec-2003

        Added Orientation tab.

1.0.0.2 10-Oct-2003

        Limited second release (minor fixes).

1.0.0.1 17-Mar-2004

        Limited first release to easily default header values when importing SPEC files.

Frm2Frm release notes:

History:

  1.0.20 27May04

        Fixed handling “?” wildcards.

        Fixed for older frame headers with missing header lines.

        Fixed pre-clearing overflow tables to zero (for SAINT).

  1.0.19a 05Mar04

        Fixed access violation when reading underflow tables.

  1.0.19 18Feb04

        Fixed handling BIS format frame file when overflow table is completely full.

        Fixed stray null character in frame header when converting between the two Bruker formats.

        Added monochromator angle and roll to frame header fix-up tab.

  1.0.18 06Jan04

        Added support for writing Bruker/BIS file format and half-size too.

        Compatible with FrmUtility 1.0.0.4/06-Jan-2004

  1.0.17 05Mar03

        Added support for reading Roper SPEC (*.spe) and TIFF (*.tif) files.

        Added user defaults for missing header items in Registry.

        GUI only: Allow changing user header defaults.

        Note: Console version uses these Registry user header defaults too.

  1.0.16 09Dec02

        New feature to Trim imported frame type (TIFFs) dimensions to Bruker

          supported frame dimensions (512, 1024, 2048, 4096, etc.)

          Console: Added "/T" command line switch.

          GUI: Added [] Trim to Bruker dimensions.

  1.0.16 28Oct02 (beta2)

  1.0.16 05Sep02 (beta)

        Added support for reading Bruker new frame format (PROTEUM).

        Added JPEG min and max input for re-scaling the output image.

        GUI only: Improved support for using wildcards in file specs.

          Now supports multiple wildcards of '*' and/or '?'.

          Now supports renaming filename conventions by using wildcards.

  1.0.15 29Jan02

        Bug fix for reading ASCII frame formats. Sometimes extra counts were

        read as zero, especially in 11I7 formatted counts.

  1.0.14 11Jan02

        Added a second TIFF output for non-CHESS TIFF files. Adds more tags to

        the TIFF header.

        Added support to read ASCII frame format files.

        Added warning for PROTEUM frame formats.

  1.0.13 21Aug01

        Improved APS import support. Fixed reading some images (data section).

  1.0.12 14May01

        Improved APS import support. Added support for "beamlinename", etc.

  1.0.11 22Dec99

        Added the importing frame parms of CMTOGRID and PIXPERCM.

  1.0.10 09Apr99

        Enhanced APS support (second pass at reading this file format).

        (used frame from Quantum4 CCD at ALS).

        Reads only the first frame image of 4 in the Quantum4 file.

  1.0.09 18Jan99

        Allow opening readonly files as input frames (ie. off DVD/CDROM).

        Enhanced TIFF support to read MMX/MarCCD TIFFs.

  1.0.08 19Oct98

        Enhanced TIFF support to read monochrome TIFFs stored by strips (ugly).

        Added support for JPEG output images as option number 5.

        Code now compiles into console or gui version of FRM2FRM.

        Note: GUI version supports file drag and drop (from NT Explorer).

          Dialog Input: finding project directories is n.y.i.

          File finder window is not centered

          Abort button is not yet implemented

          On error, change title bar to read is not yet implemented

  1.0.07 19Aug98 Added "/Z" option switch (applies only to reading non-Bruker

        frame file formats, such as APS or TIFF).

  1.0.06 27May98 Corrected handling of filename wildcard characters.

  1.0.05 24Apr98 Added reading APS frame formats. This is first pass at reading

        APS frames, so several frame header items may be incorrect or missing.

  1.0.04 13Apr98 Enforce minimum overflow table size of 512 bytes.

  1.0.03 09Dec97 Handle frames with LINEAR scaling feature in frame header.

  1.0.02 01Oct97 Bruker AXS release.

  1.0.00 27May97 first version to replace SHRINK & TOASCII utilities.

        Eventually FRM2FRM will replace FRMFIX & TOSAXII utilities.

FrmFix release notes:

History:

  1.108  04-Dec-01  Fixes frames collected with phi axis rotating (incorrectly)

                    CCW. Negating the phi angle will correct this problem.

  1.107  17-Apr-01  Fixes unreasonable scan times from external triggers.

                    (sets ELAPSDA & CUMULAT to ELAPSDR value).

         04-Apr-01  Fixed /value switch

  1.106  unreleased Fixed angular modulus bug (phi=400 is 80).

  1.105  01-Sep-99  Fixes "OCTMASK" frame header items from SMART frames.

  1.104  16-Oct-97  Fixes "LINEAR" frame header item number one.

  1.103  01-Oct-97  Bruker AXS release.

FrmRename release notes:

History:

  Unknown.


Help menu commands

The Help menu offers the following commands, which provide you assistance with this application:

Help Topics	Offers you an index to topics on which you can get help.
About FrmUtility	Displays the version number of this application.


File Open command
Open command (File menu)

Use this command to open an existing document in a new window.  You can open multiple documents at once, by using this command multiple times.  Use the Window menu to switch among the multiple open documents.  See Window 1, 2, ... command.

Shortcuts

Toolbar:

Keys:	CTRL+O


File Open dialog box

The following options allow you to specify which file to open:

File Name

Type or select the filename you want to open.  This box lists files with the extension you select in the List Files of Type box.

List Files of Type

Select the type of file you want to open:

All Files (*.*).

Drives

Select the drive that stores the file that you want to open.

Directories

Select the directory that stores the file that you want to open.

Network...

Choose this button to connect to a network location, assigning it a new drive letter.


Index command (Help menu)

Use this command to display the opening screen of Help.  From the opening screen, you can jump to step-by-step instructions for using FrmUtility and various types of reference information.

Once you open Help, you can click the Contents button whenever you want to return to the opening screen.


Using Help command (Help menu)

Use this command for instructions about using Help.


About command (Help menu)

Use this command to display the copyright notice and version number of your copy of FrmUtility.


Help Using Help Command
Context Help command

Use the Context Help command to obtain help on some portion of FrmUtility.  When you choose the Toolbar's Context Help button, the mouse pointer will change to an arrow and question mark.  Then click somewhere in the FrmUtility window, such as another Toolbar button.  The Help topic will be shown for the item you clicked.

Shortcut

Keys:	SHIFT+F1


Move command (Control menu)

Use this command to display a four-headed arrow so you can move the active window or dialog box with the arrow keys.

Note:  This command is unavailable if you maximize the window.

Shortcut

Keys:	CTRL+F7


System Minimize Command
Minimize command (application Control menu)

Use this command to reduce the FrmUtility window to an icon.

Shortcut

Mouse:	Click the minimize icon [image] on the title bar.

Keys:	ALT+F9


Maximize command (System menu)

Use this command to enlarge the active window to fill the available space.

Shortcut

Mouse:	Click the maximize icon [image] on the title bar; or double-click the title bar.

Keys:	CTRL+F10 enlarges a document window.


Close command (Control menus)

Use this command to close the active window or dialog box.

Double-clicking a Control-menu box is the same as choosing the Close command.

Note:  If you have multiple windows open for a single document, the Close command on the document Control menu closes only one window at a time.  You can close all windows at once with the Close command on the File menu.

Shortcuts

Keys: 	CTRL+F4 closes a document window

ALT+F4 closes the map document window or dialog box


Restore command (Control menu)

Use this command to return the active window to its size and position before you chose the Maximize or Minimize command.


Switch to command (application Control menu)

Use this command to display a list of all open applications.  Use this "Task List" to switch to or close an application on the list.

Shortcut

Keys:	CTRL+ESC

Dialog Box Options

When you choose the Switch To command, you will be presented with a dialog box with the following options:

Task List

Select the application you want to switch to or close.

Switch To

Makes the selected application active.

End Task

Closes the selected application.

Cancel

Closes the Task List box.

Cascade

Arranges open applications so they overlap and you can see each title bar.  This option does not affect applications reduced to icons.

Tile

Arranges open applications into windows that do not overlap.  This option does not affect applications reduced to icons.

Arrange Icons

Arranges the icons of all minimized applications across the bottom of the screen.


No Help Available

No help is available for this area of the window.


No Help Available

No help is available for this message box.

<< If you wish to author help specific to each message box prompt, then remove the AFX_HIDP_xxx values from the [ALIAS] section of your .HPJ file, and author a topic for each AFX_HIDP_xxx value.  For example, AFX_HIDP_INVALID_FILENAME is the help topic for the Invalid Filename message box. >>


Appendix A   	Area Detector Frame Formats

Bruker has used several different frame file formats over the years. These are:

•	Bruker fixed-format/free-line frame image file.

•	Bruker fixed-format frame image file.

•	XENGEN frame image file.

By reading the first 240 characters of the file, you can identify the file format.

A-2 Bruker Fixed-Format/Free-Line Frame Format

In 2000, Bruker updated the frame file format, by adding additional header information and improving the file compression scheme. This frame file format is often called the BIS/PROTEUM format.

Bruker software will use the combination of the below compression options which produces the smallest file.

•	Subtracting or not-subtracting the baseline.

•	Compressing the 4-byte image to 1-byte with overflows as 255, 2-byte image with overflows as 65535, or leave as 4-byte image.

•	No underflow table, 1- byte underflow table, or 2-byte underflow table.

•	No overflow table, 1-byte overflow table, 2-byte overflow table, or both 1-byte and 2-byte overflow tables.

At the top level, a frame in Bruker format can be represented as:

Header

Compressed image data

Underflow data

Overflow data

Overflow data

Trailer

Header

The header information is essentially identical to the Fixed-Format Frame Format with these changes:

•	FORMAT: is 100, instead of 86.

•	VERSION: is 11 (was 1 in beta release).

•	HDRBLKS: The restriction that the number of header blocks is a multiple of 5 has been eliminated.

•	The 72-character data for each header line is in free-format. All white space is spaces (no tabs, nulls, linefeeds, etc).

•	Additional header items as identified by version 11. [See A-3 Fixed-Format Frame Format tables]

Image

The image data is a simple byte stream (no record delimiters) with one, two, or four bytes per pixel, as defined in the header. If the data are two bytes per pixel, the least-significant byte is first.

The order of the pixels in the file corresponds to the display of pixels on a screen, like the raster-scan order of a CRT display. The first pixel in the file corresponds to the upper-left corner of the display, the 512th to the upper right, and the last pixel to the lower right.  This data ordering convention is the one used by most display devices and by the X-Windows library. Frames display as if viewed from the source toward the detector.

Underflow table

After subtracting the CCD baseline, any negative or zero pixels are stored in an underflow table. The number of underflow entries is stored as first value of the NOVERFL: header line. The byte size of the underflow table is stored as second value of NPIXELB header line.

The underflow table is stored in binary 1-byte or 2-byte format immediately following the compressed image data. The underflow block is padded with zeros to a multiple of 16-bytes.

Overflow table(s)

The number of 1-byte overflow entries is stored as the second value of the OVERFL: header line. The number of 2-byte overflow entries is stored as the third value of the OVERFL: header line.

Each overflow table is stored in binary 2-byte or 4-byte format immediately following the underflow table. Each overflow block is padded with zeros to a multiple of 16-bytes.

Uncompression algorithm

•	Read first 240 bytes of header.

•	Is this a Bruker frame file?

•	Which FORMAT?

•	Which VERSION?

•	Get header block size from HDRBLKS: The total size is 512 * hdrblks in bytes.

•	Read entire header.

•	Get image block size from NPIXELB. The total size is nbytes * nrows * ncolumns.

•	Read image block.

•	Get number of underflow entries from NOVERFL and size of underflow table from NPIXELB. The total size is nbytes * nentries padded to a multiple of 16.

•	Read underflow table.

•	Get number of 2-byte overflow entries from NOVERFL. The total size is 2 * nentries padded to a multiple of 16.

•	Read 2-byte overflow table.

•	Get number of 4-byte overflow entries from NOVERFL. The total size is 4 * nentries padded to a multiple of 16.

•	Read 4-byte overflow table.

•	Expand 1-byte or 2-byte image to a 4-byte image.

•	Sequentially loop over all pixels

•	1-byte image: Replace any 255 pixel with next 2-byte overflow value (which may be 255 or 65535).

•	1-byte or 2-byte image: Replace any 65535 pixel with next 4-byte overflow value (which may be 65535).

•	All images: Replace any 0 pixel with next underflow value. (not applicable to multi-wire images).

•	Add baseline. (not applicable to multi-wire images).

Note: Either apply underflow or baseline, but not both to same pixel.

A-3 Bruker Fixed-Format Frame Format

The Bruker format addresses issues of data portability, speed of image I/O and display, and storage of all the data acquisition conditions required to reduce the data. Header and overflow information are stored in portable ASCII, rather than binary. Critical data, such as setting angles, can thus be stored portably as formatted floating-point values. The pixel values themselves are binary, but they are assured to start on a 512-byte boundary for quick, easy access (using Byte IO routines), and they are stored as a byte stream without delimiters of any kind.  This format is completely transportable between all computers and networks, including PCs, NT workstations, and SGI systems. The only coding difference on these systems is that big-endian systems such as SGI must byte-swap the pixel values in the (relatively rare) case where it encounters a 16-bit frame.

Up to 32 bits/pixel are supported, although frames are stored where possible as 8 or 16 bits per pixel with an overflow table like that on earlier systems (but this overflow table is ASCII, as described below). BYTE ORDER OF PIXEL VALUES IN FRAMES WHICH ARE STORED IN THIS FORMAT ON DISK, TAPE, ETC. IS ALWAYS "LITTLE-ENDIAN" (LSB first, even though the header contains a flag indicating the pixel byte ordering).  Bruker does not support big-endian frames that otherwise look like this format.  The 16-bit format is fully implemented. If more than 4096 overflows occur on attempted compression to 8 bits, the frame buffer will compress to 16 bits with an overflow table (the SAXS HI-STAR and SMART CCD frame buffers accumulate 32 bits/pixel internally).

At the top level, a frame in Bruker format can be represented as:

Header

Image data

Overflow table

Trailer 1

.

.

.

Trailer N

Header

The header is 1) typable ASCII and 2) an even multiple of the 512-byte disk block size. Each entry in the header is an 80-byte unterminated ASCII line. Thus, the header size is always a multiple of 5 disk blocks to hold an integral number of lines. The first eight characters of each item contain the item name, with the remaining 72 characters for ASCII data. Thus, the organization of the header can be represented as:

HEADER

Item_name1 (8 char): Item_Data1 (72 chars)

Item_name2 (8 char): Item_Data2 (72 chars)

.

.

.

Item_nameN (8 char): Item_DataN (72 chars)

This organization has several advantages. First, fast random access can be performed on the header to pull out or rewrite an individual entry. During random access, the item names provide a method for checking for corruption of the header block.

Second, frames are actually TYPEable on both PCs and workstations if the screen wraps at 80 columns. The padding to a multiple of 5 disk blocks contains ASCII dot characters. The last characters of the padding are a CTRL+Z and a CTRL+D. This convention provides a "warning indicator" on a workstation during which a CTRL+S or CTRL+C can be issued, before the binary pixel values start to appear. On a PC, an MS-DOS TYPE command stops when it hits the CTRL+Z.   Presence of the item names makes the output easily interpretable.

Third, the format is highly portable, because different byte and word ordering conventions don't enter into the interpretation of ASCII data. Items currently contained in the header are listed below in positional order. The format is expandable. New information to be added to the header will always be added at the end. A version number is present at the start of the header so programs can deal with new header information.

The old header items are:

Mnemonic	Offset	Version	Type	Description
FORMAT :	0	1	Int	Frame format. Always “86” or "100" for Bruker-format frames. 86 means old frame compression format (see A-3). 100 means new image compression format (see A-2).
VERSION:	1	1	Int	Header version #, such as: 1 to 10 means old fixed format/fixed-line header (6 is obsolete). 11 means old fixed format/free-line header (see A-2). 101 for new free-format header (see A-3). Note: Version 11 is typically only with FORMAT 100. Note: FORMAT: 100 VERSION: 1 were early beta software. These are actually version 11 headers.
HDRBLKS:	2	1	Int	Header size in 512-byte blocks, such as 10 or 15.
TYPE   :	3	1	C	String indicating king of data in the frame.  Valid primary types are: BIS uses: FLOOD FIDUCIAL PLATE UNWARPED UNWARPED LINEAR Unknown Axis Scan Image Two-Theta Axis Scan Image Omega Axis Scan Image Phi Axis Scan Image Chi/Kappa Axis Scan Image Older Bruker software uses: DEFAULT Add frame Rotation frame SCAN FRAME UNWARPED UNWARPED LINEAR FLOOD FRAME FLOOD TABLE FIDUCIAL PLATE BACKGROUND <A> & <B> COMBINATION POLE FIGURE, [POLAR | STEREO | WULFF] STRESS, SCHEME Sometimes the primary type is appended with CALIBRATED FIBER LPA MULT_FF PLATE SMOOTHED Pole figure type may be appended with: INTERPOLATED INVERTED NORMED ROTATED SCHEME SYMMETRIZED TILTED
SITE   :	4	1	C	Site name, from Edit > Configure > User settings
MODEL  :	5	1	C	Diffractometer model, from SAXI$ADMODEL or INI file
USER   :	6	1	C	Username, from Edit > Configure > User settings
SAMPLE :	7	1	C	Sample ID, from Project > New/Edit
SETNAME:	8	1	C	Basic data set name
RUN    :	9	1	Int	Run number within the data set
SAMPNUM:	10	1	Int	Specimen number within the data set
TITLE  :	11-18	1	C	User comments (8 lines)
NCOUNTS:	19	1,9,10	1: Int 9: 2 Int 10: 5 Int 11: 2 Int	Total frame counts (followed by reference counts in Ver 9).  9: Adds direct-beam monitor counts to NCOUNTS line 10: Adds baseline offset [MultiWire: 0, CCD: 32 or 64], CCD experimental temp*100 C, and detector temp *100 C. Note: baseline offset also in NEXP line.
NOVERFL:	20	1	Int 11: 3 Int	Number of overflows when compression frame. This has nothing to do with CCD chip overflows when collecting a frame. 11: Number of underflows (-1 = no baseline subtraction), Number of 1-byte overflows, Number of 2-byte overflows.
MINIMUM:	21	1	Int	Minimum counts in a pixel
MAXIMUM:	22	1	Int	Maximum counts in a pixel
NONTIME:	23	1	Int	Number of on-time events
NLATE  :	24	1	Int	Number of late events.
FILENAM:	25	1	C	(Original) frame filename
CREATED:	26	1	C	Date and time of creation
CUMULAT:	27	1	R	Accumulated frame exposure time in seconds FRAMBO/GADDS/SAXS: Adds time for all exposures in this frame. CCD & BIS:  Adds times for only correlation frames, excludes rescans and attenuated frame times.
ELAPSDR:	28	1	R	Requested time for last exposure in seconds FRAMBO/GADDS/SAXS: Typically same as CUMULAT: SMART: last image taken in frame BIS Classic: unknown BIS: NX, MX, AX, or 1X frame time (first valid time in this list)
ELAPSDA:	29	1	R	Actual time for last exposure in seconds. Uses same definition of last exposure as in ELAPSDR:
OSCILLA:	30	1	Int	Nonzero if acquired by oscillation
NSTEPS :	31	1	Int	# steps or oscillations in this frame
RANGE  :	32	1	R	Scan range in decimal degrees (unsigned)
START  :	33	1	R	Starting scan angle value, decimal degrees
INCREME:	34	1	R	Scan angle increment between frames (signed)
NUMBER :	35	1	Int	Sequence number of this frame in series (@0)
NFRAMES:	36	1	Int	Total number of frames in the series
ANGLES :	37	1	4R	Diffractometer angles( 2T, OM, PH, CH)
NOVER64:	38	1	Int 11: 3Int	Number of pixels > 64K (actually LinearThreshold value) 11: Adds number of pixels > 64K after 8x rescan and number of pixels > 64K after 8x rescan with attenuator.
NPIXELB:	39	1	Int 11: 2Int	Number of bytes/pixel, such as 1, 2, or 4. 11: Adds number of bytes per pixel in under flow table (0, 1, or 2).
NROWS  :	40	1	Int	Number of rasters in frame, such as 512, 1024, 2048, or 4096.
NCOLS  :	41	1	Int	Number of pixels/raster, such as 512, 1024, 2048 or 4096
WORDORD:	42	1	Int	Order of bytes in word (0=LSB first)
LONGORD:	43	1	Int	Order of words in a longword (0=LSW first)
TARGET :	44	1	C	X-ray target material: Cu, Mo, Ag, Fe, Cr, Co, or other.
SOURCEK:	45	1	R	X-ray source kV
SOURCEM:	46	1	R	X-ray source milliamps
FILTER :	47	1	C	Filter/monochromator setting: Such as: Parallel, graphite Ni Filter C Filter Zr Filter Cross coupled Goebel Mirrors
CELL   :	48-49	1	6R	Unit cell A,B,C,ALPHA,BETA,GAMMA
MATRIX :	50-51	1	9R	Orientation matrix (P3 conventions)
LOWTEMP:	52	1,8,9	1: Int 8: Int,3R 9: 3Int	Low temp flag. Note: Version 8 and 9 headers diverge.  8: Adds sub-mnemonic TEMP: with set point K, ramp rate deg/min,  hold time sec. 9: Adds experimental temperature in hundredths C and CCD sensor temperature in hundredths C. Note: Version 8 diverges from version 9, 10, 11.
ZOOM   :	53	1	3R	Zoom: Xc, Yc, Mag used for HI-STAR detectors: 0.5 0.5 1.0
CENTER :	54	1	2R 11: 4R	X, Y of direct beam at 2-theta = 0. These are raw center for raw frames and unwarped center for unwarped frames. 11: Raw and unwarped X, Y detector center.
DISTANC:	55	1 11+	R 2R	Sample-detector distance, cm Adds: Sample-detector grid/phosphor distance, cm
TRAILER:	56	1	Int	Byte pointer to trailer info
COMPRES:	57	1	C	Compression scheme ID, if any. Such as: NONE
LINEAR :	58	1	C	Linear scale, offset for pixel values, typically 1.0, 0.0.
PHD    :	59	1	2R	Discriminator: Pulse height settings
PREAMP :	60	1 11	R 2Int	Preamp gain setting BIS 11:  Stores preamp gain and speed for CCD chip
CORRECT:	61	1	C	Flood table correction filename, UNKNOWN or LINEAR. Note: Some BIS versions place the path here too.
WARPFIL:	62	1	C	Brass plate correction filename, UNKNOWN or LINEAR. Note: Some BIS versions place the path here too.
WAVELEN:	63	1, 8+	1: 3R 8+: 4R 11: 4R	Version 1 to 7, 9, 10: Wavelengths (average, a1, a2) Version 8+: adds beta wavelength. Version 11: adds beta wavelength.
MAXXY  :	64	2	2R	X,Y pixel # of maximum counts (from lower corner of 0,0) BIS: Has “X+1” (bug).
AXIS   :	65	3	Int	Scan axis (1-4 for 2-theta, omega, phi, chi) Default is 2. 0=none.
ENDING :	66	3	4R	Actual goniometer angles at end of frame
DETPAR :	67-68	4	6R	Detector position corrections (dX,dY,dDist,Pitch,Roll,Yaw)
LUT    :	69	4	C	Recommended display lookup table
DISPLIM:	70	4	2R	Recommended display limits
PROGRAM:	71	4	C	Name and version of program writing frame, such as: SAXS for WNT  V4.0.07 BIS V1.1.11 & BCP 1.1.10
ROTATE :	72	5	Int	Nonzero if acquired by rotation of phi during scan. Also if oscillates between phi limits.
BITMASK:	73	5	C	File name of active pixel mask associated with this frame or $NULL
OCTMASK:	74-75	5	8Int	Octagon mask parameters to use if BITMASK=$null
ESDCELL:	76-77	7	6R	Unit cell parameter standard deviations
DETTYPE:	78	7, 8+	C 8+:C,2R 9,10: C, 5R  11: C, 2R,I,2R,I	Detector or CCD chip type (as displayed on CEU). Default is MULTIWIRE. Version 8+: adds sub-mnemonics PIXPERCM: & CMTOGRID:. If these values are missing, the defaults are: DETTYPE:        PIXPERCM:   CMTOGRID: MULTIWIRE       47.5        2.0 CCD-PXL-2K      56.02       0.8 CCD-PXL-ARR     32.00       0.4 CCD-PXL-KAF1500 51.2        0.8 CCD-PXL-L6500N  32.00       1.5 CCD-PXL-L6500F  32.00       1.5 CCD-PXL-L6000   56.02       0.3 (or 56.3,0.8?) CCD-PXL-KAF2    81.92       0.8 CCD-PXL-KAF     81.92       0.8 CCD-PXL-MSPD    81.92       0.8 CCD-PXL         81.92       0.8 CCD-LDI         83.333      0.8 CCD-MMX         Imported frames must ask for settings UNKNOWN         Imported frames must ask for settings OTHER           Imported frames must ask for settings Note: Newer detectors always have pixpercm and cmtogrid values in the frame header. Version 9,10,11: adds Pix512PerCM, CmtoGrid, 0.00, BrassHoleSpacingCm, BeWindowThicknessCm. Version 11: adds Pix512PerCM, CmtoGrid, Circular (1=Yes), BrassHoleSpacingCm, BeWindowThicknessCm, AccuratelyTimed (1=Yes). Note: Version 8 diverges from version 9,10,11
NEXP   :	79	7,9,10	7: Int 9: 2Int 10: 5Int	Number of exposures:  1=single, 2=correlated sum (followed by fixed bias ADU in Vers 9). 9: Adds per-exposure bias level in ADU to NEXP line 10: Adds baseline offset (normally 32),  Adds Orientation (value of SAXI$INVERTCCD),  Adds Overscan flag (1 if overscan used) Note: Baseline, if missing, should be defaulted to 0 for multiwires, 32 for most ccds, and 64 for 2K ccds. (see DETTYPE).
CCDPARM:	80	7	5R	CCD parameters: readnoise, e/ADU, e/photon, bias, full scale Full scale is defined differently by programs SMART: Full scale of this frame. BIS: Potential full scale if rescan and attenuator used.
CHEM   :	81	7	C	Chemical formula in CIFTAB string, such as “?”
MORPH  :	82	7	C	Crystal morphology in CIFTAB string, such as “?”
CCOLOR :	83	7	C	Crystal color in CIFTAB string, such as “?”
CSIZE  :	84	7	C	Crystal dimensions (3 ea) in CIFTAB string, such as “?”
DNSMET :	85	7	C	Density measurement method in CIFTAB string, such as “?”
DARK   :	86	7	C	Name of dark current correction or NONE. Note: Some BIS versions also stored path here.
AUTORNG:	87	7	5R	Auto-ranging: gain, high-speed time, scale, offset, full scale
ZEROADJ:	88	7	4R	Goniometer zero corrections (refined in least squares)
XTRANS :	89	7	3R	Crystal XYZ translations (refined in least squares)
HKL&XY :	90	8	5R	HKL and pixel XY for reciprocal space scan
AXES2  :	91	8	4R	Diffractometer setting linear axes (4 ea). (X, Y, Z, Aux)
ENDING2:	92	8	4R	Actual goniometer linear axes @ end of frame. (X, Y, Z, Aux)
FILTER2	93	11	2R	Monochromator 2-theta angle and monochromator roll angle.
	94			Unused lines are periods.
	95			Ends with <Ctrl-Z> <Ctrl-D> characters.
Note: Items in version 6 headers are obsolete (MICRODIF). Use FRMFIX to convert these frame headers to version 8.

Note: Version 5 & 8 items are mainly for GADDS

Note: Version 7 & 9 items are mainly for SMART

Note: Version 9 & 10 items do not add additional lines to the header, but instead appends additional values to a previously existing line.

Image Data

The image data is a simple byte stream (no record delimiters) with one, two, or four bytes per pixel, as defined in the header. If the data are two bytes per pixel, the least-significant byte is first.

The order of the pixels in the file corresponds to the display of pixels on a screen, like the raster-scan order of a CRT display. The first pixel in the file corresponds to the upper-left corner of the display, the 512th to the upper right, and the last pixel to the lower right.  This data ordering convention is the one used by most display devices and by the X-Windows library. Frames display as if viewed from the source toward the detector.

Overflow Table

The overflow table is stored as ASCII values. Each overflow entry is 16 characters, comprising a 9-character intensity and a 7-character pixel # offset. The table is padded to a multiple of 512 bytes.  In an 8-bit frame, any pixel with a value of 255 in the image needs to be looked up in the overflow table to determine its true value (even if the true value is 255, to allow overflow table validity checks, which could not otherwise be made).  In a similar manner, any pixel in a 16-bit frame with a value of 65535 must be looked up in the overflow table to determine its true value.  To look up a pixel value, compute its pixel displacement (for example, in a 512x512 frame, 512*j + k, where j is the zero-based row number and k is the zero-based column number), and compare the displacement with that of each overflow table entry until a match is found.  While the overflow table is normally sorted on displacement, it is not guaranteed to be sorted, so we recommend that you search the whole table until you find a match.


Trailers

The header contains a byte pointer (item name "TRAILER", set to zero if none) to the location in the file of any "trailer" data that has been tacked onto the image. This provision won't be used immediately, but provides later expansion capability.  For example, if a frame is derived from processing some other (parent) frame, the header of the parent could be tacked onto the processed frame as a trailer to provide processing history. The format of a trailer is:

TRAILER

Trailer size in 512-byte blocks (1 byte)

3-byte pad

Trailer data