MAN-0008 CSS Installation and User's Guide - atst.nso.edu

Project Documentation

Document MAN-0008

Rev F

CSS Installation

and

User’s Guide

Chris Berst

Software Group

December 1, 2015

CSS Installation and Users Guide

MAN-0008, Rev F i

Revision History

1. Date: February 12, 2014 Version: Draft 1 Edited by: Chris Berst

Reason for / items changed: Initial Release

2. Date: June 24, 2014 Version: Draft 2 Edited by: Chris Berst

Reason for / items changed: Modified to outline steps required to use pkgDevel for installation and configuration.

Added section providing CSS Engineering GUI overview.

Added Advanced Topics section which includes details on the parameter-set database and creating simulation data

files.

3. Date: June 30, 2014 Version: Draft 3 Edited by: Chris Berst

Reason for / items changed: Adds new cssSite.config option CSS_NAME. Description contained in Section 6.2.

Expands Section 8.7.4.2 in describing the total amount of shared memory needed.

4. Date: July 7, 2014 Version: Rev A Edited by: Chris Berst

Reason for / items changed: Title change: CSS User’s Guide CSS Installation and User’s Guide

Updated Table 1 and Section 4.1 for the Canary_7 branch of the CSS.

Removed Section 4.1.2 Installation using getAsdt.sh

5. Date: August 28, 2014 Version: Rev B (Prelim) Edited by: Chris Berst

Reason for / items changed: Section 3.2.3: Per JIRA CSS-75, removed requirement to set ATST_JNI_PACKAGES="SysShMem" in CSF

site.config file.

Per JIRA CSS-77, it is no longer required to run “make gcc_all” to get the CSS to link properly. The note to this effect

has been removed from the build instructions.

Sections 3.1.2, 3.1, 3.4: Per JIRA ATCS-815, the order of installation steps for both the CSF and CSS have been

modified to eliminate package dependencies during installation and build.

Section 4.2: Updated Figure 1 Main CSS Engineering GUI Screen. Main screen changed because of updates to Global

Control Tab and this tab is visible when GUI is started.

Section 4.5: Updated Figure 4 BDT Publication Details. Instrument Supplied Meta-data now contains two columns:

One for css.pub:metaData:fromDAT and one for css.pub:metaData:passThrough.

Section 4.7.1: Updated Figure 5 Global Control Tab and associated description due to re-layout and addition of

Observation IDs and Pass-through Meta-data text entry fields.

Added Section 5 Data Acquisition Trees. “Understanding through an Analogous Example” and “Data Acquisition

Trees by Example” was formerly contained in SPEC-0098. Use case examples were taken from TN-0158.

6. Date: October 19, 2014 Version: Rev A.1 Edited by: Chris Berst

Reason for / items changed: Section 5.3: Updates to use case drawings/descriptions and adjustments to parameters as needed to run.


Reason for / items changed: Section 4.7.4.4: Updated Figure 10 CSS Processing Meters and associated descriptions for re-layout of dialog box and

addition of the Sim Data Slice processing information. Section 4.7.5: Updated Figure 11 Simulation Control and associated description for addition of file load status raw

frame preparation status widgets. Added Section 4.7.5.2 File Load Status and Section 4.7.5.3 Preparation Status. Removed Section 6.2.2 Simulation Sub-directories. The CSS no longer requires a specific sub-directory format and no

longer requires a set of simulation data files that match the hardware applied windowing size as defined in a camera

configuration. The simulated frame-grabber now applies hardware applied windowing and binning to the source files


MAN-0008, Rev F ii

which should be sized according to the sensor size and bits per pixel of the camera hardware being simulated.

Remaining sections updated accordingly to reflect this modification.


Reason for / items changed: Section 3.2.3 Modification to site.config: Removed note regarding setting DHS parameters in the site.config file. DHS

and BDT configuration parameters are now configured via their respective pkgDevel site config files.

Moved: Section 6 Advanced Topics Section 7 Advanced Topics Added new Section 6 Java Utility Classes for Convenient Handling of CSS Metadata Updated: Section 4.2 Figure 1: Main CSS Engineering GUI Screen – Cosmetic Changes Updated: Section 4.7.1, Figure 5: Global Control Tab and associated discussion for addition of “Cancel All” and

“Abort All” control buttons in Acquisition Tree Control. Updated: Section 4.7.2, Figure 6 and Section 4.7.3 Figure 7 to reflect removal of Editors | Attribute Table tab.

Updated: Section 4.7.4, Figure 8: System Status - Cosmetic changes and addition of C++ Container Debug Slider.

Updated: Section 4.7.4.6 Debug Slider to include C++ Container debug slider.

9. Date: November 12, 2014 Version: Rev B Edited by: Chris Berst

Reason for / items changed: Updated Section 2.1 Table 1 CSS Compatibility Matrix

Updated Section 3.1 for Google Protocol Buffers 2.5.0 (Canary_8+)

Section 3.4 Completing CSF and CSS Installation – Updated steps adding pkgDevel for base and bdt.

Section 4.7.2 Editors Tab | Camera Configuration Editor – Updated Figure 6 illustrating new layout using a

JesGeneralConfiguration widget for submitting camera configuration attributes. Section 4.7.3 Editors Tab | Execution Block Editor – Updated Figure 7 illustrating new layout using a

JesGeneralConfiguration widget for submitting execution block attributes. Functionally, both editors now use their respective ID fields to enter the value of an ID to get rather than the previous

separate input field. Descriptions for above Editor Tab sections have been updated accordingly. Submitted for Approval as Rev B

10. Date: March 25, 2015 Version: Rev B.1 Edited by: Chris Berst

Reason for / items changed: This update applies to the Canary_8 branch and Canary_8-4 branch tag of the CSS repository.

Updated Section 2.1 Table 1 CSS Compatibility Matrix

Renamed Section 3.1 to “Third Party Packages: Pre CSF/CSS Installation”.

Section 3.3.2 cssSite.config Parameters – Added site config parameters CSS_CAMERA_NAME and

CSS_SIM_ENABLE.

Section 3.4: Removed ‘make install_scripts’ removed from installation instructions. This is contained as part of ‘make

build_all’

Section 3.4.1, Table 5: Added description for auto-generated file “sshConfigForRootCSS” placed in $ATST/admin/css/app when the

CSS is configured to run an Imperx Bobcat camera. Updated description for “cc_default.pset”.

Added Section 3.5: “Third Party Packages: Post CSF/CSS Installation” Section 3.5.1 contains instructions for installing the Imperx Bobcat GEV SDK, and for building and loading the

ebUniversalPro_x86_64.ko kernel module. Root access with passwordless ssh is now required. See Footnote #1 on Page 14.

Added Section 7.1.1 Default Camera Configuration. Existing section shift up in numbering by 1. Updated Section 7.1.3.4 regarding default Camera Configuration. Section3.3.2 cssSite.config Parameters, 3.6 CSS Camera Simulation Data Files, and 7.2 Simulation Data Files:

Updates throughout these sections to reflect the following change to the CSS simulation data file set:

Previously, the CSS_SimData.tgz file contained the directory and file structure of: /Andor/XxY/Andor_XyY.nn.raw

CSS_SimData.tgz has been updated to contain: /cssSimData/XxY/cssSim_XxY.nn.raw

Note that the default value for the cssSite.config parameter CSS_SIM_DATA_BASEFILENAME is now

“cssSim_2560x2160”.

Added Appendix A: DKIST Assigned Camera Names Added Appendix B: Imperx Bobcat Hardware Considerations


MAN-0008, Rev F iii

11. Date: April 1, 2015 Version: Rev C Edited by: Chris Berst

Reason for / items changed: Update to Rev B.1 as checked in on 3/25/2015 is not valid. Document requires revision change and approval. Document

submitted for official approval as Rev C.

See Revision History, Item #10, for all updates from Rev B Rev C.

12. Date: April 8, 2015 Version: Rev C Edited by: Chris Berst

Reason for / items changed: Corrected document error found by SEIC review. MS Word had replaced the text of a link with the entire text from the

linked section resulting in duplication of the text from one section of the document into another.

13. Date: July 10, 2015 Version: Rev D Edited by: Chris Berst

Reason for / items changed: This update applies to the Canary_8 branch and Canary_8-4 branch tag of the CSS repository.

Updated all Canary_8-2 references to Canary_8-4. Added Section 3.1.3: Expat (XML Parser) and Qt Tools to Section 3. CSS Installation. Section 3.6 CSS Camera Simulation Data Files: Removed references to directories 128x128 and 512x512 as these are

unnecessary file sizes and have been removed from the CSS Simulation data tar-ball. Section 5: Updated all examples in section to use a size of 2560x2160 rather than 2048x2048. Section 7.2 Simulation Data Files: Updated introduction to include details on requirements for simulation data file size

and contents and removed references to unused file sizes of 128x128 and 512x512. Section 7.2.6: Changed example size of 2048x2048 to 2072x2072.

14. Date: September 3, 2015 Version: Rev E Edited by: Chris Berst

Reason for / items changed: Reformatted Revision History.

Section 3.4: Correct problem where inserted reference was including content of reference when file is printed to pdf. Added Section 3.5.1.5 Firewalls. Steps are necessary to disable firewalls when using the Imperx Bobcat hardware. Imperx Bobcat: Extensive edits to Appendix B, Section B.4.1 Windowing and Binning. Section now includes

discussion on hardware implementation, CSS adaptation, deriving windowing/binning limits, rules and restrictions,

summary, and Hardware applied ROI application notes for a couple of use cases. NOTE: The code implemented in correlation to the edits contained in Appendix B is only available on the

Canary_8 branch and CSS trunk. It does not apply to any Canary_8-n point release.

15. Date: September 26, 2015 Version: Rev E.1 Edited by: Chris Berst

Reason for / items changed: Updates for WCI support (CSS-83) – Feature available beginning with Canary_9:

Added WCI to Table 2 Common Acronyms

Added Section 2.3 Related Documents and Drawings – References TN-0213

Section 3.3 Customizing the CSS Installation: Added defining source/update rate for wPos to list of actions that

are customized via execution of pkgDevel.

Section 3.3.2 cssSite.config Parameters, Table 4: Added World Coordinate Information related parameters

CSS_WCI_WPOS_SOURCE and CSS_WCI_WPOS_UPD_INTERVAL.

Section 4.2 Main Screen, Figure 1: Main screen now includes input fields for CSS global attributes

.global:wci:wPosSource and .global:wci:wPosUpdInterval.

Section 4.5 bdtStatus, Figure 4: System Status/Global Configuration for FPA now displays CSS meta-data for

css.pub:global:wci:wPosSource and css.pub:global:wci:wPosUpdInterval. Instrument Supplied and WCI Meta-

data now contains a column for viewing WCI meta-data obtained from css.pub:metaData:wci, converted into a

table, and displayed one attribute per line.

Added Section 7.3 World Coordinate Information

16. Date: October 8, 2015 Version: Rev E.2 Edited by: Chris Berst

Reason for / items changed: Updates to remove macros from CSS JES Screens (CSS-144)

Section 3.3.2 cssSite.config Parameters: Modified CSS_NAME to indicate how value is used with respect to the

CSS screen file location.

Section 3.4.1, Table 5: Shell Scripts: Removed warning on use of Restart script; Removed note that GUI script is

used to define the macros used by the CSS JES screens based on the users <fqvcc>.

Section 3.4.1, Table 4: Added “Resources” Section to outline expansion of JES screen .xml from CSS templates


MAN-0008, Rev F iv

into system specific production files.

17. Date: October 15, 2015 Version: Rev E.3 Edited by: Chris Berst

Reason for / items changed: Updates to fully qualify property tables cssCommon, cssGlobal, cssSimulatedCamId (CSS-146)

Section 3.4.1, Table 5: Property Databases: Modified to indicate that cssCommon, cssGlobal, and

cssSimulatedCamId have fully qualified vcc prefixes.

18. Date: November 13, 2015 Version: Rev E.4 Edited by: Chris Berst

Reason for / items changed:

Section 4.5 bdtStatus, Figure 4: Updated screenshot due to cosmetic update of screen

Updates to Section 4.2 CSS Engineering GUI Main screen (CSS-149, CSS-151)

Figure 1: Main screen layout cleaned up. Camera Name/ID background colors indicate sim/real hardware.

Figure 1: Adds “Camera Is Simulated” along with BDT camera line, topic name, transport, and max buffer size to

vcStatus event display.

Updates to Section 4.7.1 Global Control Tab (CSS-83)

Figure 5 Global Control Tab updated: Includes World Coordinate Info input fields for wPos Source and Update

Interval.

Added descriptions for World Coordinate Info fields as contained on the Global Control Tab.

Updates to Section 4.7.5 Simulation Control (CSS-126, CSS-127)

Figure 11 Simulation Control updated: Simulation control attributes are now submitted to the VCC as

<fqvcc>.sim:baseDirectory, <fqvcc>.sim:baseFilename, and <fqvcc>.sim:numFiles.

Section 4.7.5.1 Camera Data Files: Updated discussion on new attributes referencing SPEC-0098 for details.

Section 4.7.5.2 File Load Status: Clarification on “Buffer is Valid” flag and # Loaded regarding file validation.

19. Date: November 29, 2015 Version: Rev E.5 Edited by: Chris Berst

Reason for / items changed: CSS-125 Imperx Bobcat: Update drivers to 4.0.8.64

Updates to Sections 3.5.1.2 and 3.1.4: Change in Linux Kernel Module Name

ebusUniversalPro_x86_64.ko ebusUniversalProForEthernet_x86_64.ko

CSS-155 Add support for 10, 12, 14, 16-bit simulation data files

Updated Section 3.3.2, Table 4 Simulation Data Related Parameters: Added “/12-bit/2560x2160” to value listed

for CSS_SIM_DATA_PATH.

Corrected value of CSS_SIM_DATA_BASE_FILENAME to be “cssSim_2560x2160” for default CSS

installation procedures.

Added content to Section 3.6 CSS Camera Simulation Data Files regarding new simulation data file

organization. Added Table 6 which provides a cross reference between download file, bits-per-pixel, and sensor

sizes.

Section 4.7.5 Simulation Control, Figure 11: Simulation tab screenshot now shows bit-depth sub-directory.

Updated Section 7.2 Simulation Data Files and 7.2.1 Simulation Data Path regarding CSS Simulation Data

Files.

Updated Appendix A to show Sensor Size for Dkist_Generic.01.

19. Date: December 1, 2015 Version: Rev F Edited by: Chris Berst

Reason for / items changed: Updated Table 1 CSS Compatibility Matrix with CSS_Beta_1.

Updated Section 3 to use Canary_9 and CSS_Beta_1 in installation examples.

Submitted for Approval as Rev F (See revision history Rev E.1 through E.5 for modifications since Rev E)


MAN-0008, Rev F v

Table of Contents

REVISION HISTORY ................................................................................................................................................. I

TABLE OF CONTENTS ........................................................................................................................................... V

1. INTRODUCTION .............................................................................................................................................. 1

GUIDE TO THIS DOCUMENT ........................................................................................................................... 1 1.1.

2. REFERENCE ...................................................................................................................................................... 1

CSF COMPATIBILITY .................................................................................................................................... 1 2.1.

COMMON ACRONYMS ................................................................................................................................... 2 2.2.

RELATED DOCUMENTS AND DRAWINGS ....................................................................................................... 3 2.3.

3. CSS INSTALLATION........................................................................................................................................ 3

THIRD PARTY PACKAGES: PRE CSF/CSS INSTALLATION ............................................................................. 3 3.1.

3.1.1. Google Protocol Buffers ...................................................................................................................... 3 3.1.1.1. C++ Installation of Google Protocol Buffers – Canary_7 Only! ..................................................................... 3 3.1.1.2. Java Installation of Google Protocol Buffers – Canary_7 Only! ..................................................................... 4

3.1.2. Expat (XML Parser) and Qt Tools ...................................................................................................... 4

CSF INSTALLATION ...................................................................................................................................... 5 3.2.

3.2.1. Source Trees ........................................................................................................................................ 5 3.2.1.1. Installation using ‘cvs co’ ............................................................................................................................... 5 3.2.1.2. Installation with an existing ASDT ................................................................................................................. 7

3.2.2. $ATST environment variable ............................................................................................................... 7

3.2.3. Modifications to site.config ................................................................................................................. 8

CUSTOMIZING THE CSS INSTALLATION ........................................................................................................ 8 3.3.

3.3.1. VCC Fully Qualified Name ................................................................................................................. 9

3.3.2. cssSite.config Parameters.................................................................................................................... 9

3.3.3. General steps to customizing the CSS ............................................................................................... 11

COMPLETING CSF AND CSS INSTALLATION ............................................................................................... 12 3.4.

3.4.1. What did pkgDevel just do for me? ................................................................................................... 12

THIRD PARTY PACKAGES: POST CSF/CSS INSTALLATION ......................................................................... 14 3.5.

3.5.1. Imperx Bobcat GEV SDK .................................................................................................................. 14 3.5.1.1. SSH as root ................................................................................................................................................... 14 3.5.1.2. Installation of the Imperx Bobcat GEV SDK ................................................................................................ 15 3.5.1.3. Modifying system startup to load kernel module on boot ............................................................................. 16 3.5.1.4. Rebuilding kernel module following a kernel update ................................................................................... 16 3.5.1.5. Firewalls ....................................................................................................................................................... 16

CSS CAMERA SIMULATION DATA FILES ..................................................................................................... 17 3.6.

CSS STARTUP ............................................................................................................................................. 18 3.7.

3.7.1. Startup and Shutdown ....................................................................................................................... 18

4. CSS ENGINEERING GUI ............................................................................................................................... 18

TOOL TIPS ................................................................................................................................................... 19 4.1.

MAIN SCREEN ............................................................................................................................................. 19 4.2.

DATA ACQUISITION TREE STATUS (DATSTATUS) ....................................................................................... 20 4.3.

MISCELLANEOUS DIALOGS ......................................................................................................................... 21 4.4.

4.4.1. Manage IDs ....................................................................................................................................... 21


MAN-0008, Rev F vi

4.4.2. Log Viewer ........................................................................................................................................ 21

4.4.3. Property Database Editor ................................................................................................................. 22

BDTSTATUS ................................................................................................................................................. 23 4.5.

VCSTATUS ................................................................................................................................................... 24 4.6.

TABS ........................................................................................................................................................... 24 4.7.

4.7.1. Global Control Tab ........................................................................................................................... 24

4.7.2. Editors Tab | Camera Configuration Editor Tab .............................................................................. 27

4.7.3. Editors Tab | Execution Block Editor Tab ......................................................................................... 28

4.7.4. System Status ..................................................................................................................................... 28 4.7.4.1. Thread Status ................................................................................................................................................ 29 4.7.4.2. Shared Memory Status .................................................................................................................................. 29 4.7.4.3. Reload Camera HW Master on Init ............................................................................................................... 30 4.7.4.4. View Processing Time Info ........................................................................................................................... 31 4.7.4.5. Maximum Allowable # of Data-Tiers ........................................................................................................... 32 4.7.4.6. Debug Sliders ................................................................................................................................................ 32

4.7.5. Simulation Control ............................................................................................................................ 32 4.7.5.1. Camera Data Files ......................................................................................................................................... 33 4.7.5.2. File Load Status ............................................................................................................................................ 34 4.7.5.3. Preparation Status ......................................................................................................................................... 34 4.7.5.4. TRADS State ................................................................................................................................................ 35

5. DATA ACQUISITION TREES ....................................................................................................................... 36

UNDERSTANDING THROUGH AN ANALOGOUS EXAMPLE ............................................................................. 36 5.1.

5.1.1. File Rules ........................................................................................................................................... 36

5.1.2. Folder Rules ...................................................................................................................................... 36

5.1.3. Reading Assignment #1 – A File........................................................................................................ 38

5.1.4. Reading Assignment #2 – A Folder ................................................................................................... 38

5.1.5. Reading Assignment #3 ..................................................................................................................... 40

5.1.6. Reading Assignment #4 ..................................................................................................................... 41

5.1.7. CSS Execution Blocks ........................................................................................................................ 43

DATA ACQUISITION TREES BY EXAMPLE .................................................................................................... 44 5.2.

5.2.1. Accumulations Disabled .................................................................................................................... 44 5.2.1.1. Simple Camera Configuration Execution ...................................................................................................... 45 5.2.1.2. Using an Execution Block ............................................................................................................................. 47 5.2.1.3. Using Time-slices ......................................................................................................................................... 51 5.2.1.4. Defining Instrument Supplied Meta-data ...................................................................................................... 54

5.2.2. Accumulations Enabled ..................................................................................................................... 56 5.2.2.1. Example #6a – Multiple Accumulators ......................................................................................................... 58 5.2.2.2. Example #6b – Multiple Accumulators......................................................................................................... 62 5.2.2.3. Example #7 – Multiple Accumulators .......................................................................................................... 65

INSTRUMENT SPECIFIC USE CASES ............................................................................................................. 69 5.3.

5.3.1. VBI Use Cases ................................................................................................................................... 69 5.3.1.1. VBI Use Case #1 ........................................................................................................................................... 70 5.3.1.2. VBI Use Case #2 ........................................................................................................................................... 71 5.3.1.3. VBI Use Case #3 ........................................................................................................................................... 72 5.3.1.4. VBI Use Case #4 ........................................................................................................................................... 74 5.3.1.5. VBI Use Case #5 – Modulator Synchronization ........................................................................................... 77 5.3.1.6. VBI Use Case #6 – Modulator Synchronization ........................................................................................... 78


MAN-0008, Rev F vii

5.3.2. 2-D Tunable Instrument - Spectroscopy Use Cases .......................................................................... 81 5.3.2.1. Spectroscopy Use Case #1 ............................................................................................................................ 82 5.3.2.2. Spectroscopy Use Case #2 ............................................................................................................................ 84

5.3.3. 2-D Tunable Instrument - Spectropolarimetry Scenarios .................................................................. 87 5.3.3.1. Modulation Scenario #1 – No accumulations ............................................................................................... 88 5.3.3.2. Modulation Scenario #1a – No accumulations, Variation on Scenario #1 .................................................... 90 5.3.3.3. Modulation Scenario #1 with M accumulations – Option #1 ........................................................................ 93 5.3.3.4. Modulation Scenario #1 with M accumulations – Option #2 ........................................................................ 96

6. JAVA UTILITY CLASSES FOR CONVENIENT HANDLING OF CSS METADATA .......................... 98

EXAMPLE 1 – SCRUB DETECTION AND PROCESSING ................................................................................... 98 6.1.

EXAMPLE 2 – BURST INDEX MANAGEMENT................................................................................................ 98 6.2.

EXAMPLE 3 – SWITCH ON DISCRETE STATES .............................................................................................. 99 6.3.

7. ADVANCED TOPICS .................................................................................................................................... 100

PARAMETER-SET DATABASE..................................................................................................................... 100 7.1.

7.1.1. Default Camera Configuration ........................................................................................................ 100

7.1.2. Creating your own parameter-set.................................................................................................... 100

7.1.3. Parameter-set Database Category, Name, and ID .......................................................................... 101 7.1.3.1. In-file parameters ........................................................................................................................................ 101 7.1.3.2. Command-line Options ............................................................................................................................... 101 7.1.3.3. Inserting into the Parameter-set Database ................................................................................................... 101 7.1.3.4. Defining Your Own Default Camera Configuration ................................................................................... 102 7.1.3.5. Verifying Database Contents ...................................................................................................................... 102

SIMULATION DATA FILES ......................................................................................................................... 103 7.2.

7.2.1. Simulation Data Path ...................................................................................................................... 103

7.2.2. Base Filename ................................................................................................................................. 104

7.2.3. # of Files Per Set ............................................................................................................................. 104

7.2.4. Final Filename Format ................................................................................................................... 104

7.2.5. File Sizes ......................................................................................................................................... 104

7.2.6. Example ........................................................................................................................................... 104

WORLD COORDINATE INFORMATION ........................................................................................................ 105 7.3.

7.3.1. Configuring via cssSite.config ......................................................................................................... 105

7.3.2. Configuring programmatically ........................................................................................................ 105

7.3.3. WCI Acquisition and publication .................................................................................................... 105

APPENDIX A DKIST ASSIGNED CAMERA NAMES ................................................................................. 107

APPENDIX B IMPERX BOBCAT HARDWARE CONSIDERATIONS .................................................... 109

B.1 NETWORK INTERFACE ADAPTOR .............................................................................................................. 109

B.2 NETWORK CONNECTION ........................................................................................................................... 109

B.3 CONNECTING THE CAMERA TO YOUR COMPUTER ...................................................................................... 109

B.4 OPERATIONAL NOTES ............................................................................................................................... 110

B.4.1 Windowing and Binning ....................................................................................................................... 110

B.4.1.1 Bobcat implementation and CSS adaptation ................................................................................... 110

B.4.1.2 Deriving limits ................................................................................................................................. 111

B.4.1.3 Additional rules and restrictions ..................................................................................................... 112

B.4.1.4 Binning and Windowing Summary .................................................................................................. 112

B.4.1.5 Hardware applied ROI Application Notes ...................................................................................... 113


MAN-0008, Rev F viii

Table of Tables Table 1: CSS Compatibility Matrix .............................................................................................................. 2

Table 2: Common Acronyms ........................................................................................................................ 3

Table 3: CVSROOT Export Commands ....................................................................................................... 6

Table 4: cssSite.config File Parameters ...................................................................................................... 11

Table 5: pkgDevel output for the CSS ........................................................................................................ 14

Table 6: Simulation Data Download Files .................................................................................................. 17

Table 7: Examples – Fixed Global Attributes ............................................................................................. 45

Table 8: Camera Configurations with a Single Accumulator ..................................................................... 45

Table 9: DAT "Take a Picture" Meta-data (execCount0=1) ....................................................................... 46

Table 10: DAT "Take a Picture" Meta-data (execCount0=3) ..................................................................... 47

Table 11: DAT Example #1 Meta-data ....................................................................................................... 48



Table 14: DAT Example #4a Meta-data ..................................................................................................... 52

Table 15: DAT Example #4b Meta-data ..................................................................................................... 54


Table 17: Camera Configurations with Multiple Accumulators ................................................................. 57

Table 18: Accumulation Examples – Fixed Global Attributes ................................................................... 58


Table 20: DAT Example #6b Meta-data ..................................................................................................... 65


Table 22 List of Camera Names ............................................................................................................... 107

Table 23: Imperx Bobcat B2021M ROI Origin/Size X Limits ................................................................. 113

Table 24: Imperx Bobcat B2021M ROI Origin/Size Y Limits ................................................................. 113

Table of Figures Figure 1: Main CSS Engineering GUI Screen ............................................................................................ 20

Figure 2: Manage IDs ................................................................................................................................. 21

Figure 3: Log Viewer .................................................................................................................................. 22

Figure 4: BDT Publication Details.............................................................................................................. 23

Figure 5: Global Control Tab ...................................................................................................................... 24

Figure 6: Camera Configuration Editor ...................................................................................................... 27

Figure 7: Execution Block Editor ............................................................................................................... 28

Figure 8: System Status .............................................................................................................................. 29

Figure 9: Shared Memory Info.................................................................................................................... 30

Figure 10: CSS Processing Meters ............................................................................................................. 31

Figure 11: Simulation Control .................................................................................................................... 33

Figure 12: Data Acquisition Tree Analogy – Folder Contents ................................................................... 37

Figure 13: Reading Assignment #2 ............................................................................................................. 39




MAN-0008, Rev F ix

Figure 16: DAT - "Take a picture" ............................................................................................................. 46

Figure 17: DAT Example #1 – Simple Execution Block ............................................................................ 48

Figure 18: DAT Example #2 - Simple Execution Block ............................................................................ 49

Figure 19: DAT Example #3 – Execution Block with :exec:count[i] > 1................................................... 50

Figure 20: DAT Example #4a - Execution Block with :timeSlice[i]>0.0, :timeSliceRepeats=true ........... 52

Figure 21: DAT Example #4b - Execution Block with :timeSlice[i]>0.0, :timeSliceRepeats=false .......... 53

Figure 22: DAT Example #5a – Execution Block with Instrument Supplied Meta-data ........................... 55

Figure 23: DAT Example #5b – Execution Block with Instrument Supplied Meta-data ........................... 56

Figure 24: DAT Example #6a - Multiple Accumulators ............................................................................ 58

Figure 25: DAT Example #6b - Multiple Accumulators ............................................................................ 62

Figure 26: DAT Example #7 - Multiple Accumulators .............................................................................. 65

Figure 27: DAT - VBI Use Case #1 ............................................................................................................ 71




Figure 31: DAT - VBI Use Case #5 – Modulator Synchronization ............................................................ 78

Figure 32: DAT - VBI Use Case #6 – Modulator Synchronization ............................................................ 80

Figure 33: DAT - 2-D Tunable Instrument, Spectroscopy Use Case #1..................................................... 84

Figure 34: DAT - 2-D Tunable Instrument, Spectroscopy Use Case #2..................................................... 86

Figure 35: DAT - 2-D Tunable Instrument, Spectropolarimetry Scenario #1 ............................................ 90

Figure 36: DAT - 2-D Tunable Instrument, Spectropolarimetry Scenario #1a .......................................... 92

Figure 37: DAT - 2-D Tunable Instrument, Spectropolarimetry Scenario #1, Option #1 .......................... 95

Figure 38: DAT - 2-D Tunable Instrument, Spectropolarimetry Scenario #1, Option #2 .......................... 97

Figure 39: CSS Metadata Class Diagram ................................................................................................... 98

Figure 40: Aligning the Imperx Bobcat with Spectral Lines .................................................................... 114


MAN-0008, Rev F 1

1. Introduction

This serves as an installation and users guide to the CSS. Complete installation details are documented.

An overview of the CSS Engineering GUI is presented following which is a “tutorial and examples”

section on use of CSS Data Acquisition Trees. Additionally, advanced topics including creation and

storage of CSS parameter sets and details on creating your own camera simulation data files are

presented.

Guide to this Document 1.1.

The following provides a summary overview of this document:

Section 1: Introduction

Section 2: Reference contains a reference to related DKIST materials and a glossary of acronyms.

CSS Terminology is also defined.

Section 3: CSS Installation contains complete details on installation of the CSS in conjunction

with the CSF.

Section 4: CSS Engineering GUI contains an overview of the various aspects of the CSS

Engineering GUI.

Section 5: Data Acquisition Trees presents data acquisition trees both through the use of an

analogous example and then using a progressive set of examples that builds from the simple to

complex. As examples progress, various elements of execution blocks are introduced and

illustrated.

Section 6: Java Utility Classes for Convenient Handling of CSS Metadata introduces a set of

utilities for working with CSS metadata.

Section 7: Advanced Topics presents creation of camera configuration and execution block

parameter sets for storage in the Parameter Set Database, creating camera simulation data files

that are compatible with the CSS, and World Coordinate Information support features.

Appendix A: DKIST Assigned Camera Name contains the complete list of cameras supported by

the CSS

Appendix B: Imperx Bobcat Hardware Considerations contains system installation, configuration,

and operational information specific to the Imperx Bobcat camera.

2. Reference

CSF Compatibility 2.1.

Table 1 provides a compatibility cross reference between releases of the CSS and the tags/versions of

other elements of the ASDT.

CVS Repository Branch/Tags

CSS CS Base BDT CVS Type

1 Canary_7 Canary_7 Canary_7 Canary_7 Branch

2 Canary_8 Canary_8 Canary_8 Canary_8 Branch

3 Canary_8-0 Canary_8-0 Canary_8-0 Canary_8-0 Tag on Canary_8 Branch




MAN-0008, Rev F 2

CVS Repository Branch/Tags

CSS CS Base BDT CVS Type



8 CSS_Beta_1 Canary_9 Canary_9 Canary9 Branch

Table 1: CSS Compatibility Matrix

Common Acronyms 2.2.

The following table provides a brief description of some of the acronyms used in this document:

Acronym Definition

ASDT ATST Software Development Tree – An installation of the DKIST provided software packages

and development tools.

BDT Bulk Data Transport – The DKIST 10 Gigabit Ethernet data transport layer.

CSF Common Services Framework – The ATST software framework.

CSH Camera Systems Hardware – All camera hardware including the physical detector, camera

mount and motion stages, and all inter-connects to the CSS.

CSS

Camera Systems Software – The system consisting of the software, computer, frame grabber,

and timing interface which is responsible for configuring and acquiring data from the CSH and

then processing, and publishing that data according to a supplied set of attributes as defined by

this document.

cssDevel A short-cut term for execution of “$ATST/admin/pkgDevel css”

CSV Comma Separated Values – A list of values where individual values are separated from each

other by a comma.

DAT Data Acquisition Tree – The overall controlling data structure for execution of one or more

validated camera configurations.

DHS Data Handling System – The general term applied to the DKIST data system responsible for

transport, display, and storage of data generated by various subsystems of the DKIST.

FPA Fully Processed Accumulator – A CSS accumulator which has completed the CSS data-

acquisition and processing pipeline and is ready for data publication on the BDT.

IC

Instrument Controller – An element of the Instrument Control System which is built by an

ATST Instrument team using building blocks supplied by the DKIST and is responsible for the

control of the instrument using DKIST conventions.

ICS

Instrument Control System – A major software system of the DKIST which interfaces between

the Observatory Control System and the Instrument Controllers. The ICS is responsible for

disseminating commands from the OCS to one or more IC’s, collecting responses from the IC’s

and returning status information to the OCS.

IS

Instrument Sequencer – A tool of the Instrument Controller used to execute a sequence of

instrument specific commands to control electro-mechanical components of the instrument and

to command/control the cameras associated with the instrument.

MC Mechanism Controller – A controller within an IC used to command/control electro-

mechanical or electro-optical devices.

ms Milli-seconds

OCS Observatory Control System – The OCS manages, controls, and monitors all observatory

operations through other system components of the DKIST.

TCS

Telescope Control System – The TCS provides precise pointing and guiding of the sun and

delivers a specified optical light beam down to the coudé platform based on the required target

location and tracking system, spectral region, polarization characteristics, wave front quality,

pin-holes, occulting devices, and other light beam qualities.


MAN-0008, Rev F 3

Acronym Definition

VC Virtual Camera – A general term applied to the entire camera system including the CSS and the

CSH.

VCC Virtual Camera Controller – The top level CSF controller of the CSS which provides the CSF

interface to 1) The DC of an IC 2) The Engineering GUI for a specific VC.

WCI World Coordinate Information

Table 2: Common Acronyms

Related Documents and Drawings 2.3.

1) SPEC-0098, Camera Systems Software Functional Interface Specification

2) TN-0213, World Coordinate Information and the DKIST Bulk Data Transport

3. CSS Installation

The following general steps are required to install the CSS:

1. Refer to the appropriate appendix for any system specific information based on your camera:

a. Imperx Bobcat Appendix B

2. Install any CSS specific 3rd

Party Packages.

3. Install CSF and CSS source code.

4. Customize the CSF installation and build both the CSF and CSS source trees.

5. Install any additional 3rd

Party Packages included as tools with the CSS.

6. Installation of CSS camera simulation data files.

7. Startup and execution of the CSS.

This section details each of these steps.

Third Party Packages: Pre CSF/CSS Installation 3.1.

This section contains instructions for any third party packages that you must install on your system in

order to run the CSS. The packages must be installed before attempting to build your ASDT. The current

list of third party packages is:

1. Google Protocol Buffers 2.4.1 (Canary_7 Only)

2. Google Protocol Buffers 2.5.0 (Canary_8+)

3.1.1. Google Protocol Buffers

NOTE: As of Canary_8, the CSF will ship with and install all files necessary for compiling and running

Google Protocol Buffers Ver 2.5.0. These files include the Java .jar file, libraries, C++ header files, and

the GPB Protoc compiler. This section may be skipped if you are installing Canary_8 or above.

The CSS requires installation of Google Protocol Buffers. Before proceeding with the ASDT installation

download the Google Protocol Buffers Version 2.5.0 installation package:

http://code.google.com/p/protobuf/downloads/list

File Name: protobuf-2.5.0.tar.gz Protocol Buffers 2.5.0 full source -- C++, Java, Python Featured

3.1.1.1. C++ Installation of Google Protocol Buffers – Canary_7 Only!

Use the following steps to install the protoc compiler and C++ libraries into /usr/local. See the

README.txt file included with protobuf-2.4.1.tar.gg for additional information.



MAN-0008, Rev F 4

NOTE: These steps also include saving the downloaded .tar.gz file into an archive directory which, if

desired, may be omitted:

$ su -

# cd /usr/local/src

# mkdir protobuf

# cd protobuf

# mkdir archive

# mv <path to download/protobuf-2.5.0.tar.gz> archive/.

# cp archive/protobuf-2.5.0.tar.gz .

# gunzip protobuf-2.5.0.tar.gz

# tar -xvf protobuf-2.5.0.tar

# rm protobuf-2.5.0.tar

# cd protobuf-2.5.0

Use the following commands to make, test, and install

# ./configure

# make

# make check

# make install

3.1.1.2. Java Installation of Google Protocol Buffers – Canary_7 Only!

Installation of CSF includes the appropriate Java .jar file. It is not necessary to take any further action

regarding Java installation of Google Protocol Buffers. But, if you want to install the Java portion of

Google Protocol Buffer do the following:

1. If installing on Ubuntu simply use the Ubuntu Software Center to select and install Maven.

Otherwise, download and install Apache Maven from:


2. Change to the Google Protocol Buffer Java source directory

$ cd /usr/local/src/protobuf/protobuf-2.5.0/java

3. Run the tests:

$ mvn test

4. If you use Maven to manage your builds then install the library into your Maven repository:

$ mvn install

5. If you don’t use Maven to manage your builds then build the protobuf .jar file:

$ mvn package

6. Execution of Step #5 results in a protobuf-java-2.5.0.jar file being placed in:

/usr/local/src/protobuf/protobuf-2.5.0/java/target

3.1.2. Expat (XML Parser) and Qt Tools

The CSS code suite includes support for the Imperx Bobcat camera. Regardless of whether you are going

to use the Imperx Bobocat camera hardware, when the CSS is built, libraries for all supported cameras are

compiled. Per the requirements of Imperx, the CSS requires installation of both libexpat (an XML parser

library) and Qt.

The following instructions are taken from the “Bobcat GEV Linux Installer Manual” pages 11 and 12. All

installations must be performed as root:

For CentOS/RHEL/Fedora 64-bit:

Installing Dependency Packages Command Line:

Install ‘libexpat.so.0’ Download and save: compat-expat1-1.95.8-8.el6.x86_64.

You can download from this website: http://rpm.pbone.net


http://rpm.pbone.net/


MAN-0008, Rev F 5

Search for the package, download and save the file and then run:

rpm –Uvh compat-expat1-1.95.8-8.el6.x86_64

Install Qt # yum install qt-devel.x86_64

Install qtcreator Download from http://download.qt-project.org/archive/qtcreator/2.5

Then, change the permission of the binary file and install the package:

# chmod +x <binary_file>.bin

# ./<binary_file>.bin

NOTE: In order to search which package contains the library/executable file you need, you can use the following command:

$ yum whatprovides <filename>

For example, if you want to find what package contains ‘libexpat.so.0’ you would use the following command line:

$ yum whatprovides libexpat.so.0

For Ubuntu/Debian 64-bit:

Installing Dependency Packages Command Line:

Install ‘libexpat.so’ $ apt-get install libexpat1-dev

Install Qt $ apt-get install qt-sdk

In Ubuntu:

You must have ‘apt-file’ installed to use the tool to help you search for files which are in specific packages.

$ apt-file –package-only search <filename>

For example, if you want to find what package contains ‘libexpat.so’ you would use the following command line:

$ apt-file –package-only search libexpat.so

CSF Installation 3.2.

The CSS requires the following repositories for installation and execution: cs, base, bdt, css.

In general, the installation steps as detailed in SPEC-0022-2, Section 6 apply. The following sections

provide some additional guidance geared specifically to the CSS installation in conjunction with CSF.

3.2.1. Source Trees

This section outlines the step required to install a complete ASDT along with the CSS.

Section 3.2.1.1 provides the steps as detailed in SPEC-0022-2, Section 6 specifically for CSS installation.

Instructions provided assume you will be installing:

The Canary_9 branch of cs, base.

The Canary_9 branch of bdt.

The CSS_Beta_1 branch of css.

3.2.1.1. Installation using ‘cvs co’

This section outlines the steps used to check-out source code from each of the repositories required for

CSS installation and building. Table 3 lists the export commands needed during this process to set the

repository to check out. NOTE: Follow the order listed when installing.

Repository Export Command Order

cs export CVSROOT=":pserver:[email protected]:/home/atst/src/cs"

base export CVSROOT=":pserver:[email protected]:/home/atst/src/base"

bdt export CVSROOT=":pserver:[email protected]:/home/atst/src/bdt"

http://download.qt-project.org/archive/qtcreator/2.5


MAN-0008, Rev F 6

Repository Export Command Order

css export CVSROOT=":pserver:[email protected]:/home/atst/src/css"

Table 3: CVSROOT Export Commands

1. Change directories to your desired installation directory.

$ cd /path/to/install/directory

2. Set the environment variable CVSROOT to point to a source repository. Substitute “user-name”

with your user name:

$ export CVSROOT=":pserver:[email protected]:/home/atst/src/cs"

3. After setting the repository login to CVS:

$ cvs login

4. Checkout the code in the currently exported repository using one of the following options:

a. Option #1: By default, checking out an ATST repository will result in the items from that

repository being placed into the current directory under the sub-directory “atst”. To install

into the default installation directory (/path/to/install/directory/atst) use:

$ cvs co –r <tag> atst

where <tag> is substituted with a tag value from Table 1 above.

b. Option #2: With possibly multiple ASDT releases on a single computer it is convenient to

rename the installation directory from "atst" to something else. To install into a named sub-

directory other than “atst” (/path/to/install/directory/<aName>) use:

$ cvs co –r <tag> -Pd <aName> atst

where <tag> is substituted with a tag value from Table 1 and <aName> is substituted with

the sub-directory name you want to use rather than /atst. For example, if <tag>=Canary_8-

4 and <aName>=myInstall and you issue the above command your installation will reside

in:

/path/to/install/directory/myInstall

5. Repeat steps 2, 3, 4 for the all remaining repositories (base, bdt, and css). Note that you must use

the same Option from Step 4 for all repositories.

Example for Option #1: Assume the user Joe wants to check out the tag set as listed in Row 4 of Table

1: Canary_8-4 tag of CSS; the Canary_8-4 tag of both CS and BASE; the Canary_8-4 tag of the BDT.

Joe wants to install the code into /opt. Following the steps outlined above and using Option #1 of Step 4

he would do the following:

# su – (because /opt requires root privledges)

(Step 1) # cd /opt

(Step 2) # export CVSROOT=":pserver:[email protected]:/home/atst/src/cs"

(Step 3) # cvs login

(Step 4) # cvs co –r Canary_8-4 atst

(Step 2) # export CVSROOT=":pserver:[email protected]:/home/atst/src/base"



(Step 2) # export CVSROOT=":pserver:[email protected]:/home/atst/src/css"



(Step 2) # export CVSROOT=":pserver:[email protected]:/home/atst/src/bdt"



When these steps are complete, Joe will see a new directory called /opt/atst which contains the ASDT

installation and code from the supplied repository tags.


MAN-0008, Rev F 7

Example for Option #2: Assume the user Mary wants to check out the tag set as listed in Row 8 of Table

1: CSS_Beta_1 of CSS; Canary_9 of CS and BASE; Canary_9 tag of the BDT.

Additionally, Mary wants to install the code into an “atstCode” sub-directory off of her home and, within

that sub-directory, maintain multiple ASDT/CSS/BDT installations. She wants to organize these “code

sets” based on the the CSF tag. In this case, Mary will be checking out Canary_9 of CS and BASE and

therefore wants the entire code set to reside in /home/mary/atstCode/Canary_9. First, Mary needs to

create her installation directory:

$ cd /home/mary (because this is her home directory)

$ mkdir atstCode (because this is where she wants ASDT’s)

Next, following the steps outlined above and using Option #2 of Step 4 she would do the following:

(Step 1) $ cd /home/mary/atstCode

(Step 2) $ export CVSROOT=":pserver:[email protected]:/home/atst/src/cs"

(Step 3) $ cvs login

(Step 4) $ cvs co –r Canary_9 –Pd Canary_9 atst

(Step 2) $ export CVSROOT=":pserver:mary @maunder.tuc.noao.edu:/home/atst/src/base"



(Step 2) $ export CVSROOT=":pserver:mary @maunder.tuc.noao.edu:/home/atst/src/css"


(Step 4) $ cvs co –r CSS_Beta_1 –Pd Canary_9 atst

(Step 2) $ export CVSROOT=":pserver:[email protected]:/home/atst/src/bdt"



When these steps are complete, Mary will see a new directory called /home/mary/atstCode/Canary_9

which contains the ASDT installation and code from the supplied repository tags.

NOTE: If Mary had omitted “-Pd Canary_9” in the cvs co steps above hew new ASDT installation

would have been placed in /home/mary/atstCode/atst.

3.2.1.2. Installation with an existing ASDT

Installation of the css in conjunction with an existing ASDT depends on your current installation:

If you are installing CSS in conjunction with an existing ASDT then you need only install the css

and BDT repositories. Follow the steps as outlined in Section 3.2.1.1 but only for the css and

BDT repositories.

If your existing installation already contains the BDT and the tag for the BDT in your ASDT is

not compatible with the version of css you are installing (See Table 1) you will need to perform a

complete installation (See Section 3.2.1.1).

3.2.2. $ATST environment variable

The following steps assume you are using bash as your shell.

1. Set the ATST environment variable to match the installed ASDT:

a. For the current session do:

$ cd /path/to/install/directory/atst (or …/<aName>)

$ export ATST=$(pwd)

b. To make this export permanent for the current user, add the following to the users .bashrc

file:

export ATST=/path/to/install/directory/atst (or …/<aName>

c. To make this export permanent for the entire system, add the following to /etc/rc.local

(NOTE: Using this option will require a re-boot for the change to take effect):

export ATST=/path/to/install/directory/atst (or …/<aName>

2. Add $ATST/bin to your path:


MAN-0008, Rev F 8

PATH=$PATH:$ATST/bin

3. Don’t forget to source the .bashrc file after editing.

$ source .bashrc

3.2.3. Modifications to site.config

In conjunction with the steps contained in SPEC-0022-2, Section 6.7 regarding the site.config file, a few

of the site.config parameters require specific values to be added.

$ cd $ATST/admin

$ vi site.config

baseDir=/path/to/install/directory/atst (or…/<aName>)

ATST_RELEASE_FLAG=<cs tag used for install>

ATST_PACKAGE_LIST=”base bdt css”

USE_CPP=yes

ATST_CPP_CPP_BIN=</path/to/g++4.8/or/later/compiler>

ATST_CC_BIN=</path/to/gcc4.8/or/later/compiler>

ATST_CLIB_DIRS=/usr/pgsql-9.3/lib/:</path/to/gcc/libs>:/usr/local/lib

NOTE for Canary_7 Only: ATST_CLIB_DIRS must include the path to where the Google Protocol

Buffers Ver. 2.4.1 libraries are installed. If you followed the default installation guidelines then these

libraries reside in /usr/local/lib.

The customized values entered in site.config will be applied when createDevel is executed during the

final steps contained in Section 3.4. At that time the development tools will be created and the

modifications made to site.config will be applied.

At this point, continue on to Section 3.1

Customizing the CSS Installation 3.3.

In a manner similar to customizing your ASDT installation through the use of the createDevel utility and

a site.config file the CSS is customized to your particular installation through the use of the pkgDevel

utility and a cssSite.config file. Customization of the CSS installation includes the following:

Define the Host that the CSS containers, controllers and components will be deployed on.

Set the Fully Qualified Name of your top level Virtual Camera Controller and its workers.

Set the path to your simulation data file installation (as performed in Section 3.4)

Define the Parameter-set Database Category and Name for your system.

Define a default Camera Configuration ID (optional).

Define the BDT Camera Line, Topic, and Transport protocol to be used by the CSS for data

publication on the BDT.

Selecting the camera and whether it will be simulated.

Defining the source of the wPos event and the update interval the CSS will use to monitor the

wPos event for gathering WCI meta-data.

Details on the flags associated with each of these topics are contained in Section 3.3.2 below. Section

3.3.3 outlines the steps necessary to configure cssSite.config. Section 3.4.1 outlines the results of

executing pkgDevel with your customized cssSite.config file.

NOTE: Actual execution of pkgDevel to complete the ASDT and CSS installation process is deferred to

Section 3.4 as execution of pkgDevel must be broken into a couple of steps and interleaved with

building your ASDT.


MAN-0008, Rev F 9

3.3.1. VCC Fully Qualified Name

During the course of setting parameters in cssSite.config you will be required to provide the fully

qualified name of the Virtual Camera Controller (VCC). The VCC is a Java management controller that is

part of the CSS and is responsible for receiving commands, providing responses, and managing the

actions of all additional controllers in a single instance of a Virtual Camera. Your system will be sending

commands and receiving responses from the VCC. Each instance of a VCC is ultimately responsible for

the actions of a single camera. There is a one-to-one relationship between a VCC and a camera.

The Fully Qualified Name of the top level VCC for a single instance of a DKIST Virtual Camera is

named a.b.c.vcc where:

a.b.c = Fully qualified name of your Controller that is responsible for communicating with a single

instance of a DKIST Virtual Camera.

.vcc = The CSS top level Virtual Camera Controller

By convention, the top level Virtual Camera Controller is referred to as a vcc. Therefore, a.b.c.vcc is the

fully qualified name of a single Virtual Camera Controller. If your system will be communicating with

more than one camera it is recommended that you add a numerical designator to your VCC’s Fully

Qualified Name (i.e. a.b.c.vcc1).

3.3.2. cssSite.config Parameters

Table 4 below describes the parameters contained in cssSite.config:

cssSite.config Parameters

$ATST/admin/css/cssSite.config

Option Description

Application Database Related Parameters

CSS_HOST

The name of the host (computer) from which the CSS containers, controllers, and components will be deployed. Typically, the value assigned to this option is the value reported when executing “hostname” from the command line of the target system.

CSS_HOST_DESCRIPTION

A description of the host.

NOTE: If the host definition already exists in the Application Database,

this description will overwrite the current value.

CSS_CPP_CONTAINER_NAME

The name of the CSF C++ container to be used for CSS controllers and components. It is good practice to add some type of identifier to the name to designate this as the C++ container.

Example: CB.ATST.C

See the NOTE in the next option description.

CSS_JAVA_CONTAINER_NAME

The name of the CSF Java container to be used for CSS controllers and components. It is good practice to add some type of identifier to the name to designate this as the Java container.

Example: CB.ATST.J

NOTE: If the container name you choose for the C++ and/or Java

container already exists in the Application Database then Application Database entries for your VC controllers and components will be added to those containers.

CSS_VCC_FQNAME

The Fully Qualified Name of the top level Virtual Camera Controller for a single instance of a DKIST Virtual Camera (see Section 3.3.1).

Example: If the fully qualified name of your system is atst.foo.bar then the fully qualified name of your VCC would be named atst.foo.bar.vcc.

Therefore, CSS_VCC_FQNAME=atst.foo.bar.vcc.


MAN-0008, Rev F 10



Option Description

CSS_NAME

A name to assign to a single instance of a Virtual Camera. Use this option if your system controls multiple cameras or if you want a more descriptive prefix for the CSS management scripts.

Leaving this option blank will result in the CSS management scripts, written to $ATST/bin being named:

cssUp, cssDown, cssResart, cssManage, and cssGui.

This will also result in the CSS screen files being written to:

$ATST/resources/screens/css/css/*.xml

Supplying a value to this option will replace 'css' in the aforementioned script names with the value entered.

Example:

CSS_NAME=foo will result in the following scripts being written to

$ATST/bin:

fooUp, fooDown, fooRestart, fooManage, and fooGui

This will also result in the CSS screen files being written to:

$ATST/resources/screens/css/foo/*.xml

Camera Selection and Configuration Related Parameters

CSS_CAMERA_NAME

The DKIST defined name of the camera that will be controlled by this

instance of the CSS. See Appendix A, “Table 22 List of Camera Names”

for a list of currently supported cameras.

Simulation Data Related Parameters

CSS_SIM_ENABLE

Enable/Disable camera simulation.

“yes” Configure the CSS to simulate data acquisition and processing for the camera identified by CSS_CAMERA_NAME.

“no” Configure the CSS to run the physical hardware for the camera selected by CSS_CAMERA_NAME.

CSS_SIM_DATA_PATH

The path to your simulation data files. If you followed the step outlined in Section 3.6 then this option should be set to: CSS_SIM_DATA_PATH=/your/sim/data/path/cssSimData/12-bit/2560x2160

NOTE: This parameter is only required if CSS_SIM_ENABLE=yes. However, it is recommended that you provide a valid path to facilitate switching between simulation and real camera hardware.

CSS_SIM_DATA_BASE_FILENAME

The base filename for your simulation data files. The base filename is defaulted to “cssSim_2560x2160” in the cssSite.config file and should not be changed during the course of default CSS installation procedures.

NOTE: This parameter is only required if CSS_SIM_ENABLE=yes. However, it is recommended that you provide a valid base filename to facilitate switching between simulation and real camera hardware.

CSS_SIM_DATA_FILES_PER_SET

The number of files-per-set of simulation data. By default, the CSS ships with 100 files per set. The files-per-set is defaulted to ‘100’ in the cssSite.config file and should not be changed during the course of normal CSS installation procedures.

NOTE: This parameter is only required if CSS_SIM_ENABLE=yes. However, it is recommended that you provide a valid number of files per set to facilitate switching between simulation and real camera hardware.

Parameter-set Database Related Parameters

CSS_PSETDB_CATEGORY

The Parameter-set Database Category to be used with your system. This is the system that ‘owns’ the parameter-sets. By convention, and to avoid collisions with other systems, the Parameter-set Database Category should be set to the same value as the Fully Qualified Name of your system and should be equal to a.b.c as described in Section 3.3.1.


MAN-0008, Rev F 11



Option Description

CSS_PSETDB_NAME

The initial identifying name for the parameter-sets within your category. The parameter-set name is used to group sets of camera configuration and execution blocks by task such as “default”, “observe”, “setup”, “focus”, etc. This is the default “name” that the CSS will initially use to retrieve parameter-sets from the database.

CSS_DEFAULT_CCID

The ID of the default camera configuration that will be executed when this VCC enters the ‘running’ state. If you set this value to something other than ‘cc_default’, then a camera configuration with that ID must

exist in the Parameter-set database under the Category and Name defined above.

See Section 7.1.1 for details on the CSS default camera configuration and Section 7.1.3.4 for details on defining your own default camera configuration.

Data Publication Related Parameters

CSS_BDT_CAMERALINE The BDT Camera Line assigned to your system. Valid values are 1-16.

CSS_BDT_TOPICNAME The topic name that the CSS will use to publish data on the BDT.

CSS_BDT_TRANSPORT

The BDT transport. This is the mechanism that the CSS will use to publish FPA on the BDT.

Valid values are:

“none” No BDT transport is defined or will be used. The CSS will run through the motions of data publication but no actual data publication on the BDT will occur.

“UDPv4” Configure the CSS data publisher to use Ethernet for data publication.

“shmem” Configure the CSS data publisher to use Shared Memory for data publication.

NOTE: Refer to the BDT/DHS documentation for further details on use

of “UDPv4” and “shmem” as the BDT transport protocols.

World Coordinate Information Related Parameters

CSS_WCI_WPOS_SOURCE

The source name of the wPos event that this instance of the CSS will monitor. The name provided must match the name supplied to WciWatch by the system controlling this camera in order for this camera to monitor the proper source.

Example: If the fully qualified name of your system is atst.foo.bar then

you may choose to use that name as the wPos event source name. Therefore, CSS_WCI_WPOS_SOURCE=atst.foo.bar.

NOTE: DO NOT INCLUDE .wPos as part of the supplied name.

NOTE: By default, the CSS uses a source name that does not exist in

the system and therefore will not be able to monitor a wPos event. The not collect and publish WCI meta-data.

CSS_WCI_WPOS_UPD_INTERVAL The interval (in ms) that the CSS will use to monitor the wPos source as defined in CSS_WCI_WPOS_SOURCE.

Table 4: cssSite.config File Parameters

3.3.3. General steps to customizing the CSS

The following steps are required to customize the CSS installation:

1. Copy cssSite.config.template to cssSite.config:

$ cd $ATST/admin/css

$ cp cssSite.config.template cssSite.config

2. Edit cssSite.config and set parameters according to your installation and requirements. The

cssSite.config file parameters are described in Section 3.3.2 above.


MAN-0008, Rev F 12

Completing CSF and CSS Installation 3.4.

Once the steps outlined in Sections 3.1 Third Party Package, 3.2 CSF Installation, and 3.3 Customizing

the CSS Installation are complete follow these steps to complete the installation process:

If installing the CSS in conjunction with a fresh ASDT:

$ cd $ATST

$ ./admin/createDevel --make-all

$ ./admin/pkgDevel base bdt css --init-data --init-bin

$ make build_all docs

$ ./admin/pkgDevel base bdt css --load-db --init-resources

If installing the CSS on top of an existing ASDT:

$ cd $ATST

$ ./admin/createDevel --make-all

$ ./admin/pkgDevel base bdt css --init-data --init-bin

$ make ice_clean class_clean gcc_clean jni_clean

$ make build_all docs

$ ./admin/pkgDevel base bdt css --load-db --init-resources

3.4.1. What did pkgDevel just do for me?

Upon completion of execution of pkgDevel, a number of files will be automatically generated and

installed per the parameters defined in cssSite.config. The following table outlines the files that are either

generated or simply operated on during the course of execution of pkgDevel.

WARNING: If you are re-executing pkgDevel to effect some change to cssSite.config all properties that

were previously installed will be removed and re-installed. If for some reason you have modified any

properties in the CSS property tables those modifications will be lost.

WARNING: Each time a parameter-set is inserted into the parameter-set database a new “version” is

assigned to it. Parameter-set database version numbers are a monotonically increasing integer that is

incremented each time any parameter-set is inserted in the database. Version numbers are not

incremented based on a unique Category/Name/ID combination.

NOTE: <fqvcc> in this table refers to the Fully Qualified Name of your VCC as defined by the

CSS_VCC_FQNAME option in the cssSite.config file.

CSS results from execution of pkgDevel

Filename Description

Application Database

Output directory: $ATST/admin/css/app NOTE: The contents of any *.app file are automatically written to the Application DB using $ATST/bin/AppReader

<fqvcc>.app Contains the Host, Container, and Controller definitions.

sshConfigForRootCSS

Contains the content that must be added to ~/.ssh/config that allows the CSS to start the C++ container as root. The CSS will only run the C++ container as root when the selected camera is an Imperx Bobcat with real hardware (i.e. the cssSite.config parameter CSS_SIM_ENABLE=”no”).

Shell Scripts

Output directory: $ATST/bin NOTE: Script names depend on the value of the cssSite.config file option CSS_NAME.

cssUp –or- nameUp Convenience script that will start the CSS containers, deploy the defined controllers and components, and transition the CSS through its lifecycle states all the way to ‘running’.

cssDown –or- nameDown Convenience script that will transition the CSS from ‘running’ to ‘loaded’, followed by unloading and stopping the CSS containers.

cssRestart –or- nameRestart Convenience script that performs the actions of ‘Down’ followed by ‘Up’.


MAN-0008, Rev F 13



cssManage –or- nameManage Executable script that performs all the work required by Up, Down, and Restart. Additionally, this script may be used to check the status of the CSS

containers and components via: $ xxxManage –status

cssGui –or- nameGui Use this script to start the CSS Engineering GUI.

Resources Output directory: $ATST/resources/screens/css/<name>/*.xml

NOTE: Value of <name> depends on the value of the cssSite.config file option CSS_NAME.

If you defined a value for the cssSite.config option CSS_NAME then the CSS screen files will be placed in the above named output directory where <name> is the value you assigned to CSS_NAME.

If you did not define a value for the cssSite.config option CSS_NAME then the CSS screen files will be placed in the above named output directory where <name>=”css”.

*.xml

The CSS Engineering GUI screen files customized for your specific CSS_NAME and <fqvcc> as defined in cssSite.config and placed in a directory as described above.

Note that the CSS GUI management script, written to $ATST/bin, properly accounts for the location of the screen files.

Property Database

Output directory: $ATST/admin/css/prop NOTE: The contents of these files were automatically written to the Property DB using $ATST/bin/PropertyReader

<fqvcc>.prop The CSS Top Level Management Controller properties (Java).

<fqvcc>.id.prop The CSS Camera Id Component properties (Java).

<fqvcc>.xfer.prop The CSS Transfer Controller (BDT Interface) properties (Java).

<fqvcc>.cam.prop The CSS Camera Controller properties (C++).

<fqvcc>.cssCommon.prop Properties common between all controllers.

<fqvcc>.cssGlobal.prop The CSS Global Attributes properties.

<fqvcc>.cssSimulatedCamId.prop The CSS Simulated Camera ID properties.

Dkist_Generic.01.prop The DKIST Generic Development camera properties (camera ID = 1)

ImperxBobcat.0n.prop The camera properties for the Imperx Bobcat cameras (1 ≤ n ≤ 9) which correspond to camera ID = 2 thru 10.

cssCamConfig.prop The CSS Camera Configuration properties.

cssExecBlock.prop The CSS Execution Block Attributes properties.

cssMasterListOfCameras.prop The DKIST maintained master list of cameras.

NOTE: The properties defined in cssCamConfig, cssExecBlock are inherited by both the management and

camera controller property tables. They are defined in these tables for maintenance purposes.

Parameter-set Database NOTE: Excluding “cc_default”, all parameter-sets are written, as is, to the parameter-set database. There are no interim files.

cc_default.pset

A default camera configuration has been inserted into the parameter-set database using the CSS default category and name of “css” and ”default” respectively. This camera configuration is compatible with the currently selected camera.

If the cssSite.config parameters CSS_PSETDB_CATEGORY and/or

CSS_PSETDB_NAME were set to something other than “css” and “default”, then the same default camera configuration has been inserted into the parameter-set database using the category and name you defined.

The CSS automatically configured the default camera configuration based on the sensor size of the camera specified by the cssSite.config parameter CSS_CAMERA_NAME. See Section 7.1.1 for additional details on the default camera configuration.

cc_1Hz_20ms.pset

cc_4Hz_10ms.pset

cc_4Hz_20ms.pset

Test camera configurations which are used in conjunction with a variety of test execution blocks. These are installed for engineering purposes.

Category=”css”, name=”testing”

eb_1_Test_NN.pset

eb_2_Test_NN.pset

Execution blocks used to test a variety of data acquisition tree scenarios. These are installed for engineering purposes.

Category=”css”, name=”testing”


MAN-0008, Rev F 14



NOTE: In addition to the factory camera configuration and execution blocks listed above, two templates are

provided which you are free to copy and modify for use in defining your own camera configuration and execution blocks. These templates are located in $ATST/admin/css/param/templates.

Table 5: pkgDevel output for the CSS

Third Party Packages: Post CSF/CSS Installation 3.5.

This section contains instructions for any third party packages which are provided as part of the CSS

package that you must install on your system in order to run the CSS. The packages must be installed

before attempting to build your ASDT. The current list of third party packages is:

1. Imperx Bobcat GEV SDK (Canary_8+) Only necessary if using camera hardware!

3.5.1. Imperx Bobcat GEV SDK

NOTE: This section is only applicable when the following cssSite.config parameters are configured for:

CSS_CAMERA_NAME=”ImperxBobcat.NN” (See Appendix A)

CSS_SIM_ENABLE=”no”

This section may be skipped if you are using the CSS as a simulator only (i.e. CSS_SIM_ENABLE=”yes”).

If you have followed the installation instructions to this point then a complete ASDT has been installed

and configured and is ready for execution of the CSS. Standard installation of the CSS contains ONLY

the Imperx Bobcat GEV SDK include (.h) and library (.so) files required by the CSS for compilation and

linking and will only run as a camera simulator. Included within the tools portion of your CSS installation

is the complete Imperx Bobcat GEV SDK. This SDK must be installed following the manufacturer

instructions and is required for building and loading the “ebUniversalPro_x86_64.ko" kernel module.

The basic steps required in order for the CSS to communicate with the Imperx Bobcat hardware are:

1. Be able to SSH as root.

2. Install the Imperx Bobcat SDK.

3. Modify system startup to load kernel module on boot.

3.5.1.1. SSH as root1

Execution of the CSS in conjunction with the Imperx Bobcat GEV SDK requires that the CSS be run as

root. This is a requirement of the current Imperx Bobcat GEV SDK.

The container management scripts distributed with CSF use ssh when starting containers on a host. The

cssSite.config parameters CSS_HOST and CSS_CPP_CONTAINER_NAME define the name of your C++

container and the host that it will run on. Because the C++ controller of the CSS must execute as root, this

means that the container in which they reside must also execute as root. In order to execute as root either

the CSF startContainer script must be modified to ssh as root or another mechanism utilized to permit the

C++ container to be started as root.

To this end, when the CSS is customized to run the Imperx Bobcat camera hardware the host for your

C++ container in the application database is configured to one that can be executed as root via ssh while

leaving the Java container to execute with normal user privileges. This involves two things:

1 It is anticipated that a future release of the Imperx Bobcat SDK will not require root privileges for execution. The

current approach with passwordless ssh as root is provided as a stop-gap until that point in time occurs. If, and when

that does occur, it most likely will not eliminate the necessity to have root access for installation of the Imperx

Bobcat SDK specifically as it applies to rebuilding and loading the kernel module.


MAN-0008, Rev F 15

1. Moving the C++ components and controllers to a host that can be executed as root when the CSS

is configured to run Imperx Bobcat camera hardware.

2. Configure ssh with a “host” definition that can be executed as root.

Step 1 is an automated process that occurs when pkgDevel is executed for the CSS with the

cssSite.config parameters CSS_CAMERA_NAME=”ImperxBobcat.NN”, CSS_SIM_ENABLE=”no”. In this

case, a host entry of the form “root-a.b.c” (where a.b.c is the value defined by the cssSite.config

parameter CSS_HOST) is added to the application database and the C++ controllers and components are

placed in that container. If CSS_CAMERA_NAME is not “Imperxbobcat.NN” or

CSS_SIM_ENABLE=”yes”, then the CSS C++ components and controllers are added to the application

database under the host defined by CSS_HOST.

Step 2 is a manual step you must perform. When pkgDevel is executed for the CSS with the

cssSite.config parameters CSS_CAMERA_NAME=”ImperxBobcat.NN”, the file $ATST/admin/css/app/

sshConfigForRootCSS is created. This file contains a ssh config host definition that you must add to your

~/.ssh/config file allowing the host “root-a.b.c” to be ssh’d to as root. This file is always generated when

an Imperx Bobcat camera is selected regardless of the value supplied to CSS_SIM_ENABLE in

cssSite.config.

a) As instructed in the file $ATST/admin/css/app/ sshConfigForRootCSS, copy the indicated

contents to ~/.ssh/config.

- If you ever change the value of CSS_HOST, then you must repeat Step 2. -

Once the above steps are complete, you will need to configure your system to allow for passwordless ssh

as root from your user account. There are numerous online resources available that provide instructions

on how to do this. If necessary, contact your system administrator to configure passwordless ssh as root

from your user account.

Once complete, verify that you can ssh as root to your host computer:

$ ssh root@[value supplied to CSS_HOST]

With root access now available, you may proceed to the Imperx Bobcat GEV SDK installation.

3.5.1.2. Installation of the Imperx Bobcat GEV SDK

As stated earlier, the “tools” portion of the CSS installation in your ASDT includes the Imperx Bobcat

GEV SDK installer. On completion the “ebusUniversalProForEthernet_x86_64.ko” kernel module is

loaded.

NOTE: The file $ATST/tools/x86_64/bobcat_gev/Readme contains a complete set of installation

instructions.

The following steps are required to install the Imperx Bobcat GEV SDK: Note: ‘$’ denotes a user prompt, “#” denotes a root prompt:

1. Make note of the value of $ATST:

$ echo $ATST

/path/to/your/ASDT

2. As root, execute the bobcat_gev_vX.Y.Z.run installer:

$ ssh root@yourHostname

# cd /path/to/your/ASDT/tools/x86_64/bobcat_gev/install/linux

# ls bobcat_gev*.*

bobcat_gev_vX.Y.Z.run

# ./bobcat_gev_vX.Y.Z.run

- Answer “yes” to all questions.

- Upon completion the SDK is installed to ‘/opt/imperx/bobcat’

and the kernel module has been built and loaded.


MAN-0008, Rev F 16

3. Verify that the ebUniversalPro_x86_64 kernel module is loaded in the kernel:

# lsmod | grep ebUniversalPro

ebUniversalPro_x86_64 nnnnn 0

Proceed to Section 3.5.1.3 to modify your system startup.

3.5.1.3. Modifying system startup to load kernel module on boot

At this point the kernel module is built and loaded and will remain loaded unless the system is rebooted.

To assure that the “ebUniversalPro_x86_64” kernel module loads at boot time modify /etc/rc.local

to execute the Imperx"load.sh" script for the ebUniversalPro kernel module. As root, add the following

two lines to /etc/rc.local:

# Load Imperx ebUniversalPro kernel module

echo "$(cd /opt/imperx/bobcat_gev/module; ./load.sh)"

Installation of the Imperx Bobcat GEV SDK, kernel module, and required system modifications are now

complete. The next section is only applicable following an OS kernel update.

3.5.1.4. Rebuilding kernel module following a kernel update

Anytime the kernel is updated on your system, the " ebusUniversalProForEthernet_x86_64.ko" kernel

module must be rebuilt and re-loaded. Use the following steps to rebuild and re-load the module

following a kernel update (NOTE: Rebuilding the ebUniversalPro kernel module requires root

privileges):

1. Gain root access:


#

2. Change directories to the kernel module source directory:

# cd /opt/imperx/bobcat/module

3. Unload the current ebusUniversalProForEthernet_x86_64 kernel module:

# ./unload.sh

4. Rebuild the ebUniversalProForEthernet_x86_64.ko kernel module:

# ./build.sh

5. Load the new ebUniversalProForEthernet_x86_64.ko kernel module into the kernel: # ./load.sh

6. Verify that the ebUniversalProForEthernet_x86_64 kernel module is loaded in the kernel:

# lsmod | grep ebUniversalPro

ebUniversalPro_x86_64 nnnnn 0

3.5.1.5. Firewalls

Per the “Bobcat GEV Linux Installer Manual”, :

The network firewall must be disabled when using the Bobcat GEV camera. Please talk to your network

administrator for proper protocol in disabling the firewall on your system.

To disable the firewall:

1. Gain root access:


#

2. Enter the following commands to disable the firewall:


# service iptables stop


MAN-0008, Rev F 17

# service ip6tables stop

NOTE: By default, firewalls are disabled on CentOS 6. By default, firewalls are enabled on CentOS 7.

CSS Camera Simulation Data Files2 3.6.

In order for the CSS to run in simulation mode it requires that a set of raw frame simulation data files be

installed on your system which match both the bits/pixel and sensor dimensions of the camera you want

to simulate. The CSS simulation data files are not part of the CSS repository and must be obtained from

the DKIST Project Book at http://dkist.nso.edu/inst/cameras.

On this web page you will find an assortment of links to simulation .tgz files. Each file is organized by

sensor size family (i.e. 2k ≡ 2048x2048, 2072x2072, 2560x2160) and sensor bits-per-pixel. The current

set of download files and contents are listed in Table 6 below. You will need to download the simulation

file set that matches the sensor dimensions and bits-per-pixel of the camera you want to simulate.

CSS Simulation Data File

Link Name (Download File)

Bits-per-pixel

Sensor Dimensions

2048x2048 2072x2072 2560x2160

CSS Camera Simulation Data Files, 2k 10-bit

(CSS_Sim_Data_2k-10bit.tgz)

10 X



12 X X X



14 X



16 X

Table 6: Simulation Data Download Files

If you are following the default installation of the CS then the default camera is “Dkist_Generic.01”

which simulates a generic camera with a 2560x2160 12-bits/pixel sensor. The following steps outline the

installation process for the default camera, Dkist_Generic.01:

1. Using a web browser, navigate to http://dkist.nso.edu/inst/cameras and click on “CSS Camera

Simulation Data Files, 2k 12-bit” to download the “CSS_Sim_Data_2k-12bit.tgz” file.

2. Create a directory on your file system where you would like to house the simulation data files.

You are free to choose any directory in your file system for these data files. Although not

prohibited, it is recommended that this directory reside outside of your ASDT.

$ mkdir /your/sim/data/path/

3. Copy (or move) the file “CSS_SimData_2k12-bit.tgz” to this new directory and unzip/extract

$ cd /your/sim/data/path/

$ cp /download/path/CSS_SimData_2k12-bit.tgz .

$ tar –xvzf CSS_SimData_2k12-bit.tgz

After unzipping/extracting you will have the following directory structure

/your/sim/data/path/cssSimData/12-bit/2048x2048

/your/sim/data/path/cssSimData/12/bit/2072x2072

/your/sim/data/path/cssSimData/12-bit/2560x2160

Each of the above directories contains 100 simulation data files with the corresponding x/y pixel

dimensions where each file contains no more than 12 bits-per-pixel of significance in each 16-bit pixel.

File names in each directory are of the form:

2 If you require the use of your own camera simulation data files please contact DKIST engineering for assistance.

http://dkist.nso.edu/inst/cameras

http://dkist.nso.edu/inst/cameras


MAN-0008, Rev F 18

cssSim_XxY.nnn.raw where 000 ≤ nnn ≤ 099

For example, the 51st simulation data file with raw frame pixel dimensions of 2560x2160 is:

/your/sim/data/path/cssSimData/12-bit/2560x2160/cssSim_2560x2160.050.raw

CSS Startup 3.7.

This section describes the CSS startup procedure using the tools installed as a result of execution

pkgDevel for the CSS.

3.7.1. Startup and Shutdown

The simplest mechanism to start containers, deploy components and controllers, and transition them from

‘loaded’ to ‘running’ is through use of the CSS Up, Down, and Gui scripts which have been installed in

$ATST/bin.

If you defined a value for the cssSite.config option CSS_NAME then these scripts are named: nameUp,

nameDown, and nameGui where name is the value you assigned.

If you did not define a value for the cssSite.config option CSS_NAME then these scripts are named:

cssUp, cssDown, and cssGui.

The following instructions assume that you have added $ATST/bin to your environment path and that the

value of CSS_NAME was left blank:

1. Open a terminal window.

2. Start ICE Services (if not already running):

$ startIceServices

3. Start the CSS GUI:

$ cssGui

4. To start the CSS containers, deploy components/controllers and and transition to ‘running’:

$ cssUp

5. To transition the CSS components/controllers from ‘running’ to ‘loaded’, unload the

components/controllers from the containers, and stop the containers:

$ cssDown

4. CSS Engineering GUI

The main CSS Engineering GUI screen is illustrated in Figure 1. The general concept of the GUI is to

provide general runtime status information around the outside perimeter and editing functions within the

central portion of the screen.

Note that the following discussion assumes that you are familiar with the concepts of JES (TN-0089)

widgets and the CSS Functional Interface (SPEC-0098).

The screen is divided in 6 general sections. Starting on the left hand side and working counter-clockwise

there are:

Controller Lifecycle Control, Controller Health Status, Container Health Status.

Data Acquisition Tree Status (datStatus Event).

Miscellaneous Dialogs.

Data Publication Status (bdtStatus Event).

Virtual Camera Status (vcStatus Event).

Control of CSS Global attributes as they relate to DAT execution.


MAN-0008, Rev F 19

Editors for camera configuration and execution blocks.

System Engineering displays.

Simulation control.

Tool Tips 4.1.

Many edit widgets and some status widgets provide a tool-tip feature that can be used to reveal the fully

qualified target component/controller name and target attribute for which the widget is controlling. Hover

the mouse over a widget to reveal the underlying attribute name. Specifically, this feature works with the

following widgets: Lifecycle/Health, Check Box, Combo Box, Debug Slider (target component only,

there is no attribute), Radio Box, Slider, Spinner, Text Entry. Controller Lifecycle Control, Controller

Health, Container Health.3

Main Screen 4.2.

The left-hand side of the screen contains the JES widgets used to communication controller lifecycle

states, controller health and container health. The lifecycle widgets are interactive and may be used to

transition the system through its life-cycle states. The Lifecycle Widget labeled “VC Manager” should be

used to control life-cycle actions for the entire system. Although accessible via the other lifecycle

widgets, independently transitioning any single component/controller to a new lifecycle state is not

recommended. All lifecycle transitions should occur via the “VC Manager”. The lifecycle widgets also

provide access to setting a debug category and level for their respective controller.

The Camera Name and Camera ID display the camera that has currently been configured via settings in

cssSite.config and execution of pkgDevel. The background color indicates whether the selected camera

is being simulated or is executing in real hardware: YELLOW indicates simulated, GREEN indicates real

hardware.

3 Feature is supported beginning with Canary_8.


MAN-0008, Rev F 20

Figure 1: Main CSS Engineering GUI Screen

Data Acquisition Tree Status (datStatus) 4.3.

The Data Acquisition Tree Status pane occupies the bottom portion of the screen. This pane displays the

contents of the CSS datStatus event which is posted by the CSS upon completion of data acquisition and

processing of each camera configuration in the currently executing Data Acquisition Tree. This event may

be subscribed to by your application to monitor the progress of a DAT.

Information contained in the datStatus event includes:

Number of data tiers in the executing DAT.

The currently executing Camera Configuration ID.

The data acquisition status for the current execution of the camera configuration.

The number of camera configuration that have completed in the current DAT.

The Start and Completion times for the current camera configuration.

The delta time (in ms) between the start times of two consecutive camera configurations.

The data tier information which provides you with details on where execution is currently

occurring within the context of the active Data Acquisition Tree.

Comprehensive on-line help is available for this display pane.


MAN-0008, Rev F 21

Miscellaneous Dialogs 4.4.

Several dialogs are accessible via the buttons on the right side of the screen and include Camera

Configuration and Execution Block ID Management, a Log Viewer, quick access to the Property

Database Editor.

4.4.1. Manage IDs

The “Manage IDs” dialog, shown in Figure 2, provides access to the set of CSS global attributes which

are associated with managing Camera Configuration and Execution Block IDs as contained in the

parameter-set database.

Figure 2: Manage IDs

On startup the dialog will display the default parameter-set database category and name. These values will

match the values entered for the CSS_PSETDB_CATEGORY and CSS_PSETDB_NAME parameters in

cssSite.config. Additionally, your selected default camera configuration (defined via the cssSite.config

option CSS_DEFAULT_CCID) will appear as being loaded and validated. Examination of the datStatus

pane on the main GUI will reflect that this camera configuration is executing. Comprehensive on-line

help is available for this dialog.

4.4.2. Log Viewer

The Log Viewer, shown in Figure 3, is a JES widget that provides access to the Log Database where note,

warning, and severe log messages are store. During the course of normal operations the CSS will log


MAN-0008, Rev F 22

messages to report on CSS operations and progress of DAT execution. Additionally, when debug

categories and levels are enabled, those messages are also logged and visible in this viewer.

Figure 3: Log Viewer

The Log Viewer displays the following:

timeStamp: The time that the message was logged. Resolution is to milli-second accuracy only.

source: The fully qualified name of the component or controller that logged the message

type: Denotes the type of message. Message types are color coded as follows: note A standard log message.

Warning A condition for which the CSS has determined that a warning needs to be issued but CSS operations will continue.

Severe A fatal or severe condition has been detected. This may or may not result in the CSS stopping.

Alarm An alarm condition has occurred that warrants immediate attention.

Debug A debug level > 0 has been enabled for the indicated controller and category combination.

category: A CSS defined category for the message type. Categories are used to differentiate CSS

state and functional origin for any given message.

message: The actual log message.

Log messages may be filtered using the options available on the bottom of the page.

WARNING: Executing a DAT that contains camera configurations running at a high rate may result in the Log Viewer

widget getting bogged down and can adversely affect performance of the CSS GUI.

4.4.3. Property Database Editor

Selecting this button will launch the JES Property Database Editor.


MAN-0008, Rev F 23

bdtStatus 4.5.

The bdtStatus pane provides a quick overview of the status of data publication on the BDT. This pane

receives its information from a bdtStatus event that is intended for GUI consumption only. Information

conveyed includes:

BDT Status Flag: A status flag published by the CSS with each FPA that informs the BDT on the general

state of the data being published. Valid values are:

OK Data publication is ok.

CANCEL The current DAT has been cancelled. Cancellation only occurs on or between FPA-set boundaries. The most recent FPA-set will be complete.

ABORT The current DAT has been aborted. An abort occurs at the time it is received. No further data publication will occur with the current FPA-set. The current FPA-set may be incomplete.

BDT Transient Flag: A flag which informs the BDT whether data being published should be saved.

Valid values are: true Data is transient and will NOT be saved.

false Data is not transient and should be saved.

Frame ID (short version): The unique ID assigned to each FPA published on the BDT. The complete

frame ID is visible via the “View Publication Details” button.

View Publication Details: Selecting this button displays the pane shown in Figure 4 below. The BDT

Publication Details pane contains the complete set of meta-data being published with each FPA. This

pane receives its information from a bdtDetail event that is intended for GUI consumption only.

Comprehensive on-line help is available for this display pane.

Figure 4: BDT Publication Details


MAN-0008, Rev F 24

vcStatus 4.6.

The vcStatus pane provides visibility into the contents of the vcStatus event. The vcStatus event reports

the general operational status of the Virtual Camera. The CSS generates a vcStatus event to inform other

sub-systems in the DKIST of its status. The event is generated at a rate of 1Hz or on change of any

element that it reports.

NOTE: Details on items that are available, as shown in Figure 1, can be found in SPEC-0098.

Tabs 4.7.

The central portion of the screen contains the vast majority of the interactive components of the CSS

Engineering GUI. These are broken into functional groups, each of which is contained on a tab. It is from

these tabs and the widgets they contain that you may access the complete set of .global, .camConfig, and

.execBlock attributes defined for the CSS in SPEC-0098. The first of these tabs is “Global Control”.

Unless otherwise noted, all JES widgets in the Global Control, Camera Configuration, and Execution

Block editors are configured to “submit”. Therefore, whether you type a value in an input field and press

<ENTER> or fill out a set of attributes and select “Set” or “Submit”, the attributes are submitted to the

CSS.

4.7.1. Global Control Tab

The global control tab provides access to CSS .global attributes that, for the most part, play a direct role

in execution of a Data Acquisition Tree. The Global Control tab is shown in Figure 5.

Figure 5: Global Control Tab


MAN-0008, Rev F 25

From top to bottom we have:

Observation IDs: This text entry field is used to submit to the CSS the set of IDs required by the BDT

for use in the atst namespace of the attribute table published on the BDT cameraLine of the DHS. In

order, these IDs are atst.expID, atst.obsID, and atst.groupID. To change their values enter new IDs as a

comma separated list and press <enter>. You must supply all IDs even if you desire to only change one

value. When you press <enter> the ID values will be submitted to the CSS as the attribute

.global:observationIDs.

Pass-through Meta-data: This text entry field and enable/disable check box is used to enable/disable

generic pass-through meta-data to be published in conjunction with the current FPAs. To submit the

meta-data strings, type the meta-data string(s) as a comma separated list and press <enter>. You are free

to choose the format of the strings. If you want to pass attribute/value pairs use a comma to separate the

attribute name from its value and enclose the pair in single tics (i.e. ‘a.b,100’) or escape the comma

separating the attribute name from its value (i.e. a.b\,100).

For example, if you want to set the pass through meta-data to three strings with the values “Run 1”, “Test

2” and the attribute/value pair a.b/1.5 you would enter: Run 1,Test 2,’a.b,1.5’ –or- Run 1,Test 2,a.b\,1.5

Instrument pass-through meta-data can be viewed in the Instrument Supplied Meta-data section of the

BDT Publication Details pane shown in Figure 4 of Section 4.5.

Linearity Corrections: This text entry field and enable/disable check box is used to enter a path/filename

for a linearity correction table and to enable/disable use of that table. To submit the path/filename, enter it

in the text entry field and press <enter>. Use the check box to enable/disable linearity corrections.

Reference Time: This text entry field is used to set the reference time for CSS data acquisition. Type the

required reference time in the input field (in ATST Date format) and press <ENTER> to submit the time.

Note that a change in reference time will result in the current DAT being restarted. The reference time

may only be changed when the CSS is in preview mode (.global:camMode=preview).

World Coordinate Info: The CSS will automatically attempt to gather World Coordinate Information

and include it with the meta-data being published with each FPA. World Coordinate Information is

obtained from WciWatch which listens to the TCS cPos and cStatus events and the wPos event posted by

the instrument controlling the camera.

wPos Source

The name of the wPos event to which this camera’s instance of WciWatch should listen.

wPos is posted by the entity controlling this camera. Type the name of the wPos event,

excluding “.wPos”, and press <ENTER> to submit the value and update the wPos source

event.

Update Interval

The interval, in milli-seconds, that WciWatch should attempt to update is wPos information.

Type the desired update interval and press <ENTER> to submit the value. Note that a value <

the rate that wPos is being posted by wPos source will under-sample wPos while a value >

than the rate that wPos is being posted will over-sample wPos.

Acquisition Tree Control: This portion of the screen is where you define the camera mode, start mode,

initial start time, initial camera configuration or execution block ID, and the execution count for a DAT.

Camera Mode

“preview” – When this mode is selected, the defined DAT will execute continuously. All

.global, .camConfig, and .execBlock attributes may be freely edited.

“preConfigure” – When this mode is selected, the CSS will continuously execute the first

acquireNode in the defined DAT.

“startWithSave” or “startWithoutSave” – When this mode is selected, the CSS will execute

the defined DAT according to the Start Mode and Execution Count. Once complete, or


MAN-0008, Rev F 26

cancelled or aborted, the CSS will automatically return to “preview” mode and continuously

execute the defined DAT.

If “startWithSave” is selected, then the BDT Transient Flag will be set to “false” and FPAs

published on the BDT will be saved by the DHS (i.e. data store will be enabled).

If “startWithoutSave” is selected, then the BDT Transient Flag will be set to “true” and FPAs

published on the BDT will not be saved by the DHS (i.e. data store will be disabled).

Start Mode (Only applicable when the Camera Mode equals “startWith(out)Save”):

“atStartTime” – DAT execution will begin at the defined Start Time.

“immediate” – The CSS will calculate a time, in the future, that is compatible with the

defined reference time and the exposure rate and scheduling as contained in the defined DAT.

DAT execution will begin at this calculated time.

Initial Start Time:

Use to set the time, in the future that a DAT will start. This time value is only applicable

when .global:camMode=startWith(out)Save and .global:startMode=atStartTime.

As with the reference time, type the required start time in the input field (in ATST Date

format) and press <ENTER> to submit the time. When working from the GUI, you may

want to select an initial start time that is far enough in the future to allow time to submit the

DAT start.

Initial ID:

A camera configuration ID or the first execution block ID in a Data Acquisition Tree.

Execution Count:

The number of times to execute the DAT when the Camera Mode equals “startWithSave” or

“startWithoutSave”. If the current camera mode equals “preview” or “preConfigure” then the

value supplied will have no effect.

Once you have selected the Camera Mode, Start Mode, a possible Initial Start Time (depending on the

selected Start Mode), entered an Initial ID and Execution Count, select “submit” to submit these attributes

to the CSS.

If the Camera Mode = “startWith(out)Save” and the Execution Count = 0, you must use Cancel or Abort

to return the CSS to preview mode. If the Execution Count > 0 you may either wait for the number of

DAT executions to complete at which point the CSS will return to preview mode or you can Cancel or

Abort the DAT. Note that when Camera Mode = “preview”, the cancel and abort buttons have no effect.

Hint: When Camera Mode = “startWith(out)Save” and a DAT is actively running (i.e. vsStatus Current

State = active): If you erroneously submit a new DAT to be started the CSS will reject the new

configuration because a DAT is currently active. When this happens, this control widget can no longer

cancel or abort the active DAT because the last configuration, for which it tracks, was rejected and as far

as this widget is concerned, there is no current configuration. In this case you can use the “Cancel All” or

“Abort All” buttons to cancel or abort the active DAT.

Status Area: The bottom portion of the screen consists of a status area where the CSS may write status

messages based on current actions.


MAN-0008, Rev F 27

4.7.2. Editors Tab | Camera Configuration Editor Tab

The Camera Configuration Editor tab provides complete access to the set of .camConfig attributes. This

editor is used to either completely define a new camera configuration or modify an existing camera

configuration and re-submit it to the CSS. The attributes presented are completely defined in SPEC-0098.

To populate the editor with a loaded camera configuration follow these steps:

1. Enter the “cc_xxxx” id value in the “Camera Configuration ID” input field.

2. Select the “Get” button on the lower left portion of the editor. This will populate the editor with

the requested camera configuration.

NOTE: The camera configuration to “Get” MUST be loaded in CSS memory. This can occur by:

a. Loading the ID from the Parameter-set Database via the “Manage IDs” dialog.

b. Starting a DAT from the Global Control tab and taking advantage of the “auto-load” feature

of the CSS. When a DAT is started the CSS will first examine local memory to determine

whether any ID contained in the DAT is already loaded. If the ID is not located, the CSS will

attempt to retrieve the ID and its associated attributes from the parameter-set database.

Otherwise, execution of the DAT will fail.

Figure 6 illustrates the Camera Configuration when it is populated with the CSS Default Camera

Configuration for a camera whose sensor size is 2560x2160. The ID=”cc_default”.

Figure 6: Camera Configuration Editor


MAN-0008, Rev F 28

4.7.3. Editors Tab | Execution Block Editor Tab

The Execution Block Editor tab, shown in Figure 7, provides complete access to the set of .execBlock

attributes. These attributes are used to define an execution block of a Data Acquisition Tree. The

attributes presented are completely defined in SPEC-0098.

Figure 7: Execution Block Editor

A couple of notes about the editor:

1. The ID, Execution Count, and the Time-slice vectors must each contain the same number of

values.

2. The values entered in these vectors are CSV (the syntax is illustrated directly below the input

fields).

3. Meta-data sets are also defined as CSV. The number of values in the Meta-data Sets vector

MUST be evenly divisible by the Meta-data Set Size.

4. Use the same process described in Section 4.7.2, Editors Tab | Camera Configuration Editor, to

populate the editor with a loaded Execution Block.

5. When an Execution Block is retrieved, the tabular display in the middle of the editor will

populate with the ID, count, and time-slice vector values. This is for display purposes only and is

done so in an attempt to present the information in a “friendlier” form than CSV lists.

4.7.4. System Status

The System Status tab is geared more towards engineering and contains displays and tools that provide

some level visibility into the “real-time” performance of the CSS.


MAN-0008, Rev F 29

The System Status tab is shown in Figure 8. This is a tab “in-the-making” and therefore the layout is

currently in a state of flux.

Figure 8: System Status

4.7.4.1. Thread Status

This portion of the screen is intended for displaying thread specific status/timing information. Currently it

only monitors the CSS Transfer Controller’s Google Protocol Buffer Server and Queue threads. Clicking

on “View System Thread Info” displays a list of active Java threads in the Java Container. This will

eventually be expanded to include C++ and perhaps the facilities to modify thread priorities.

4.7.4.2. Shared Memory Status

The Shared Memory Status Icon provides feedback on the number of connections to each shared memory

segment used by the CSS. The color of the icon closely mirrors the colors used in the lifecycle widget.

Icon appearance will change as follows:

The number of connections to each shared memory segment is 0.

Blue parallels the loaded state of components and controllers.

The number of connections to each shared memory segment is between 1 and 2.

Yellow generally occurs during the life-cycle transition from loaded to initialized

The number of connections to each shared memory segment is 3. All required connections are present.

A shared memory connectivity error has occurred. The error will be logged.


MAN-0008, Rev F 30

Left-clicking on the Shared Memory Status Icon will display the Shared Memory Info status screen,

shown in Figure 9. This screen displays shared memory System Limits and CSS Configuration and Status

information regarding how the CSS is utilizing shared memory.

Figure 9: Shared Memory Info

It should be noted that the CSS will always acquire the maximum amount of shared memory that may be

possibly needed. This amount is independent of the actual number of accumulator being used by any

single Camera Configuration. The total amount of shared memory needed by the CSS is:

𝑇𝑜𝑡𝑎𝑙 𝑆ℎ𝑎𝑟𝑒𝑑 𝑀𝑒𝑚𝑜𝑟𝑦 𝑅𝑒𝑞𝑢𝑖𝑟𝑒𝑑 = # 𝑜𝑓 𝑆𝑒𝑔𝑚𝑒𝑛𝑡𝑠 𝐴𝑙𝑙𝑜𝑐𝑎𝑡𝑒𝑑 × 𝐴𝑐𝑡𝑢𝑎𝑙 𝑆𝑒𝑔𝑚𝑒𝑛𝑡 𝑆𝑖𝑧𝑒

where:

𝐴𝑐𝑡𝑢𝑎𝑙 𝑆𝑒𝑔𝑚𝑒𝑛𝑡 𝑆𝑖𝑧𝑒 = (𝑆𝑒𝑛𝑠𝑜𝑟 𝑆𝑖𝑧𝑒 𝑋 × 𝑆𝑒𝑛𝑠𝑜𝑟 𝑆𝑖𝑧𝑒 𝑌 × 6) + 1024

4.7.4.3. Reload Camera HW Master on Init

This is an engineering feature that forces the CSS to re-read the master set of attributes for the camera that

this instance of the CSS is running. This only works when this button is selected and the following

Lifecycle transitions take place:

Initialized Un-Initialize Initialize

Running Shutdown Un-Initialize Initialize


MAN-0008, Rev F 31

4.7.4.4. View Processing Time Info

Selecting this button will result a pop-up screen, shown in Figure 10, to display. This screen contains a

number of processing time metrics for the CSS. Metrics are only gathered while the window is open.

Figure 10: CSS Processing Meters

A brief description of each metric follows:

Camera Controller

Sim Data:

N Slices: The number of slices(threads) being used by the simulated frame-grabber to process a

simulation data buffer and convert it into a raw frame. A simulation data buffer contains the

contents of a simulation data file and conversion to a raw frame entails application of windowing

and binning as contained in the :winBin:hw attributes of the currently active camera

configuration.

Total Processing Time (ms): The total amount of time, in milliseconds, it takes N slices (threads)

to process the simulation data buffer to create a raw frame.

Raw Frame Processing

Count: The total number of raw frames acquired since the CSS entered the running state.

Raw Frame dt(ms): The delta time, in milliseconds, between consecutively acquired raw frames.

N Slices: The current number of slices (threads) being used to process a raw frame. This number

will change based on the current camera configuration.


MAN-0008, Rev F 32

Total Processing Time (ms): The total amount of time, in milliseconds, it takes N slices (thread)

to process the raw frame.

FPA Metadata Process Time (ms):

The total amount of time, in milliseconds, it takes the CSS to gather and format all meta-data that will

be published with an FPA. This includes formatting all meta-data into Google Protocol Buffer

message that contains a CSS defined Xfer Command and generating the Length Prefixed Frame that

will be serialized over Ethernet to the CSS Xfer Controller.

Scrub DAT Processing Time (ms):

The total amount of time, in milliseconds, it takes the CSS to gather and format all meta-data

associated with a Scrub message. A Scrub message is generated whenever current data publication is

being interrupted due to a restart of a DAT or, when the CSS is in start mode, execution of the current

DAT is cancelled or aborted. This includes generating the Length Prefixed Frame that will be

serialized (transmitted) over Ethernet to the CSS Xfer Controller.

GPB Serialize Processing Time (ms):

The total amount of time, in milliseconds, it takes the CSS to serialize the Length Prefixed Frame

(which includes the Google Protocol Buffer) over Ethernet to the CSS Xfer Controller. This amount

of time is not necessarily equal to the amount of time it takes to transmit the data but rather the

amount of time it takes to hand the data off to the Google Protocol Buffer method that will do the

actual transmission.

Xfer Controller

LPF Transmit Time (ms):

The total amount of time, in milliseconds, it took for the Length Prefixed Frame to be transmitted

from the CSS C++ Camera Controller to the CSS Java Xfer Controller.

LPF Parsing Time (ms):

The total amount of time, in milliseconds, it takes for the Xfer Controller to read an LPF from the

LPF queue, parse it, and determine the type of CSS Xfer Command the Google Protocol Buffer

message contains.

Xfer Cmd Processing Time (ms):

The total amount of time, in milliseconds, it takes for the Xfer Controller to process the received Xfer

Command. This includes data publication time.

Reset Meters

Selecting this button will reset all meters on the page to zero.

4.7.4.5. Maximum Allowable # of Data-Tiers

The value displayed reflects the value of the VCC property .dat:maxDataTiers which controls the

allowable “depth” you can have in any given Data Acquisition Tree. This is not a user configurable

property but if the value is insufficient for your purposes, contact DKIST engineering and we can discuss

the possibility of this property being added to the configurable parameters contained in cssSite.config.

4.7.4.6. Debug Sliders

Debug sliders, which allow for selecting a debug category and level, are provided for the VCC, Camera

Controller, Transfer Controller, and C++Container.

4.7.5. Simulation Control

The simulation control tab, shown in Figure 11, provides access to attributes that affect CSS operations

when it is running as a camera simulator.


MAN-0008, Rev F 33

Figure 11: Simulation Control

A DKIST supported camera is configured as a camera simulator via three attributes within the .csh

namespace of the VCC. These attributes are .csh:interface:commType, .csh:interface:model, and

.csh:interface:vendor. The CSS contains a map of valid combinations of these attributes to determine the

camera that is being instantiated and the communications/data channel to use for the camera. The attribute

.csh:interface:commType defines the communication channel for the camera. When this attribute value is

set to “File_IO”, and assuming a valid combination of commType/model/vendor is configured, then on

startup the CSS automatically instantiates a simulated “frame-grabber” class that, for all intents and

purposes, behaves like a real frame-grabber but gets its data from a set of files rather than from real

camera hardware.

Each time the camera is triggered (exposed) and, following the exposure time defined in the currently

active camera configuration, a raw frame will be delivered from the simulated frame-grabber to the

camera controller. If the current camera configuration defines hardware applied windowing and/or

binning, then the raw frame will reflect this processing. Once a raw frame is delivered to the camera

controller it will continue through the CSS data acquisition and processing pipeline as determined by the

current camera configuration. The CSS will circularly iterate through any given set of data files. The rate

at which it will iterate is dependent on the current exposure rate.

4.7.5.1. Camera Data Files

These input fields contain the path, base filename, and number of files per set of your simulation data.

The initial values contained in these three fields are configured via cssSite.config using the parameters

CSS_SIM_DATA_PATH, CSS_SIM_DATA_BASE_FILENAME, and CSS_SIM_DATA_FILES_PER_SET

respectively.


MAN-0008, Rev F 34

NOTE: When first viewed, it may be necessary to select “Get” to populate the widgets with their current

values.

Base Directory

This input field defines the path to your simulation data.

Base Filename

The Base Filename is the “root” name of all your simulation data files. The actual filename must be of the

form: “<Base Filename>.nnn.raw” where 000 ≤ nnn < # Files Per Set. Note that “nnn” must contain

three characters.

For example: If # Files per Set = 3, and Base Filename = “simData”, then the simulation data files must

be named “simData.000.raw”, “simData.001.raw”, and “simData.002.raw”.

# Files per Set

This input field defines the number of files in the set of simulation data contained in the defined Base

Directory and using the defined Base Filename.

To modify any of these values, enter the new value(s) in their corresponding field and select “Submit”. A

configuration containing the defined Base Directory, Filename, and # Files per Set will be submitted to

the CSS with the attributes .sim:baseDirectory, .sim:baseFilename, and .sim:numFiles. The attributes are

defined in SPEC-0098.

The CSS will perform attribute validation including existence of the defined directory, files, size and

content of files. Once validated the defined file set is loaded into CSS memory. Any error encountered

will be reported and is viewable via the “Report” field.

4.7.5.2. File Load Status

This portion of the simulation tab displays the current load status for a set of simulation data files.

Progress Bar

The progress bar provides a simple visual feedback for the percent of files in the set that have completed

loading. Loading will occur during CSS startup or whenever any of the simulation data set parameters are

changed (Base Directory, Base Filename, and/or # Files per Set).

Because disk I/O can be relatively slow compared to the rate that the CSS is be executed, the entire set of

simulation data files are read and loaded into a set of memory buffers. The reading of data files and

loading of memory buffers occurs in a separate thread running in the background to the data delivery

mechanism of the simulated frame-grabber.

WARNING: While files are being read and loaded into memory the CSS will reject any configuration

which contains a start command.

While loading, the simulated frame-grabber will still react to a trigger and deliver a “raw frame” to the

camera controller but the contents of the raw frame may not be valid. This is indicated by the “Buffer is

Valid” flag described in the next section.

# Loaded

This field indicates the number of files that are actually loaded and ready for delivery. Under normal

circumstances, the # Loaded should equal the defined # Files per Set. All files are opened and contents

verified during the validation phase to assure that the actual loading will proceed without error. The #

Loaded may be < # Files per Set if the CSS encounters difficulty with a file during the load process or

encounters a file that does not contain the proper number of bytes of data.

4.7.5.3. Preparation Status

This section provides some insight into the buffer (and associated file) whose data is being prepared for

the “next trigger”. When a raw frame is delivered to the camera controller, the simulated frame grabber

circularly increments an index into the set of simulation data buffers and immediately begins preparing


MAN-0008, Rev F 35

the next raw frame that will be delivered on the next trigger. This preparation involves applying any

hardware windowing and/or binning as defined in the current camera configuration to the simulation

buffer.

Index #

The index into the set of simulation data buffers where 0 ≤ index < # Loaded

Buffer is Valid A flag which indicates whether the data contained in the buffer has been loaded from a data file. When a

set of simulation data-files begin loading, the entire set of simulation data buffers are marked invalid.

Then, as each file is read and loaded, the buffer associated with the file is marked valid.

Valid values are:

false File-set load is in progress and data has not been loaded into this buffer.

true Data in buffer has been loaded.

Filename

This field contains the path and filename that were used to load the buffer.

4.7.5.4. TRADS State

Toggling this radio button from state to state is used to simulate various states that TRADS may assume.

TRADS is not required for simulation purposes although the attribute which identifies the current

TRADS state is still contained within published meta-data.


MAN-0008, Rev F 36

5. Data Acquisition Trees

In the CSS, camera configurations provide all the mechanisms for configuring the CSH and CSS to

acquire and process raw frames and publish a single FPA-set. But, acquisition and processing of raw

frames and generation of FPA-sets must be coordinated with activities in the instrument. In addition to the

functionality provided with a camera configuration, it is necessary for the user to be able to do the

following:

Specify what camera configuration(s) to execute.

Schedule when the camera configuration(s) must execute.

Specify how many times each camera configuration must execute (i.e. how many FPA-sets to

generate).

Have the capability to define additional meta-data that must be published with each FPA-set.

Have a method to organize camera configurations, execution counts, timing information, and

instrument supplied meta-data into a defined sequence.

Within the CSS, a set of attributes called an execution block provides the building block for defining what

is referred to as a data acquisition tree (DAT). Before diving into the specifics of execution blocks and

DATs, let’s first explore the following example in an effort to grasp what a DAT does and how it is

processed.

Understanding through an Analogous Example 5.1.

For purposes of this example, assume that you are given a reading assignment. For this reading

assignment you are instructed to navigate on your computer to the root directory of a specified file

system. In that root directory you will find one of two things:

A single file -or- A single folder

- Your task is to read all the files and write a report on each file –

In order to complete this task, there are some rules and guidelines that must be followed.

5.1.1. File Rules

The general rules governing files are:

1. A file must be opened immediately and read to completion one time! When you open a file it will contain the following information and instructions:

a. The name of the file you opened to read.

b. How fast you must read the file.

c. Instructions on how the file is to be read.

2. When you complete reading a file you must write a report. This report must contain a summary of the contents of the file, including the name of the file, and

must be based on how you were instructed to read the file.

For illustrative purposes, a file is represented by the following symbol:

5.1.2. Folder Rules

Folders, on the other hand, are different. There are two general rules that apply to folders. These rules are:

1. A folder cannot be empty.


MAN-0008, Rev F 37

2. A folder must be opened immediately and read to completion one time!

When you open a folder you will find that it contains a cover sheet and the following:

One or more files - or - One or more folders - or - A mixture of one or more files and folders.

All folders must contain one of the above. These possible combinations are illustrated below:

Figure 12: Data Acquisition Tree Analogy – Folder Contents

The cover sheet contained in each folder gives you complete instructions on how to read the contents of

the folder. These instructions include:

A. The name of the folder you opened.

B. An ordered list where each entry in the list contains the following three pieces of information:

a. The name of a file or folder to read. This will be referred to as Fi.

b. The number of times that the file or folder must be read. This will be referred to as Ni.

c. A time value that is associated with reading the named file or folder. This will be referred

to as Ti. How you will apply this time depends on the cadence instruction below.

This ordered list is referred to as L. The number of entries in L is in the range: 1 ≤ I ≤ L

C. A cadence instruction. This instructs you on how to use the time value associated with each file

and folder. There are two possibilities:

a. Go Fast: Read the file Fi as fast as possible Ni times. When done, do not proceed to the

next entry in the list until Ti has expired.

- or –

b. Pace Yourself: Read the file Fi one time as fast as possible and then wait until Ti has

expired. Repeat this process Ni times after which you may proceed to the next entry in the

list.

D. An optional list of notes that are organized into sets. Recall that when you read a file you must

write a report. If notes are contained in the cover sheet of a folder then you must include one set

of notes from the folder when you write your report. Which set of notes you will include depends

on the notes instruction below.

E. A notes instruction. If notes are contained in the cover sheet of the folder, then this instructs you

on how you will utilize the notes. There are two possibilities:

a. Notes Repeat: Repeat inclusion of the same set of notes when writing Ni reports that

include Fi. When you have written Ni reports, you may advance to the next set of notes

for the next item in the list L. When you are finished with Ni reports, you may advance to

the next set of notes for Fi+1

- or –


MAN-0008, Rev F 38

b. Notes Do Not Repeat: Use Ni consecutive sets of notes when writing Ni reports on Fi. In

other words, retain a new set of notes each time you read a file or folder for inclusion in

the report you will write about a file.

If you need to include a new set of notes and you’ve reached the end of the list, start over from

the top.

NOTE: You may be collecting one set of notes from multiple folders as you open folders to find

a file to read. Keep track of this entire set of notes as they must be included in the report you will

eventually write on a file.

As noted above, your task is to read all files and write a report on each file that you read. In addition to

the information that pertains directly to the file you read, the report must also contain information about

the folder(s) you had to open in order to reach the file you are reading. As you proceed through the list

contained in the cover sheet of a folder you must note the following information to be included in your

report:

I. The current time when you first opened the folder or file.

II. If you are to read the folder of file more than once, then you must note the current time each

time you read the file or folder. This is in addition to the time noted in #1.

III. The number of times you are instructed to read the folder or file (Ni)

IV. Which count you are on in reading the folder or file. This is referred to as n where 1 ≤ n ≤ Ni

V. If notes are defined on the folder cover sheet, then you must include the current set of notes

as instructed.

Now that you are armed with the instructions on how to read a folder and its cover sheet, how to read a

file, and what to do when you read a file it is a relatively simple matter to perform the task at hand which

is to read the contents of the directory mentioned earlier.

Note that starting with the original folder, reading folders is an iterative (recursive) process that repeats

until a file is encountered at which time you read the file and write a report. Each folder you encounter

must be read to completion before you can proceed to the next item listed in its cover sheet.

5.1.3. Reading Assignment #1 – A File

When you are given this assignment you navigate on your computer to the root directory of the specified

file system and discover that it contains a single file. According to the rules governing a file you

immediately read it and write a report. That’s it, your assignment is complete.

5.1.4. Reading Assignment #2 – A Folder

When you are given this assignment you navigate on your computer to the root directory of the specified

file system and discover that it contains a single folder. According to the rules governing a folder you

immediately open it and begin reading it contents according to the cover sheet. The contents of this folder

are illustrated in Figure 13.


MAN-0008, Rev F 39

Figure 13: Reading Assignment #2

Per the rules and instruction for a reading assignment you will proceed as follows. The order presented

follows the numbering contained in the callouts of the timeline shown in Figure 13:

1. When handed Folder_1 you immediately open it and examine the cover sheet:

a. The cover sheet indicates that the first item to read is File_1 with the cadence instruction

Go Fast, and that you have 2 minutes allocated for this file.

b. You immediately open File_1 and begin reading it as instructed. It will take you 2

minutes to read the file.

2. After 2 minutes you are done reading File_1 and it is time to write a report. Because notes were

defined in the cover sheet, you include “The notes from Folder_1, set #1”. The report must also

include the additional required information: You include the time the folder was opened, the time

the file was first encountered, and the time you started reading the file. These are included as

separate entries in the report.

3. The cover sheet instructs you to read the file three times and you have only read it once so you

must read it again. You examine the Cadence instruction which states Go Fast; you note the start

time for the beginning of this second reading and immediately begin reading File_1 again. It will

take you 2 minutes to read the file.

4. After 2 minutes you are done reading the file and it is time to write a report again. Because notes

were defined in the cover sheet, you must determine which set of notes to include. The cover

sheet tells you that Notes Repeat which means that you will again include “The notes from

Folder_1, set #1”. The report must also include the information specified in the rules and will

include the initial start time from step #1 and the time you started the second reading.

5. Because the cover sheet instructed you to read File_1 3 times and Go Fast, you immediately note

the time and begin reading File_1 again. It will take you 2 minutes to read the file.


MAN-0008, Rev F 40

6. After 2 minutes, as instructed by File_1, you are done reading the file and it is time to write a

report again. Because notes were defined in the cover sheet, you must determine which set of

notes to include. The cover sheet tells you that Notes Repeat which means that you will once

more include “The notes from Folder_1, set #1”. The report must again include the information

specified in the rules and will include the initial start time from step #1 and the time you started

the third reading.

7. You have now read File_1 three times. You must now determine when you can state that the

reading assignment is complete. To do this, you recall that a time value of 6 minutes was defined

for File_1 and that the cadence instruction was Go Fast. You read File_1 three times as fast as

possible so now you can use the time value provided in the instructions for this file to determine

when to proceed to the next entry in the cover sheet. Using the time value you saved in step #1

and adding 6 minutes, you compare that result with the current time. The current time is also at

six minutes so you know you are done with entry #1 from the cover sheet. You examine the cover

sheet again and see that it only contains the single entry that you just completed.

You are done and the reading assignment is complete.

5.1.5. Reading Assignment #3

This next example is nearly identical to Assignment #2. The difference between these two examples will

be the cadence instruction contained on the cover sheet. In this example the cadence will be Pace

Yourself. All other elements of the assignment will remain the same. The contents of the cover sheet and

the resulting time line are illustrated in Figure 14.


The process for writing the reports is identical to the previous example. The difference between

Assignment #2 and #3 is when the file is read and the report generated. In the previous example the

cadence was set to Go Fast and the time value defined was 6 minutes. Because each read of File_1 took 2

minutes and you were instructed to read the file 3 times, it took you a total of 6 minutes which is

equivalent to the total amount of time you were given. Therefore, after 3 back-to-back read/write cycles

you were done.

In contrast, this example uses the cadence instruction Pace Yourself. Timing starts when you open the

file. When you finish reading the file you write the report and then must wait till the specified amount of

time has elapsed. The amount of time to wait is calculated as follows:

Time to wait = Ti – Time to read Fi

These wait periods are indicated by the numbered items 2a, 3a, and 4a in Figure 14.


MAN-0008, Rev F 41

When a wait period has expired you must evaluate the total number of times (Ni) you are to read the file

to determine whether to read the file again or proceed to the next entry on the cover sheet.

Aside from the cadence instruction, all other aspects of Assignment #3 are identical to Assignment #2.

5.1.6. Reading Assignment #4

The final reading assignment expands the concepts presented in the previous assignments by adding a

folder within a folder and begins to reveal how files and folders can be organized into a tree like

hierarchical structure. This is illustrated in Figure 15.


This assignment uses both types of cadence instructions and also introduces the second type of notes

instruction: Notes DO NOT Repeat.

1. When handed Folder_1 you immediately open it and examine the cover sheet:

a. The cover sheet indicates that the first item to read is Folder_2.

b. The cover sheet indicates that there are two sets of notes. You jot down “The notes from

Folder_1, set #1”, note the appropriate time values and immediately open Folder_2.

c. The cover sheet of Folder_2 instructs you to read File_2, with the cadence instruction Go

Fast, and that you have 2 minutes allocated for this file.

d. You immediately open File_2 and begin reading it as instructed. It will take you 2



MAN-0008, Rev F 42

2. It’s time to write the report for File_2. You examine the cover sheet and see that notes are

provided. You write your report using the notes you jotted down from Folder_1 and the first set

of notes from Folder_2. The notes you will include in the report are:

“The notes from Folder_1, set #1” and “The notes from Folder_2, set #1”

3. The Folder_2 cover sheet instructs you to read Folder_2 twice and to “Go Fast” – Immediately

begin reading File_2 again; take the amount of time specified by the file.

4. It’s time to write a report again for File_2. The notes instruction on Folder_2’s cover sheet states

that Notes DO NOT Repeat and you see that there are two sets of notes. Since you utilized the

first set in the previous report you advance to the next set of notes and use them. The notes you

will include in the report are:


At this point you have completed the first reading of Folder_2. All items contained in the cover

sheet of Folder_2 have been read. You close the folder and return to the Folder_1. You examine

the cover sheet to see what you are supposed to do next.

5. Folder_1 cover sheet instructs you to “Pace Yourself”. The time value associated with reading

Folder_2 is 8 minutes. Four minutes have elapsed since you first started reading Folder_2.

Therefore, you must wait an additional 4 minutes before proceeding.

6. You are done waiting. Folder_1 cover sheet instructs you to read Folder_2 twice. Because the

notes instruction indicates Notes Repeat you jot down “The notes from Folder_1, set #1” again

and proceed as in Step #1.

7. You write the report for File_2. Note that whenever you open a folder, you always start from the

beginning of the list of provided notes. The notes you will include in the report are:


8. As in Step #3, the Folder_2 cover sheet instructs you to “Go Fast” – Immediately begin reading

File_2 again; take the amount of time specified by the file.

9. You write report for File_2 as you did in Step #4. The notes you will include in the report are:


At this point you have completed the second reading of Folder_2. All items contained in the

cover sheet of Folder_2 have been read. You close the folder and return to the Folder_1. You

examine the cover sheet to see what you are supposed to do next.

10. As in Step #5, the Folder_1 cover sheet instructs you to “Pace Yourself”. The time value

associated with reading Folder_2 is 8 minutes. Four minutes have elapsed since you started

reading Folder_2 for the second time. Therefore, you must wait an additional 4 minutes before

proceeding. After waiting you have completed reading the first item in the cover sheet of

Folder_1. You proceed to item #2. This also means that you can now advance to the next set of

notes to use with writing the reports associated with this next item.

11. Item #2 instructs you to read File_1. You immediately begin reading File_1. It will take you 2


12. It’s time to write the report for File_1. You examine the cover sheet and see that notes are

provided. You write your report. The notes you will include in the report are:

“The notes from Folder_1, set #2”

At this point you have completed reading File_1. You examine the cover sheet to see what you

are supposed to do next.


MAN-0008, Rev F 43

13. Folder_1 cover sheet instructs you to “Pace Yourself”. The time value associated with reading

File_1 is 4 minutes. Two minutes have elapsed since you first started reading File_1. Therefore,

you must wait an additional 2 minutes before proceeding.

14. You examine the cover sheet of Folder_1 again and see that you have completed reading its

contents.

You are done and the reading assignment is complete

5.1.7. CSS Execution Blocks

With an understanding of the Files/Folders just presented, it is a fairly straightforward process to draw

parallels between the various aspects of the examples and the actual control elements utilized in executing

camera configurations. The relationships between the elements presented in these examples and the actual

CSS control elements are as follows:

File ≡ CSS Camera Configuration where:

o Time to read the file ≡ Exposure Rate defined in the camera configuration.

o Instructions on how to read file ≡ Defined camera configuration to produce one FPA-set.

A folder entry that names a camera configuration is also referred to as an acquireNode.

Folder and Cover Sheet ≡ CSS Execution Block where:

o Folder Name ≡ Execution Block ID.

o File/Folder List ≡ Camera configuration/Execution Block vectors where:

File/Folder Name ≡ Vector of Camera Configuration or Execution Block IDs.

Number of time to read ≡ Vector of number of times to execute each ID.

Time allocated to read ≡ Vector of time-slices for each ID.

o Cadence ≡ Time-slice Repeats Flag.

o Sets of Notes ≡ Sets of DAT Meta-data where:

Meta-data Set Size (no analogy in the examples). Defines how many strings are

contained in one set of meta-data.

o Notes Instruction ≡ Meta-data Repeats Flag.

An execution block therefore contains one set of each of the items highlighted in bold. Execution blocks

and camera configurations are arranged by the user into a hierarchical tree like structure called a data

acquisition tree. The data acquisition tree determines the What, When, and How Many Times a camera

configuration will execute. Included in these instructions are optional DAT meta-data that the user wants

to be included when a report (FPA-set) is published.

The order in which camera configurations are executed is solely dependent on how the data acquisition

tree is organized. The data acquisition tree may be simple in that it only names a single camera

configuration or complex with multiple nesting levels and camera configurations.

Each nesting level in a data acquisition tree is referred to as a data-tier. The number of data-tiers in a tree

is determined by the number of execution blocks (i.e. folders) that must be traversed to find a camera

configuration (i.e. file). Data-tiers can be utilized to organized FPA-sets into groups. Meta-data published

with each FPA of each FPA-set will contain counters and timestamps that will identify exactly when and

where within the data acquisition tree the CSS was processing an acquireNode (i.e. camera configuration)

that produced said data. This is akin to the “required” information that was specified in the examples from

the previous section. More information on data-tiers will be presented later.


MAN-0008, Rev F 44

Data Acquisition Trees by Example 5.2.

This section will present several Data Acquisition Tree (DAT) examples and progress through use of the

various attributes contained in an execution block.

The initial ID to be executed in the DAT is defined with .global:ID0. The number of times the CSS will

execute this ID when a start command is received is defined with .global:execCount0.

Configuring the DAT is accomplished by setting .global:ID0 to the ID of a camera configuration or top

level execution block and setting .global:execCount0 to the number of times .global:ID0 will be executed

when a start command is received. When .global:ID0 is submitted, the CSS will recursively descend the

DAT and verify that all execution block and camera configuration IDs are loaded in memory. If an ID is

not loaded in memory the CSS will, using the current values of .global:paramSetDB:category and

.global:paramSetDB:name, attempt to retrieve that ID and it associated set of attributes from the

parameter-set database. If all IDs associated with .global:ID0 are/can be loaded then the CSS will begin

to idle according to that DAT. Otherwise, the CSS will continue to idle according to the previous value of

.global:ID0. While the CSS is idling it is considered to be in preview mode.

The value submitted for .global:execCount0 defines the number of times the DAT will be executed when

a start command is received. A start command is defined by receipt of the following attributes

.global:camMode=”startWithSave” | “startWithoutSave” and .global:startMode=”immediate” |

“atStartTime”. Upon receipt of the start command, the CSS will examine .global:startMode to determine

if execution will begin immediately (.global:startMode = “immediate”) or at a specified time in the

future (.global:startMode = “atStartTime” where the start time is defined by .global:initialStartTime).

If :startMode=”immediate”, the CSS will, on the next time referenced trigger, begin acquiring and

processing raw frames according to the first acquireNode in the tree.

If :startMode=“atStartTime”, the CSS will wait for the time specified by .global:initialStartTime and

then begin acquiring and processing raw frames according to the first acquireNode in the tree. It is

important to note that if the time value specified in .global:initialStartTime does not fall on a T0 trigger

the CSS must wait until the next T0 trigger before it begins processing raw frames according to the first

acquireNode. It is for this reason that the data-tier meta-data published with each FPA contains both

scheduled and actual timestamps.

NOTE: In order to reduce the amount of data contained in the meta-data tables that accompany each

example, the attributes css.pub:fpa:pixelMin and css.pub:fpa:pixelMax will be omitted. Also, to conserve

space in the meta-data tables, the year, month, and day will be omitted from the timestamps.

For all examples, items highlighted in red in the meta-data tables indicate values that change in the meta-

data between published FPA’s. Examples assume that the identified camera configurations and execution

blocks have been loaded into and validated by the CSS using the appropriate .global, .execBlock, and

.camConfig namespace attributes.

As defined in SPEC-0098, recall that when a start command is received and the DAT completes either

due to normal completion by executing the DAT .global:execCount0 times or receipt of a cancel or abort

the CSS will return to the idle state. The CSS will then automatically restart continuous execution of the

DAT identified by .global:ID0 in preview mode.

For all examples, camConfigID indicates a validated camera configuration and execBlockID indicates a

validated execution block.

5.2.1. Accumulations Disabled

This first set of examples will assume that accumulations are not enabled in a camera configuration.

Unless otherwise stated, all examples assume that the following global attribute values will be or have

been configured:


MAN-0008, Rev F 45

:.global Attribute Name Attribute Value

:referenceT0 2014/08/28:14:00:00.000

:initialStartTime 2014/08/28:14:15:00.000

:startMode “atStartTime”

:paramSetDB:category “css”

:paramSetDB:name “examples”

Table 7: Examples – Fixed Global Attributes

With these defined global attributes, upon receipt of a start command (.global:camMode =

“startWith(out)Save”, the CSS will begin producing FPA-sets beginning at “2014/08/28:14:15:00.000”.

The actual FPA-sets the CSS will produce depend on the camera configurations contained in the DAT.

The total number of FPA-sets the CSS will produce depends on the DAT structure and how many times

the DAT is executed.

Table 8 below defines two camera configurations that will be used for the examples where accumulations

are disabled. The only difference between the camera configurations, aside from their ID’s and

descriptions, is the exposure time. For these examples we will assume that the camera contains a 2k x 2k

sensor, 12-bits per pixel, and will be triggered at 20Hz. This will result in a raw frame being acquired and

processed every 50ms. The accumulation attributes indicate that accumulations are disabled. Windowing

is configured such that the entire 2k x 2k pixel area is retained. Binning and normalization are disabled.

Thus, for these configurations, the CSS will produce a single FPA-set that contains one FPA. This FPA

will contain one processed raw frame with either a 10ms or 20ms exposure time.

.camConfig Attribute Name Attribute Value Attribute Value

:ID “cc_config1” “cc_config2”

:description “20Hz; 10ms” “20Hz; 20ms”

:exposure:rate 20 20

:exposure:rateMultiplier 1 1

:exposure:ratePhase 0 0

:exposure:time 10 20

:accum:numberOf 1 1

:accum:sequence [ 1 ] [ 1 ]

:accum:posAtRefT0 1 1

:accum:numCycles 1 1

:winBin:hw:binSize [ 1, 1 ] [ 1, 1 ]

:winBin:hw:win:numberOfROIs 1 1

:winBin:hw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ]

:winBin:sw:binSize [ 1, 1 ] [ 1, 1 ]

:winBin:sw:win:numberOfROIs 1 1

:winBin:sw:win:roiType “vertical” “vertical”

:winBin:sw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ]

:normalization:method “none” “none”

:normalization:value N/A N/A

:bufferEnable false false

Table 8: Camera Configurations with a Single Accumulator

5.2.1.1. Simple Camera Configuration Execution

The simplest means to acquire and process raw frames is to set .global:ID0 to a camConfigID and

.global:execCount0 to an execution count. For example, to generate a single FPA-set from camera

configuration “cc_config1” when a start command is received set:

.global:ID0 = “cc_config1”

.global:execCount0 = 1


MAN-0008, Rev F 46

.global:startMode = “immediate”

This results in the DAT illustrated in Figure 16.

Figure 16: DAT - "Take a picture"

When the CSS receives a start command it will, starting from the root node4, descend the DAT until an

acquireNode is reached. An acquireNode is defined as an execution block in which a :nextID[i] entry

identifies (points to) either “cc_NoOp” or a camConfigID. When an acquireNode is encountered that

names a camConfigID, the CSS will acquire and process raw frames according to that ID to generate a

single FPA-set. The total number of FPA-sets the CSS will generate for that acquireNode is defined by

:count[i] and generation of each FPA-set will be spaced the corresponding :timeSlice[i] seconds apart.

In this example, :nextID[0] of the root node names “cc_config1”. Thus, the root node is an acquireNode

and the CSS will, beginning on the next T0 referenced trigger, acquire and process raw frames to produce

an FPA-set. Because :globlal:execCount0 = 1 (and thus the root nodes :count[0] = 1), only one FPA-set

will be produced following the start command. Recall that beginning with the root node the CSS will

count the number of execution block levels to determine the number of data-tiers. As the root node is an

acquireNode, this acquisition tree contains only one data-tier. The following table lists the data-tier and

FPA meta-data that will be published with this single FPA-set.

css.pub<:name-space>

:dataTier<:attribute> i = 0 :fpa<:attribute> Value

:metaData:fromDAT = :numDataTiers = 1 :size [ 2560, 2160 ]

[<EMPTY>] :execCountSum[i] 1 :bitsPerPixel 12

:execCountCurr[i] 1 :bytesPerPixel 2

:nextIdLength[i] 1 :setSize 1

:nextIdIndex[i] 1 :setIndex 1

:currentID[i] “cc_config1” :accumNumber 1

:idExecCount[i] 1 :numRawFrames 1

:idCurrCount[i] 1 :timeStamp 14:15:00.000

:timeStamp:scheduled[i] 14:15:00.000 NOTES: FPA-set #1, 1 FPA

:timeStamp:actual[i] 14:15:00.000

Table 9: DAT "Take a Picture" Meta-data (execCount0=1)

As another example, by simply setting .global:execCount0 = 3 and issuing a start command, three FPA-

sets will be acquired and published. The following table lists the data-tier and FPA meta-data that will be

published with these three FPA-sets (three FPAs).

4 See SPEC-0098 for a discussion of the “root node”.


MAN-0008, Rev F 47


:dataTier<:attribute> i = 0 :fpa<:attribute> Value































Table 10: DAT "Take a Picture" Meta-data (execCount0=3)

In all cases, following receipt of the start command, once the DAT has been executed .global:execCount0

times or the DAT has been canceled or aborted, the CSS will automatically return to preview mode,

restart the DAT, and continuously execute it.

5.2.1.2. Using an Execution Block

The examples in this section will follow the same format as presented in the previous section but will

execute a single camera configuration from an execution block rather than directly from the root node.

Execution blocks contain the vectors :exec:nextID[i], :exec:count[i], and :exec:timeSlice[i] where each

vector contains N entries and N ≥ 1.

For each of these vector entries in an execution block where 0 ≤ i < N:

:nextID[i] = ID of an execution block or camConfigID.

:count[i] = The number of times to acquire :nextID[i].

:timeSlice[i] = The amount of time execution of :nextID[i] is to occupy and is dependent on

:timeSliceRepeats.

Recall that the root node is configured by the global attributes .global:ID0 and .global:execCount0

which name a single camConfigID or execution block and the number of times that ID is to be executed

respectively. For this example, .global:ID0 will name an execution block which, in turn, will identify a

single camConfigID to execute. For this example “cc_config1” will be executed 1 time. Because


MAN-0008, Rev F 48

:timeSlice[0] = 0.0, the value of :timeSliceRepeats is a “don’t care”. Instrument supplied meta-data will

not be considered at this time. This acquisition tree is illustrated in Figure 17.

Figure 17: DAT Example #1 – Simple Execution Block

Addition of an execution block also adds a data-tier. Data-tiers in Figure 17 are separated by the vertical

dashed line. Tier #1 and the counts associated with it in the css.pub:dataTier meta-data are controlled by

the global attributes .global:ID0 and .global:execCount0. When .global:ID0 names an execution block,

rather than a camConfigID, a second data-tier is added. This results in the counter vectors contained in

the css.pub:dataTier meta-data increasing in size by one. The number of data-tiers in any DAT is equal to

the number of execution block levels in the DAT.

If the CSS receives a preConfigure command it will validate, store, and then idle according to the first

acquireNode in the tree.

Assuming that .global:startMode=”atStartTime”, when the CSS receives a start command, and starting

at .global:initialStartTime , it will re-start processing of the acquisition tree from the root node and

descend the DAT until an acquireNode is reached. Recall that an acquireNode is defined as an execution

block in which a :nextID[i] entry identifies (points to) either “cc_NoOp” or a camConfigID. When an

acquireNode is encountered that names a camConfigID, the CSS will acquire and process raw frames

according to that ID to generate a single FPA-set. The total number of FPA-sets the CSS will generate for

that acquireNode is defined by :count[i] and generation of each FPA-set will be spaced the corresponding

:timeSlice[i] seconds apart.

In this example, .global:ID0 names the execution block “eb_ex1_1”. The CSS must descend the DAT

another level and try to find the first acquireNode. Examination of the :nextID[] vector of “eb_ex1_1”

reveals that it contains only one entry (:nextID[0]) and that this entry points to a camConfigID. Thus,

“eb_ex1_1” is an acquireNode and was found at the second level of execution blocks, therefore there are

two data-tiers. The total number of FPA-sets the CSS will generate for this acquireNode is 1

(:count[0]=1) and they will be acquired at the rate defined “cc_config1”. The following table lists the

data-tier and FPA meta-data that will be published with this single FPA-set.


:dataTier<:attribute> i = 0 i = 1 :fpa<:attribute> Value


[<EMPTY>] :execCountSum[i] 1 1 :bitsPerPixel 12

:execCountCurr[i] 1 1 :bytesPerPixel 2

:nextIdLength[i] 1 1 :setSize 1

:nextIdIndex[i] 1 1 :setIndex 1

:currentID[i] “eb_ex1_1” “cc_config1” :accumNumber 1

:idExecCount[i] 1 1 :numRawFrames 1

:idCurrCount[i] 1 1 :timeStamp 14:15:00.000

:timeStamp:scheduled[i] 14:15:00.000 14:15:00.000 NOTES: FPA-set #1, 1 FPA

:timeStamp:actual[i] 14:15:00.000 14:15:00.000

Table 11: DAT Example #1 Meta-data

Notice that the css.pub:dataTier:currentID[i] meta-data entries differ: Data-tier 1(i=0) identifies that

“eb_block1” is currently executing and Data-tier 2(i=1) identifies that “cc_config1” is executing.


MAN-0008, Rev F 49

As another example, by simply setting .global:execCount0 = 3 and issuing a start command, three FPA-

sets will be acquired and published. Again, because :timeSlice[0] = 0.0, the value of :timeSliceRepeats is

a “don’t care” and in this example is set to true. This acquisition tree is illustrated Figure 18.

Figure 18: DAT Example #2 - Simple Execution Block

The following table lists the data-tier and FPA meta-data that will be published with these three FPA-sets.


































In the previous example the desired outcome was to execute “eb_ex2_1” three times, which in turn,

caused “cc_config1” to be acquired and processed three times. A variation on this example is to set

:exec:count[0] = 3 in “eb_ex3_1” and then execute the acquisition tree one time. The :timeSlice[0] value

is still 0.0 so again, the value of :timeSliceRepeats is a “don’t care”. This is illustrated in Figure 19.


MAN-0008, Rev F 50

Figure 19: DAT Example #3 – Execution Block with :exec:count[i] > 1

Notice that a different execution block is defined, “eb_ex3_1”, which sets :count[0] = 3 and notice that

the same camera configuration is being used from this new execution block. The following table lists the

data-tier and FPA meta-data that will be published with these three FPA-sets.


































It is worthwhile to note a couple of differences between Example #2 and Example #3 as far as the meta-

data is concerned. First, in Example #2, the starting timestamp for “eb_ex2_1” changes from meta-data

set to meta-data set because “eb_ex2_1” is being executed three times. Because “eb_ex2_1” points to a

single camera configuration, the timestamps for each FPA-set follows the timestamps of the tier 1 data. In

Example #3, “eb_ex3_1” is only executed one time but that execution block indicates that “cc_config1”

will be executed three times. Therefore, the starting timestamp for “eb_ex3_1” remains the same until all

data has been acquired for the entire execution block. The timestamps for data-tier 2 though differ

because “cc_config1” is being acquired three times. Any timestamp in the data-tier meta-data is related to


MAN-0008, Rev F 51

when data acquisition for the currently active element and execution count commenced. Had

.global:execCount0 been set to a value of 2 then the next data-tier meta-data that would have been

published with the next FPA-set would have contained :timeStamp:scheduled[0] = 14:15:00.150 as this

is the time that the second execution of “eb_ex3_1” would have started.

Example #3 illustrates the foundation for FPA-set grouping. FPA-set grouping is used when it is

necessary to group M FPA-sets together so that each group of M FPA-sets can be identified as a unit. For

example, grouping of FPA-sets is necessary for burst operations or when multiple FPA-sets are being

acquired and must be related to a single observed wavelength. When it is desirable to group M FPA-set

together, set :count[i] = X where X = # of FPA-sets that need to be logically grouped. The meta-data

from data-tier N will contain the total number and current count for the FPA-set group.

5.2.1.3. Using Time-slices

Up to this point, the :timeSlice entries in an execution block have contained a value of 0.0 which implies

immediate execution. Additionally, because the time-slice values were 0.0, the :timeSliceRepeats flag has

been a “don’t care”. This section will present two simple examples where an execution block contains a

non-zero timeSlice with :timeSliceRepeats being both true and false. As previously defined, execution

blocks contain the flag :timeSliceRepeats and the vectors :nextID[i], :count[i], and :timeSlice[i] where

each vector contains N entries and N ≥ 1. For each of these vector entries in an execution block where 0 ≤

i < N:

:nextID[i] = ID of an execution block or camConfigID.

:count[i] = The number of times to acquire :nextID[i].

:timeSlice[i] = The amount of time execution of :nextID[i] is to occupy and is dependent on

:timeSliceRepeats.

When the CSS encounters an execution block it notes the timestamp for the start of the :nextID[0] entry

and then traverses the :nextID[0] tree until it finds an acquireNode. Once found, the CSS will examine

the :timeSliceRepeats flag and proceed as follows:

If :timeSliceRepeats = false, the CSS will note the start time of the acquireNode and then acquire

and process raw frames to produce :count[0] FPA-sets. When :count[0] FPA-sets have been

produced and published. The CSS will then wait until the current time = (start time +

:timeSlice[0]) and then proceed to :nextID[i+1].

If :timeSliceRepeats = true, the CSS will note the start time of the acquireNode and then acquire

and process raw frames to produce one FPA-set. The CSS will then wait until the current time =

(start time + :timeSlice[0]). This process will be repeated :count[0] times at which point the CSS

will proceed to :nextID[i+1].

In both cases, when :count[0] FPA-sets are complete and the CSS has completed waiting for the

appropriate amount of time it will proceed to the next index value in the execution block. This process

repeats until all N entries in the execution block have been processed. Time-slices are not restricted to

execution blocks that contain an acquireNode. The above mentioned process is applied in each execution

block along the path to the acquireNode.

NOTE: If a :timeSlice[i] entry is non-zero but the value it contains is not sufficiently long enough to

encompass the amount of time it takes to acquire :nextID[i] based on :timeSliceRepeats and the

:timeSlice value, then the CSS will immediately proceed as if the value contained 0.0.


MAN-0008, Rev F 52

Building on Example #3 from the previous section, let’s now assume that, although the camera is being

triggered at 20Hz, the camera configuration identified by “cc_config1”, one FPA-set must be produced

every 500ms5. The acquisition tree is illustrated in Figure 20.

Figure 20: DAT Example #4a - Execution Block with :timeSlice[i]>0.0, :timeSliceRepeats=true

Notice again that a different execution block is defined, “eb_block2”, which sets :count[0] = 3,

:timeSlice[0] = 0.500, and :timeSliceRepeats = true. With this execution block three FPA-sets will be

produced, spaced 500ms apart. The following table lists the data-tier and FPA meta-data that will be

published with these three FPA-sets.








:currentID[i] “eb_ex4a_1” “cc_config1” :accumNumber 1

























Table 14: DAT Example #4a Meta-data

5 The exposure rate in “cc_config1” could be changed to 2Hz and the outcome would be the same.


MAN-0008, Rev F 53

Notice that the Tier-2 meta-data timestamps, which are associated with FPA-sets, indicate that the FPA-

sets are started every 500ms. If .global:execCount0 > 1, FPA-sets would continue to be produced every

500ms.

In contrast, let’s now set :timeSliceRepeats = false. In order to illustrate this example, the execution count

for the entire tree will be increased to 2. The DAT is illustrated in Figure 21.

Figure 21: DAT Example #4b - Execution Block with :timeSlice[i]>0.0, :timeSliceRepeats=false

A new execution block with a modified :timeSliceRepeats flag is defined. When :timeSliceRepeats =

false, each defined :timeSlice[i] value applies to :count[i] consecutive acquisitions of the indicated

camera configuration. With this DAT, two groups of three FPA-sets will be generated. The FPA-sets will

be produced in succession while the two groups are spaced 500ms apart. The following table lists the

data-tier and FPA meta-data that will be published with these two groups of three FPA-sets.








:currentID[i] “eb_ex4b_1” “cc_config1” :accumNumber 1





























MAN-0008, Rev F 54






























Table 15: DAT Example #4b Meta-data

Notice that the Tier-2 meta-data timestamps, which are associated with FPA-sets, indicate that the FPA-

sets are started every 50ms and each execution of the tree begins every 500ms. FPA-sets are spaced 50ms

apart because “cc_config1” has accumulations disabled and defines an exposure rate of 20Hz.

5.2.1.4. Defining Instrument Supplied Meta-data

Instrument supplied meta-data is meta-data that is known to the instrument builder and must accompany

FPA-sets when they are published. Meta-data can be defined in an execution block and is referred to as

DAT meta-data. When the CSS traverses a DAT in search of an acquireNode it will gather the current

meta-data set from the current node in each execution block until it encounters an acquireNode. At this

point the CSS will acquire, process, and publish an FPA-set according to the defined camera

configuration. The DAT meta-data that will be published with this FPA-set is the meta-data gathered

along the path to the acquireNode. Within each execution block are a set of attributes used to define this

meta-data. These attributes are:

:metaData:repeats – Determines whether the current meta-data set will be repeated :count[i]

times or whether for each execution of :nextID[i] the CSS circularly increments to the next meta-

data set.

:metaData:setSize – Defines how many consecutive strings in :metaData:sets[] comprise a single

meta-data set.

:metaData:sets[] - The actual meta-data strings.

For this first example two camConfigID’s will be used from a single execution block. Each camera

configuration must be executed twice and must be scheduled 150ms apart. This implies that the defined


MAN-0008, Rev F 55

time-slice must repeat. The entire DAT will be executed once. Let’s assume that the following meta-data

must accompany the FPA-sets published by each of the camera configurations:

“cc_config1” – Three strings: “My Test”, “Wavelength=430”, and “Position=1”

“cc_config2” – Three strings: “My Test”, “Wavelength=490”, and “Position=2”

This is illustrated in Figure 22.

Figure 22: DAT Example #5a – Execution Block with Instrument Supplied Meta-data

Note that :metaData:repeats = false. Because this flag is false and :count[i] = 2 then for each camera

configuration the meta-data which must accompany the FPA-sets must be repeated in order to have a

proper association between the meta-data and the executing camConfigID. The following table lists the

data-tier and FPA meta-data that will be published with these four FPA-sets.



:metaData:fromDAT = [ :numDataTiers = 2 :size [ 2560, 2160 ]

“My Test”, :execCountSum[i] 1 4 :bitsPerPixel 12

“Wavelength=430”, :execCountCurr[i] 1 1 :bytesPerPixel 2

“Position=1” :nextIdLength[i] 1 2 :setSize 1

] :nextIdIndex[i] 1 1 :setIndex 1



















MAN-0008, Rev F 56






















In this example, the boolean flag :metaData:repeats = false in the execution block and therefore the CSS

will, for each execution of :nextID[i], circularly increment the set index into :metaData:sets[] to retrieve

the next meta-data set. By setting :metaData:repeats = true the amount of meta-data that must be

supplied in the execution block can be reduced and is no-longer dependent on what the :count[i] value is

for any of the :nextID[i] entries.

Figure 23 illustrates how the amount of meta-data that must be supplied in the execution block can be

reduced by setting :metaData:repeats = true. The data-tier meta-data that will be published with the

FPA-sets is exactly the same as in the above table with the exception that :dataTier:currentID[0] =

”eb_ex5b_1” for all cases.

Figure 23: DAT Example #5b – Execution Block with Instrument Supplied Meta-data

The CSS will utilize meta-data strings 0, 1, and 2 for two executions of “cc_config1” and then use meta-

data strings 3, 4, and 5 for two executions of “cc_config2”.

5.2.2. Accumulations Enabled

This next set of examples will build upon those from Section 5.2.1 by using more than one accumulator.

For all examples presented, assume that data acquisition will be synchronized to a four state modulator.

As in the previous section, assume that the camera contains a 2k x 2k sensor, 12-bits per pixel, and will be


MAN-0008, Rev F 57

triggered at 20Hz. This will result in a raw frame being acquired, processed, and accumulated every

50ms. Windowing is configured such that the entire 2k x 2k pixel area is retained. Binning and

normalization are disabled. Table 17 defined the two camera configurations that will be used.

The first camConfigID, “cc_config3”, defines four accumulators but only one accumulation cycle

(:accum:numCycles = 1). This type of configuration may be desirable when the instrument builder wants

to collect accumulation state data but does not want the CSS to perform the co-additions. Instead, the

instrument builder wants the CSS to deliver N sets of modulation state data and co-additions will be

performed in post processing.

The second camConfigID, “cc_config4”, is identical to “cc_config3” with the exception that it instructs

the CSS to co-add four raw frames per accumulator by setting :accum:numCycles = 4.

.camConfig Attribute Name Attribute Value Attribute Value

:ID “cc_config3” “cc_config4”

:description “20Hz; 10ms” “20Hz; 10ms”

:exposure:rate 20 20

:exposure:rateMultiplier 1 1

:exposure:ratePhase 0 0

:exposure:time 10 10

:accum:numberOf 4 4

:accum:sequence [ 1,2,3,4 ] [ 1,2,3,4 ]





:winBin:hw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ]




:winBin:sw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ]




Table 17: Camera Configurations with Multiple Accumulators

In principle, there is no real difference between the examples presented in Section 5.2.1 and the examples

that will be presented here except that the camera configurations are defined such that the CSS will

generate and publish more than one FPA per FPA-set. This simply means that css.pub:fpa meta-data

published with each FPA will contain counters that identify the FPA within the FPA-set. Specifically, for

these examples:

css.pub:fpa:setSize = 4

1 ≤ css.pub:fpa:setIndex ≤ .camConfig:accum:numberOf

1 ≤ css.pub:fpa:accumNumber ≤ .camConfig:accum:numberOf

Unless otherwise stated, all examples assume that the following global attribute values will be or have

been configured:

.global Attribute Name Attribute Value

:referenceT0 2014/08/28:14:00:00.000

:initialStartTime 2014/08/28:14:15:00.050




MAN-0008, Rev F 58

.global Attribute Name Attribute Value


Table 18: Accumulation Examples – Fixed Global Attributes

5.2.2.1. Example #6a – Multiple Accumulators

For this first example, assume that data acquisition will be synchronized to a four state modulator. The

instrument builder wants to acquire modulation state data but does not want the CSS to perform

accumulations. Instead, deliver FPAs that contain a single processed raw frame but contain information

that can be used to identify the modulation state the data was acquired at. The instrument builder want to

acquire two consecutive FPA-sets every 1 second and wants to do this twice. One possible DAT is

illustrated in Figure 24.

Figure 24: DAT Example #6a - Multiple Accumulators

The first item to note is that this DAT defines an additional level of execution blocks which will result in

an additional data-tier. The first requirement of this example is that two consecutive FPA-sets must be

acquired. This is accomplished via the execution block “eb_ex6a_2”. The camera configuration

“cc_config3” is defined to produce one FPA-set that contains four FPAs. Each FPA will have 1 processed

raw frame (see the :accum attributes in “cc_config3”, Table 17). In order to acquire two consecutive

FPA-sets, the time-slice between the FPA-sets must be 0.0. The next requirement of this example is that

acquisition of two FPA-sets must be spaced one second apart. This is accomplished via execution block

“eb_ex6a_1”. Notice that the :timeSlice[0] value is set to 1.0 second and :timeSliceRepeats = true. .

Recall that when :timeSliceRepeats = true, the :timeSlice[i] entries in an execution block are applied to

each acquisition of :nextID[i]. This implies that each execution of “eb_ex6a_2” must occupy 1 second.

This type of timing requirement can apply to an instrument changing a filter and then acquiring two FPA-

sets. To help identify the filter and filter wheel position, instrument supplied meta-data is defined in data-

tier 2. For simplicity sake, the entire tree will only be executed one time.

To illustrate the purpose of the css.pub:fpa:accumNumber vs. css.pub:fpa:setIndex meta-data values the

initial start time is offset from the reference time by a multiple of the exposure rate. This difference is

highlighted in red in Global Attributes listed in Error! Reference source not found.. The new

global:initialStartTime value has been selected to illustrate how css.pub:fpa:accumNumber is used to

identify the actual accumulator number in the T0 referenced accumulation sequence. Had :initialStartTime

been left at the value of 2014/08/28:14:15:00.000, the first acquired raw frame would have been co-added

to accumulator #1. With this new time, the first raw frame is acquired at the initial start time which

corresponds to accumulator #2. The accumulation sequence current position number formula is found in

SPEC-0098. The following pages contain the meta-data that will be published with the FPA’s. Each

section of this table corresponds to the meta-data published with an FPA.


:dataTier<:attribute> i = 0 i = 1 i = 2 :fpa<:attribute> Value


“FILTER=5434”, :execCountSum[i] 1 2 2 :bitsPerPixel 12

“FLTPOS=7” :execCountCurr[i] 1 1 1 :bytesPerPixel 2


MAN-0008, Rev F 59



] :nextIdLength[i] 1 1 1 :setSize 4

:nextIdIndex[i] 1 1 1 :setIndex 1

:currentID[i] “eb_ex6a_1” “eb_ex6a_2” “cc_config3” :accumNumber 2

:idExecCount[i] 1 2 2 :numRawFrames 1

:idCurrCount[i] 1 1 1 :timeStamp 14:15:00.050

:timeStamp:scheduled[i] 14:15:00.050 14:15:00.050 14:15:00.050 NOTES: FPA-set #1, FPA 1 of 4

:timeStamp:actual[i] 14:15:00.050 14:15:00.050 14:15:00.050




















































MAN-0008, Rev F 60






























































MAN-0008, Rev F 61















































MAN-0008, Rev F 62

5.2.2.2. Example #6b – Multiple Accumulators

This next example will illustrate how the requirements for Example #6a can be met but with one less level

of execution blocks and thus one less data-tier. The requirements for data acquisition are the same:

Acquire two consecutive FPA-sets every one second. The camera configuration is defined in

“cc_config3”. The DAT is illustrated in Figure 25.

Figure 25: DAT Example #6b - Multiple Accumulators

This DAT will have the same functional behavior as the DAT illustrated in Figure 24 but there are some

key differences to accomplish this. First, a new execution block is defined. Next, :timeSliceRepeats =

false. This means that the defined time-slices in the execution block encompasses :count acquisitions of

the node that the corresponding :nextID names, specifically “cc_config3”. In this case, the start of

:nextID[0] to the start of :nextID[1] will be 1 second apart. Next, :metaData:repeats = true so that each

meta-data set is included for :count[i] executions of :nextID[i]. Also note that “cc_config3” is named

from two different vector entries in the same execution block. The following pages contain the meta-data

that will be published with the FPA’s from this DAT.




“FILTER=5434”, :execCountSum[i] 1 4 :bitsPerPixel 12

“FLTPOS=7” :execCountCurr[i] 1 1 :bytesPerPixel 2

] :nextIdLength[i] 1 2 :setSize 4





:timeStamp:scheduled[i] 14:15:00.050 14:15:00.050 NOTES: FPA-set #1, FPA 1 of 4

















MAN-0008, Rev F 63





























































MAN-0008, Rev F 64






























































MAN-0008, Rev F 65
























Table 20: DAT Example #6b Meta-data

Notice how the meta-data vectors track the generation of FPA-sets from “cc_config3” as execution of

“eb_ex6b_1” proceeds.

5.2.2.3. Example #7 – Multiple Accumulators

For this next example both camConfigID’s “cc_config3” and “cc_config4”, listed in Table 17, will be

used. As in the previous example, data acquired with “cc_config3” will not be accumulated. Individual

accumulators, each containing a single processed raw frame, will be published as part of an FPA-set. In

contrast, “cc_config4” does perform actual accumulations (4 raw frames per accumulator). In this

example, the instrument builder wants to do the following:

1. Acquire 1 FPA-set using “cc_config3” giving this acquisition a 1 second time-slice.

2. Acquire 1 FPA-set using “cc_config4” giving this acquisition a 1 second time-slice.

3. Repeat Steps 1 & 2 twice.

The DAT is illustrated in Figure 26.

Figure 26: DAT Example #7 - Multiple Accumulators


MAN-0008, Rev F 66

To help identify the filter and filter wheel position, instrument supplied meta-data is defined in data-tier 2.

Assume the same global attributes as defined in the previous accumulation example.

NOTE: This may not be a particularly realistic example and is only provided to illustrate the difference in

how the CSS reports the contents of a given FPA when accumulations are enabled.

The following pages contain the meta-data that will be published with the FPA’s. Each section of this

table corresponds to the meta-data published with an FPA.





















































MAN-0008, Rev F 67





























































MAN-0008, Rev F 68



























































MAN-0008, Rev F 69

Instrument Specific Use Cases 5.3.

This section contains DATs for instrument specific use cases. In some cases, use cases have been

obtained from the instrument scientist. In others, examples of the types of observations that may be made

with a particular type of instrument have been obtained from the NSO scientific staff. In all examples

presented some assumptions have been made to fully illustrate the example and these assumptions will be

explained on a case by case basis. Each use case will contain a synopsis and a DAT. Unlike the examples

presented in Section 5.2, output meta-data will not be listed.

For each use case only one version of a DAT is presented. There are many different ways that DATs can

be organized or modified where they still meet the basic requirements of the use case but perhaps result in

FPA-sets being published with a different data-tier organization.

For all examples:

1. The Year/Month/Day will be omitted from any timestamps.

2. Values contained in the attribute tables for .global:referenceT0 contain “don’t care” indicators of

xx:xx:xx for hours, minutes, and seconds. The portion of the timestamp value that is of

importance is the sub-seconds. If these DATs are executed then a reference time that contains a

value compatible with the specified sub-seconds must be supplied.

3. Values contained in the attribute tables for .global:initialStartTime contain “don’t care” indicators

of yy:yy:yy for hours, minutes, and seconds. The portion of the timestamp value that is of

importance is the sub-seconds. If these DATs are executed and a start command issued (i.e.

.global:startMode=”atStartTime” and .global:camMode=”startWith(out)Save”) then the initial

start must:

a. Be greater than the current time and contain a value compatible with the specified sub-

seconds.

When a DAT is executing in preview mode, the value of .global:startTime is a “don’t care”.

4. Global attributes used for ID management will not be part of the examples. This includes

.global:copyID, .global:deleteID, .global:idList, .global:id0List.

5. Global attributes .global:cameraID, .global:cameraLine, and .global:topicName will not be

illustrated. These attributes are “read” only and cannot be submitted to the CSS.

Note: Any instrument supplied meta-data attribute names provided in the following use cases have

been selected for illustrative purposes only! There is no intent in these examples to match the

requirements set forth in SPEC-0122, DKIST Data Model.

5.3.1. VBI Use Cases

The following sets of use cases are specific to the VBI. General requirements for these use cases were

obtained from the VBI instrument scientist. The following set of meta-data is required by the VBI to

accompany each published FPA. The following table lists this meta-data and whether it is automatically

supplied by the CSS or will be passed as instrument supplied meta-data in an execution block.

Required Metadata: Metadata Source

FPA-set: BITPIX Automatically supplied by CSS

NAXIS Automatically supplied by CSS

NAXIS1,2,3 Automatically supplied by CSS

PIXELSIZX,Y [arcs] Automatically supplied by CSS

FOVID [position of current FPA-set in the whole FOV] Supplied by VBI

FOVN [how many positions in the FOV scan] Supplied by VBI

FOVPAT [what pattern was used to scan the FOV] Supplied by VBI

WAVELENGTH [nm] Supplied by VBI

FPA: DATE-OBS Automatically supplied by CSS


MAN-0008, Rev F 70

The following general guidelines also apply to all examples:

In all cases only 1 accumulator is defined therefore 1 FPA-set = 1 accumulator.

Accumulations are disabled: :accum:sequence = [1], :accum:numCycles = 1.

5.3.1.1. VBI Use Case #1

General Scenario Guidelines/Assumptions

VBI is configured to observe image bursts at a single wavelength continuously.

Supplied pseudo-code

while (!done and !interrupted)

*wavelength: 430 nm (G-band)

*exposure time: 10 ms

*number of images in frameset: 80

*binning: 1x1

*frameset cadence: 3 s

*frame rate: 30 fps

end while

Global Attributes and Camera Configuration

.global<:Attribute Name> Attribute Value .camConfig<:Attribute Name> Attribute Value

:referenceT0 xx:xx:xx.000 :ID “cc_vbi1”

:initialStartTime N/A :description “30Hz; 10ms”

:ID0 “eb_vbi_uc1_1” :exposure:rate 30.0

:execCount0 0 :exposure:rateMultiplier 1.0

:startMode “immediate” :exposure:ratePhase 0.0

:camMode “preview” :exposure:time 10.0

:linearityCorrection:enable true :accum:numberOf 1

:linearityCorrection:tableName “2k_linearity_table” :accum:sequence [ 1 ]

:observationIDs “id1”,”id2”,”id3” :accum:posAtRefT0 1

:passThrough:enable true :accum:numCycles 1

:passThrough:metaData “I am Groot” :winBin:hw:binSize [ 1, 1 ]

:paramSetDB:category “css” :winBin:hw:win:numberOfROIs 1

:paramSetDB:name “examples” :winBin:hw:win:ROI_1 [ 0, 0, 2560, 2160 ]

:winBin:sw:binSize [ 1, 1 ]

:winBin:sw:win:numberOfROIs 1

:winBin:sw:win:roiType “vertical”

:winBin:sw:win:ROI_1 [ 0, 0, 2560, 2160 ]

:normalization:method “none”

:normalization:value N/A

:bufferEnable false


MAN-0008, Rev F 71

Data Acquisition Tree

Figure 27: DAT - VBI Use Case #1



VBI is configured to observe image bursts at 3 different wavelengths continuously.



for wavelength in [430, 450, 486] nm

*exposure time (corresp. to wavelength): [10, 5, 20] ms


*binning (corresp. to wavelength): [1x1, 1x1, 2x2]

*frameset cadence: 3 s

*frame rate: 30 fps

end for

end while

Global Attributes and Camera Configurations

.global<:Attribute Name> Attribute Value

:referenceT0 xx:xx:xx.000

:initialStartTime yy:yy:yy.000

:ID0 “eb_vbi_uc2_1”

:execCount0 0


:camMode “preview”

:linearityCorrection:enable true

:linearityCorrection:tableName “2k_linearity_table”

:observationIDs “id1”,”id2”,”id3”

:passThrough:enable true

:passThrough:metaData “I am Groot”



.camConfig<:Attribute Name> Attribute Value

:ID “cc_vbi1” “cc_vbi2” “cc_vbi3”

:description “30Hz; 10ms” “30Hz; 5ms” “30Hz; 20ms, 2x2”

:exposure:rate 30.0 30.0 30.0

:exposure:rateMultiplier 1.0 1.0 1.0

:exposure:ratePhase 0.0 0.0 0.0

:exposure:time 10.0 5.0 20.0


MAN-0008, Rev F 72

:accum:numberOf 1 1 1

:accum:sequence [ 1 ] [ 1 ] [ 1 ]

:accum:posAtRefT0 1 1 1

:accum:numCycles 1 1 1

:winBin:hw:binSize [ 1, 1 ] [ 1, 1 ] [ 1, 1 ]

:winBin:hw:win:numberOfROIs 1 1 1

:winBin:hw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ]

:winBin:sw:binSize [ 1, 1 ] [ 1, 1 ] [ 2, 2 ]

:winBin:sw:win:numberOfROIs 1 1 1

:winBin:sw:win:roiType “vertical” “vertical” “vertical”

:winBin:sw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ]

:normalization:method “none” “none” “none”

:normalization:value N/A N/A N/A

:bufferEnable false false false

NOTE: The camera configuration “cc_vbi1” is identical to that from Use Case #1 and can (should) be

reused. There is no need to redefine with a different ID.





VBI is configured to observe bursts/one image/10 images at 4 different wavelengths

continuously.



MAN-0008, Rev F 73


for wavelength in [393, 430, 486, 450] nm

*exposure time (corresponding to wavelength): [20, 10, 20, 5] ms

*number of images in frameset (corresp. to wavel.): [10, 80, 1, 80]

*binning (corresp. to wavelength): [2x2, 1x1, 2x2, 1x1]

*frameset cadence (corresp. to wavelength): [0.5, 3, 0.25, 3] s

*frame rate: 30 fps

end for

end while

NOTE: The cadence value of 0.25 for set #3, as supplied by the instrument scientist, is not evenly

divisible by 1/rate. The next trigger, and subsequent raw frame that the CSS will want to process,

will not occur for another 0.0166666666 seconds. A cadence and subsequent timeSlice value that

will fall on a 1/30s boundary is 0.266666666. The example execution block will reflect this change.






:execCount0 0












:description “30Hz; 10ms” “30Hz; 5ms” “30Hz; 20ms; 2x2”






:accum:sequence [ 1 ] [ 1 ] [ 1 ]





:winBin:hw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ]




:winBin:sw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ]





MAN-0008, Rev F 74

NOTE: This use case uses the exact same camera configurations as Use Case #2. The order in which

camera configurations are utilized and the number of FPA-sets that will be generated using each camera

configuration differs. These differences are contained within a unique execution block.





VBI is configured to observe bursts of data at 2 wavelengths in field sampling mode to cover

the full field of view.



for wavelength in [393, 430] nm

for camera stage position [1, 2, ..., N]

* exposure time (corresponding to wavelength): [20, 10] ms

* number of images in frameset (corresp. to wavel.): [80, 80]

* binning (corresp. to wavelength): [3x3, 1x1]

* frameset cadence (corresp. to wavelength): [3, 3] s

* frame rate: 30 fps

end for

end for


MAN-0008, Rev F 75

end while






:execCount0 0











:ID “cc_vbi1” “cc_vbi4”

:description “30Hz; 10ms” “30Hz; 20ms; 3x3”

:exposure:rate 30.0 30.0

:exposure:rateMultiplier 1.0 1.0

:exposure:ratePhase 0.0 0.0

:exposure:time 10.0 20.0

:accum:numberOf 1 1






:winBin:hw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ]




:winBin:sw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 2, 2, 2043, 2043 ]




Other Assumptions Made

The following 2k x 2k FOV numbering and acquisition patterns are assumed:

FOV Numbering FOVPAT=LRBT FOVPAT=LRTB

31 32 33 34 35 36 X ← ← ← ← ← Start Here: → → → → → ↓

25 26 27 28 29 30 → → → → → ↑ ↓ ← ← ← ← ←

19 20 21 22 23 24 ↑ ← ← ← ← ← → → → → → ↓

13 14 15 16 17 18 → → → → → ↑ ↓ ← ← ← ← ←

07 08 09 10 11 12 ↑ ← ← ← ← ← → → → → → ↓

01 02 03 04 05 06 Start Here: → → → → → ↑ X ← ← ← ← ←


MAN-0008, Rev F 76



For this specific example, and using the number of execution blocks and camera configurations as

defined, there are three different methods to achieve the same timing characteristics of taking 2 sets of 36

bursts, where each burst is spaced 3 seconds apart. They are as follows:

Method #1: Use the execution blocks as illustrated in Figure 30.

Method #2: Make the following modifications:

In execution block “eb_vbi_uc4_2” – set :timeSlice[0] = 3.0


In execution block “eb_vbi_uc4_1” – set :timeSliceRepeats = false, :timeSlice[0] = 108.0

and :timeSlice[1] = 108.0.

Method #3: Make the following modifications:



In execution block “eb_vbi_uc4_1” – set :timeSlice[0] = 0.0 and :timeSlice[1] = 0.0. These

time slices can be set to 0.0 in this case because the 3.0s slice required by each “burst” is

defined in “eb_vbi_uc4_2” and “eb_vbi_uc4_3”. In effect, Method #2 and Method #3 are

identical in that the expiration of the 36th execution of “eb_vbi_uc4_2” and “eb_vbi_uc4_3”

is coincident with expiration of the 108s time slices in “eb_vbi_uc4_1”. Therefore the

timeSlice values in “eb_vbi_uc4_1” can be set to 0.0.


MAN-0008, Rev F 77

5.3.1.5. VBI Use Case #5 – Modulator Synchronization


VBI is configured to observe image bursts at a single wavelength continuously. This is the

same scenario as VBI Use Case #1 with the following exceptions as specified by the VBI

team:

o Exposures are synchronized to a rotating modulator.

o Desired modulation state change occurs at 20Hz. Exposure rate decreased to 20Hz to

match desired modulation state change rate.

o Burst cadence decreased to 4.3s to accommodate modulator synchronization at 20Hz.

o 45ms are added to the initial start time to align with the phase of first exposure.

o The camera configuration exposure rate phase is set to 0.9. The comment provided by

the VBI team is as follows:

“0.9 of 1/20 s is 45ms, thus for 10ms exposure we get 5ms before/after V=0”

Supplied pseudo-code (Modifications to VBI Use Case #1 pseudo-code are in red)


*wavelength: 430 nm (G-band)

*exposure time: 10 ms


*binning: 1x1

*frameset cadence: 4.3 s

*frame rate: 20 fps

end while

Global Attributes and Camera Configuration


:referenceT0 xx:xx:xx.000 :ID “cc_vbi5”

:initialStartTime yy:yy:yy.045 :description “20Hz; 10ms”

:ID0 “eb_vbi_uc5_1” :exposure:rate 20.0


:startMode “atStartTime” :exposure:ratePhase 0.9

:camMode “startWithSave” :exposure:time 10.0


:linearityCorrection:tableName “2k_linearity_table” :accum:sequence [ 1 ]









:winBin:sw:win:ROI_1 [ 0, 0, 2560, 2160 ]



:bufferEnable false


MAN-0008, Rev F 78


Figure 31: DAT - VBI Use Case #5 – Modulator Synchronization

5.3.1.6. VBI Use Case #6 – Modulator Synchronization


VBI is configured to observe image bursts at 3 different wavelengths continuously. This is

the same scenario as VBI Use Case #2 with the following exceptions:

o Exposures are synchronized to a rotating modulator.

o Desired modulation state change occurs at 20Hz. Exposure rate decreased to 20Hz to

match desired modulation state change rate.

o Instrument mechanism time is 0.333s.

o Camera readout time is 0.005s.

o Burst cadence set to as close to 4.35s as possible with respect to modulation.

o 45ms are added to the initial start time to align with the phase of first exposure.

o The camera configuration exposure rate phase differs between each camera

configuration. The comments provided by the VBI team for “cc_vbi5”, “cc_vbi6”,

and “cc_vbi7” respectively are as follows:

“0.9 of 1/20s is 45ms, thus for 10ms exposure we get 5ms before/after V=0”

“0.95 of 1/20 is 47.5ms, thus for 5ms exposure we get 2.5ms before/after V=0”

“0.8 of 1/20s is 40ms, thus for 20ms exposure we get 10ms before/after V=0”

Supplied pseudo-code (Modifications to VBI Use Case #2 pseudo-code are in red)


for wavelength in [430, 450, 486] nm

*exposure time (corresp. to wavelength): [10, 5, 20] ms


*binning (corresp. to wavelength): [1x1, 1x1, 2x2]

*frameset cadence: ~4.35 s

*frame rate: 20 fps

end for

end while


MAN-0008, Rev F 79






:execCount0 0












:description “20Hz; 10ms” “20Hz; 5ms” “20Hz; 20ms, 2x2”






:accum:sequence [ 1 ] [ 1 ] [ 1 ]





:winBin:hw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ]




:winBin:sw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ]




NOTE: The camera configuration “cc_vbi5” is identical to that from Use Case #5 and can (should) be

reused in this use case. There is no need to redefine with a different ID.


MAN-0008, Rev F 80


Figure 32: DAT - VBI Use Case #6 – Modulator Synchronization


MAN-0008, Rev F 81

5.3.2. 2-D Tunable Instrument - Spectroscopy Use Cases

The following use cases serve as a sampling of the types of observations that may be conducted with a 2-

Dimensional Tunable Instrument doing Spectroscopy. General requirements for these use cases were

obtained from NSO scientific staff. The following general guidelines were supplied and apply to each use

case:

Observe in 4 different pre-filters (5434, 5896, 6563, and 8542) and scan the corresponding lines

from Wavelength 1 to Wavelength N. N = wavelength points per pre-filter where:

o 5434: N = 16

o 5896: N = 17

o 6563: N = 13

o 8542: N = 17

Set the first and last 3 wavelengths in the 5434, 5896 and 6563 filter to an exposure time of 10ms,

and all other wavelengths to 40ms.

Data for these examples was obtained from the “vtf_example_spectroscopy_data.txt” file

provided by NSO science staff. This file was used for the following:

o Timing characteristics for tuning and data acquisition.

o Fabry-Pérot tuning voltages, pre-filter wavelength, filter wheel position number, and

relative tuning wavelength from pre-filter core. This data will be used as instrument

supplied meta-data to be published with the FPA’s of these examples.

The file is located in the ATST vault in the following directories:

\SysDocs\3.0 Inst Sys\3.6 Cameras\Docs\CSS Attributes\Rev X.X Examples\2D Tunable Instrument\Spectroscopy

In addition to these general guidelines, assumptions may have been made to facilitate demonstrating how

data acquisition by the CSS can be synchronized with instrument activities including, but not limited to:

pre-filter tuning and Fabry-Pérot tuning. This includes assumptions that deal with instrument tuning times

and possible instrument supplied meta-data.

For all wavelength positions in each example it is assumed that the following instrument supplied meta-

data will be defined and must accompany the FPA-sets published by the CSS:

Required Metadata Comment

FILTER Specifies pre-filter wavelength

FLTPOS Specifies pre-filter position in filter wheel

RELWAVE Specifies the relative wavelength from the pre-filter

FP1V1 Fabry-Pérot 1 Voltage


The spectroscopy use cases presented are based on the same basic set of requirements as listed above.

Therefore, in order to save space in the DAT diagrams the :metaDataSets[] vectors for each of the core

filters (5434, 5896, 6563, and 8542) are listed in the following table. The DAT diagram will reference this

table. The first column in the table is the :metaDataSets[] vector index. The second column indicates

meta-data set number and is for illustrative purposes only. The remaining four columns contain the meta-

data strings that will be used as the :metaDataSets[] vector in an execution block for each of the observed

filter position.

index Set # Wavelength Meta-data Sets for each Filter

5434 5896 6563 8542

0 1: RELWAVE=-0.8865 RELWAVE=-0.5159 RELWAVE=-2.0276 RELWAVE=-2.0359

1 1: FP1V1=-705 FP1V1=-182 FP1V1=-1144 FP1V1=-864

2 1: FP2V2=-35 FP2V2=-173 FP2V2=-819 FP2V2=-178



MAN-0008, Rev F 82


5434 5896 6563 8542

4 2: FP1V1=-486 FP1V1=20 FP1V1=-779 FP1V1=-585

5 2: FP2V2=28 FP2V2=-115 FP2V2=-714 FP2V2=-98


7 3: FP1V1=-399 FP1V1=104 FP1V1=-414 FP1V1=-307

8 3: FP2V2=53 FP2V2=-91 FP2V2=-609 FP2V2=-18


10 4: FP1V1=-354 FP1V1=142 FP1V1=-52 FP1V1=-25

11 4: FP2V2=66 FP2V2=-80 FP2V2=-505 FP2V2=63


13 5: FP1V1=-333 FP1V1=163 FP1V1=133 FP1V1=114

14 5: FP2V2=72 FP2V2=-74 FP2V2=-452 FP2V2=103


16 6: FP1V1=-308 FP1V1=184 FP1V1=258 FP1V1=169

17 6: FP2V2=79 FP2V2=-68 FP2V2=-416 FP2V2=119


19 7: FP1V1=-287 FP1V1=204 FP1V1=314 FP1V1=211

20 7: FP2V2=85 FP2V2=-62 FP2V2=-400 FP2V2=131

21 8: RELWAVE=-0.3958 RELWAVE=-0.0255 RELWAVE=0.0528 RELWAVE=-0.0691

22 8: FP1V1=-274 FP1V1=215 FP1V1=369 FP1V1=235

23 8: FP2V2=89 FP2V2=-59 FP2V2=-384 FP2V2=138


25 9: FP1V1=-267 FP1V1=225 FP1V1=494 FP1V1=253

26 9: FP2V2=91 FP2V2=-56 FP2V2=-348 FP2V2=143

27 10: RELWAVE=-0.3753 RELWAVE=-0.0045 RELWAVE=0.4791 RELWAVE=0.0006

28 10: FP1V1=-256 FP1V1=232 FP1V1=679 FP1V1=274

29 10: FP2V2=94 FP2V2=-54 FP2V2=-295 FP2V2=149

30 11: RELWAVE=-0.3594 RELWAVE=0.009 RELWAVE=0.9768 RELWAVE=0.0382

31 11: FP1V1=-242 FP1V1=243 FP1V1=1041 FP1V1=295

32 11: FP2V2=98 FP2V2=-51 FP2V2=-191 FP2V2=155


34 12: FP1V1=-221 FP1V1=264 FP1V1=1406 FP1V1=336

35 12: FP2V2=104 FP2V2=-45 FP2V2=-86 FP2V2=167


37 13: FP1V1=-200 FP1V1=284 FP1V1=1771 FP1V1=392

38 13: FP2V2=110 FP2V2=-39 FP2V2=19 FP2V2=183

39 14: RELWAVE=-0.2888 RELWAVE=0.0856 RELWAVE=0.4677

40 14: FP1V1=-180 FP1V1=305 FP1V1=535

41 14: FP2V2=116 FP2V2=-33 FP2V2=224


43 15: FP1V1=-134 FP1V1=347 FP1V1=813

44 15: FP2V2=129 FP2V2=-21 FP2V2=304


46 16: FP1V1=-47 FP1V1=427 FP1V1=1095

47 16: FP2V2=154 FP2V2=2 FP2V2=385

48 17: RELWAVE=0.4859 RELWAVE=1.9674

49 17: FP1V1=629 FP1V1=1373

50 17: FP2V2=60 FP2V2=465

5.3.2.1. Spectroscopy Use Case #1


Take 1 image per wavelength step.

Repeat the sequence 100 times.


MAN-0008, Rev F 83

Set the first and last 3 wavelengths in the 5434, 5896 and 6563 filter to an exposure time of

10 ms, and all other wavelengths to 40 ms.

Using the supplied timing data, delta times between wavelength steps are rounded up to

175ms. 175ms accommodates exposure and filter tuning time.

Cameras will be run at a 5.714Hz rate.

Tuning the pre-filter to a new position takes 875ms.

Derived pseudo-code

do[ 100 times ]

for [ filter in 5434, 5896, 6563, 8542 ]

for [ each wavelength 1 thru N ]

Acquire 1 raw frame, process, and save





:ID0 “eb_2dSpec_uc1”

:execCount0 100


:camMode “startWithSave”









:ID “cc_2dSpec1” “cc_2dSpec2”

:description “5.71Hz; 10ms” “5.714Hz; 40ms”





:accum:numberOf 1 1






:winBin:hw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ]




:winBin:sw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ]





MAN-0008, Rev F 84


Figure 33: DAT - 2-D Tunable Instrument, Spectroscopy Use Case #1

5.3.2.2. Spectroscopy Use Case #2


Take 5 images per wavelength step. Repeat the sequence 10 times.

Cameras will be run at a 25Hz rate.


MAN-0008, Rev F 85

It takes 200ms to acquire 5 raw frames (includes time to the next trigger where Fabry-Pérot

tuning occurs).

It takes 100ms to tune the Fabry-Pérot and tuning occurs on a 25Hz referenced time slice.

Data acquisition for each wavelength occupies a 320ms timeSlice calculates as follows:

timeSlice = (5 * 1/25) + 0.100 rounded up to nearest 1/rate slice.

No Fabry-Pérot tuning time at last wavelength (it is included in the time of the filter change)

It takes 875ms to change the filter position and occurs on a 25Hz referenced time slice.

Total Time per Filter = (.32 * (N-1)) + .2 + .875

This result is rounded up to the nearest 25Hz referenced time slice.

Derived pseudo-code

do[ 10 times ]

for [ filter in 5434, 5896, 6563, 8542 ]


for [ S = 1 thru 5 ]

Acquire 1 raw frame, process, and save





:ID0 “eb_2dSpec_uc1”

:execCount0 10


:camMode “startWithSave”









:ID “cc_2dSpec3” “cc_2dSpec4”

:description “25.0Hz; 10ms” “25.0Hz; 40ms”





:accum:numberOf 1 1






:winBin:hw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ]




:winBin:sw:win:ROI_1 [ 0, 0, 2560, 2160 ] [ 0, 0, 2560, 2160 ]



MAN-0008, Rev F 86




Figure 34: DAT - 2-D Tunable Instrument, Spectroscopy Use Case #2

NOTE: The structure in this DAT could also be applied to 2-D Spectroscopy Use Case #1. Timing

differences do not permit the two use cases to share the same execution blocks but the overall structure is

applicable. To meet the requirements of Use Case #1: 1) The :timeSlice values in Data-tiers 2 and 3 must

be changed to match those in Data-tiers 2 and 3 of Use Case #1, and 2) The :execCount entries in the

execution blocks of Data-tier 4 would contain values of 1 rather than 5.


MAN-0008, Rev F 87

5.3.3. 2-D Tunable Instrument - Spectropolarimetry Scenarios

The following use cases serve as a sampling of the types of observations that may be conducted with a 2-

Dimensional Tunable Instrument doing Spectropolarimetry. General requirements for these use cases

were obtained from NSO scientific staff. The following general guidelines were supplied and apply to

each use case:

Observe in 4 different pre-filters (5434, 5896, 6563, and 8542) and scan the corresponding lines

from Wavelength 1 to Wavelength N. N = wavelength points per pre-filter where:

o 5434: N = 16

o 5896: N = 17

o 6563: N = 13

o 8542: N = 17

Examples use 4 mixed modulation states.

Data for these examples was obtained from the “vtf_example_spectroscopy_data.txt” file

provided by NSO science staff. This file was used for the following:

o Timing characteristics for tuning and data acquisition.

o Fabry-Pérot tuning voltages, pre-filter wavelength, filter wheel position number, and

relative tuning wavelength from pre-filter core. This data will be used as instrument

supplied meta-data to be published with the FPA’s of these examples.

The file is located in the ATST vault in the following directories:

\SysDocs\3.0 Inst Sys\3.6 Cameras\Docs\CSS Attributes\Rev X.X Examples\2D Tunable Instrument\Spectroscopy

In addition to these general guidelines, assumptions may have been made to facilitate demonstrating how

data acquisition by the CSS can be synchronized with instrument activities including, but not limited to:

pre-filter tuning and Fabry-Pérot tuning, and modulator state changes. This includes assumptions that deal

with instrument tuning times and possible instrument supplied meta-data.

For all wavelength positions in each example it is assumed that the following instrument supplied meta-

data will be defined and must accompany the FPA-sets published by the CSS:

Required Metadata Comment

FILTER Specifies pre-filter wavelength

FLTPOS Specifies pre-filter position in filter wheel

RELWAVE Specifies the relative wavelength from the pre-filter



The spectropolarimetry use cases presented are based on the same basic set of requirements as listed

above. Therefore, in order to save space in the DAT diagrams the :metaDataSets[] vectors for each of the

core filters (5434, 5896, 6563, and 8542) are listed in the following table. The DAT diagram will

reference this table. The first column in the table is the :metaDataSets[] vector index. The second column

indicates meta-data set number and is for illustrative purposes only. The remaining four columns contain

the meta-data strings that will be used as the :metaDataSets[] vector in an execution block for each of the

observed filter position.


5434 5896 6563 8542


1 1: FP1V1=-705 FP1V1=-182 FP1V1=-1144 FP1V1=-864

2 1: FP2V2=-35 FP2V2=-173 FP2V2=-819 FP2V2=-178


4 2: FP1V1=-486 FP1V1=20 FP1V1=-779 FP1V1=-585


MAN-0008, Rev F 88


5434 5896 6563 8542

5 2: FP2V2=28 FP2V2=-115 FP2V2=-714 FP2V2=-98


7 3: FP1V1=-399 FP1V1=104 FP1V1=-414 FP1V1=-307

8 3: FP2V2=53 FP2V2=-91 FP2V2=-609 FP2V2=-18


10 4: FP1V1=-354 FP1V1=142 FP1V1=-52 FP1V1=-25

11 4: FP2V2=66 FP2V2=-80 FP2V2=-505 FP2V2=63


13 5: FP1V1=-333 FP1V1=163 FP1V1=133 FP1V1=114

14 5: FP2V2=72 FP2V2=-74 FP2V2=-452 FP2V2=103


16 6: FP1V1=-308 FP1V1=184 FP1V1=258 FP1V1=169

17 6: FP2V2=79 FP2V2=-68 FP2V2=-416 FP2V2=119


19 7: FP1V1=-287 FP1V1=204 FP1V1=314 FP1V1=211

20 7: FP2V2=85 FP2V2=-62 FP2V2=-400 FP2V2=131


22 8: FP1V1=-274 FP1V1=215 FP1V1=369 FP1V1=235

23 8: FP2V2=89 FP2V2=-59 FP2V2=-384 FP2V2=138


25 9: FP1V1=-267 FP1V1=225 FP1V1=494 FP1V1=253

26 9: FP2V2=91 FP2V2=-56 FP2V2=-348 FP2V2=143

27 10: RELWAVE=-0.3753 RELWAVE=-0.0045 RELWAVE=0.4791 RELWAVE=0.0006

28 10: FP1V1=-256 FP1V1=232 FP1V1=679 FP1V1=274

29 10: FP2V2=94 FP2V2=-54 FP2V2=-295 FP2V2=149


31 11: FP1V1=-242 FP1V1=243 FP1V1=1041 FP1V1=295

32 11: FP2V2=98 FP2V2=-51 FP2V2=-191 FP2V2=155


34 12: FP1V1=-221 FP1V1=264 FP1V1=1406 FP1V1=336

35 12: FP2V2=104 FP2V2=-45 FP2V2=-86 FP2V2=167


37 13: FP1V1=-200 FP1V1=284 FP1V1=1771 FP1V1=392

38 13: FP2V2=110 FP2V2=-39 FP2V2=19 FP2V2=183


40 14: FP1V1=-180 FP1V1=305 FP1V1=535

41 14: FP2V2=116 FP2V2=-33 FP2V2=224


43 15: FP1V1=-134 FP1V1=347 FP1V1=813

44 15: FP2V2=129 FP2V2=-21 FP2V2=304


46 16: FP1V1=-47 FP1V1=427 FP1V1=1095

47 16: FP2V2=154 FP2V2=2 FP2V2=385

48 17: RELWAVE=0.4859 RELWAVE=1.9674

49 17: FP1V1=629 FP1V1=1373

50 17: FP2V2=60 FP2V2=465

5.3.3.1. Modulation Scenario #1 – No accumulations

Scenario Table (supplied by NSO scientific staff):

Wavelength 1 Wavelength 2 … Wavelength N

Mod 1 ,…, Mod 4, t1 ,…, t4 Mod 1,…,Mod 4, t5 ,…, t8 … Mod 1 ,…, Mod 4, tN-3, …, tN

Where: M = number of accumulations/sample. Mod 11 denotes modulation state 1 out of 4.


MAN-0008, Rev F 89

The "purple" denotes in which "direction" time proceeds.


Take 4 modulation state images per wavelength and then tune to the next wavelength.

Save each modulation state image - No Accumulations (M = 1).

S = 4 = # modulation states.

Exposure times are fixed at 20ms for all wavelengths.

Repeat observations for 4 filters 100 times.


It takes 133ms to acquire 4 raw frames (includes time to the next trigger where Fabry-Pérot

tuning occurs).

LCVR can change state < 1ms; state changes are scheduled by the instrument to occur at the

end of the exposure and state changes are referenced to T0 and occur within the 1/rate time.


Data acquisition for each wavelength occupies a 233ms timeSlice calculated as follows:

timeSlice = (4 * 1/30) + 0.100 : rounded up to nearest 30Hz referenced time slice.

No Fabry-Pérot tuning time at last wavelength (it is included in the time of the filter change).


Total Time per Filter = (.233333 * (N-1)) + .133333 + .875 : rounded up to nearest 30Hz

referenced time slice.

NOTE: This scenario results in the CSS publishing FPA-sets which consist of 4 FPAs. Each

FPA contains one (1) processed raw frame that was acquired coincident with a modulation

state. Only one FPA-set per wavelength will be acquired and published.

Derived pseudo-code

do[ 100 times ]

for [ filter in 5434, 5896, 6563, 8542 ]


Acquire Mod 1, Mod 2, Mod 3, Mod 4 and save



:referenceT0 xx:xx:xx.000 :ID “cc_2dSPol1”


:ID0 “eb_2dSPol_uc1a” :exposure:rate 30.0





:linearityCorrection:tableName “2k_linearity_table” :accum:sequence [ 1, 2, 3, 4 ]










MAN-0008, Rev F 90


:winBin:sw:win:ROI_1 [ 0, 0, 2560, 2160 ]



:bufferEnable false


Figure 35: DAT - 2-D Tunable Instrument, Spectropolarimetry Scenario #1

5.3.3.2. Modulation Scenario #1a – No accumulations, Variation on Scenario #1

An variation of Scenario #1 is to repeat acquisition of Mod 1 thru Mod 4 at each wavelength step C times

and save all modulation state images with no accumulations. This modification is denoted as Scenario 1a.

Derived pseudo-code

do[ 100 times ] {

for [ filter in 5434, 5896, 6563, 8542 ] {

for [ each wavelength 1 thru N ] {

for [ 1 to C ] {

for [ 1 to S ] {


MAN-0008, Rev F 91

Mod State Accumulator #S = raw Frame

} // End S Loop

Save S Mod State Accumulators

} // End C Loop

} // End N Loop

} // End filter loop

}


The general scenario guidelines and assumptions for this example are identical to the

previous example (Modulation Scenario #1 – No accumulations) with the following

distinctions:

o An assumption is made that a user may want to acquire C FPA-sets per wavelength

where C ≥ 1.

o For this variation on Scenario #1, C = 4 = # modulation state sets per wavelength. This

results in the CSS publishing four (4) FPA-sets per wavelength. Each FPA-set consists of

4 FPAs for a total of 16 FPAs per wavelength. Each FPA contains one (1) processed raw

frame that was acquired coincident with a modulation state.

The DAT presented in this example illustrates some unique points:

1. It illustrates the use of the camera configuration “cc_NoOp” to introduce delays in data

acquisition per the requirements of Scenario #1. Use of the “cc_NoOp” camera configuration is

highlighted in red in the DAT.

2. Unlike all other DATs in this document where absolute time slice values are defined to meet the

requirements of the use case, this DAT divorces both the number of wavelength (sample) points

and the amount of data being acquired at any given wavelength from the timing requirements of

the scenario. Namely, the only timing requirements this DAT is concerned with are:

a. 100ms to tune the Fabry-Pérot and tuning occurs on a 30Hz referenced time slice.

This requirement is met in execution block “eb_2dSPol_uc1af” which contains the number of

FPA-sets to acquire (:execCount[0] = 4) followed by execution of a “cc_NoOp” with a

timeSlice of 100ms, which is the amount of time required to tune the Fabry-Pérot.

b. 875ms to change the filter position and occurs on a 30Hz referenced time slice.

This requirement is met through a combination of the 100ms NoOp in “eb_2dSPol_uc1af”

and the 800ms time slice of the “cc_NoOp” acquireNodes of “eb_2dSPol_uc1ab”. Following

N wavelength points for a given filter, the instrument requires 875ms to change the filter.

100ms has already transpired so 775ms are still needed. A timeSlice value of 800ms per

“cc_NoOp” delays processing the next acquireNode until a 1/rate (1/30) referenced trigger. It

would be perfectly acceptable to simply put 0.775 as the timeSlice value. When the 775ms

NoOp expires the CSS will immediately proceed to the next acquireNode where it must wait

for the next trigger and raw frame. The trigger will not occur for another 25ms so the CSS

will simply wait. Either approach is acceptable.

3. Using the technique presented, it is possible simply modify the :execCount[i] entries in the

execution blocks contained in data-tiers 3 and 4 to either change the number of wavelength points

or the number of FPA-sets without the need to recalculate and modify time slice values in the

entire tree. Of course, if the number of wavelength points are changed then, as this scenario is

defined, the number of instrument supplied meta-data sets contained in the execution block must

be changed to match.


MAN-0008, Rev F 92


Figure 36: DAT - 2-D Tunable Instrument, Spectropolarimetry Scenario #1a

NOTE: The “cc_NoOp” acquireNodes in execution block “eb_2dSPol_uc1aa” could have been placed in

the execution blocks of data-tier 3 and the effect would be the same.


MAN-0008, Rev F 93

NOTE: If the timeSlice values used in conjunction with the “cc_NoOp” acquireNodes in execution block

“eb_2dSPol_uc1aa” had contained the value of 0.77500 instead of 0.800000 then this would have been

reflected in the data-tier meta-data published with each FPA of the FPA-sets. The result would be a

difference between the scheduled and actual time stamps for data-tier 2. Specifically, there would be a

0.025s difference between .css:dataTier:timeStamp:scheduled[1] (which occurs 775ms following

completion of N executions of “eb_2dSPol_uc1af”) and .css:dataTier:timeStamp:actual[1] (which occurs

on a (1/30)s boundary.

5.3.3.3. Modulation Scenario #1 with M accumulations – Option #1



Mod 11 ,..., Mod 1M , t1 ,..., tM Mod 11 ,..., Mod 1M , 4tM+1 ,..., 5tM ↓ ↓ Mod 21 ,..., Mod 2M , tM+1 ,..., 2tM Mod 21 ,..., Mod 2M , 5tM+1 ,..., 6tM … ↓ Mod 31 ,..., Mod 3M , 2tM+1 ,..., 3tM ↓ … ↓ Mod 41 ,..., Mod 4M , 3tM+1 ,..., 4tM ↓ ↗ ↗

Where: M = number of accumulations/sample. Mod 11 denotes modulation state 1 out of 4. The "purple" denotes in which "direction" time proceeds.


Take modulation state images per wavelength and then tune to the next wavelength.

Accumulations enabled: M = 4 = # accumulations per state.

S = 4 = # modulation states.

Exposure times are fixed at 20ms for all wavelengths.

Repeat observations for 4 filters 100 times.


LCVR can change state < 1ms; state changes are scheduled by the instrument to occur at the

end of the exposure and state changes are referenced to T0 and occur within the 1/rate time.


Data acquisition for each wavelength occupies a 633ms timeSlice calculated as follows:

timeSlice = (16 * 1/30) + 0.100 : rounded up to nearest 30Hz referenced time slice.

No Fabry-Pérot tuning time at last wavelength (it is included in the time of the filter change).


Total Time per Filter = (.633333 * (N-1)) + .533333 + .875 : rounded up to nearest 30Hz

referenced time slice.

NOTE: This scenario results in the CSS publishing FPA-sets which consist of 4 FPAs. Each

FPA contains four (4) consecutively acquired, processed, and co-added raw frames (see the

defined accumulation sequence in the camera configuration).

Derived pseudo-code

do[ 100 times ]

for [ filter in 5434, 5896, 6563, 8542 ]


for [ 1 to S ]

for [ 1 to M ]

Mod State Accumulator #S += raw Frame


MAN-0008, Rev F 94










:linearityCorrection:tableName “2k_linearity_table” :accum:sequence [ 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4 ]









:winBin:sw:win:ROI_1 [ 0, 0, 2560, 2160 ]



:bufferEnable false


MAN-0008, Rev F 95


Figure 37: DAT - 2-D Tunable Instrument, Spectropolarimetry Scenario #1, Option #1


MAN-0008, Rev F 96

5.3.3.4. Modulation Scenario #1 with M accumulations – Option #2



Mod 11 ,..., Mod 41 , t1 ,..., t4 ↓ ↓ ↓ Mod 12 ,..., Mod 42 , t5 ,..., t ↓ … ↓ ….. ↓ … ↓ Mod 1M ,..., Mod 4M , 4tM-3 ,..., 4tM ↓ ↗ ↗

Where: M = number of accumulations/sample. Mod 11 denotes modulation state 1 out of 4. The "purple" denotes in which "direction" time proceeds.


The general scenario guidelines and assumptions for this example are identical to the previous

example (Modulation Scenario #1 with M accumulations – Option #1) with the following

distinction:

This scenario results in round robin co-addition of sixteen (16) consecutively acquired raw frames

into four (4) accumulators (4 co-added raw frames per accumulator). This, and different

execution block and camera configuration ID’s, is the only difference from the previous example.

The change in accumulation configuration is highlighted in red in the camera configuration.

Derived pseudo-code

do[ 100 times ]

for [ filter in 5434, 5896, 6563, 8542 ]


for [ 1 to M ]

for [ 1 to S ]

Mod State Accumulator #S += raw Frame










:linearityCorrection:tableName “2k_linearity_table” :accum:sequence [ 1, 2, 3, 4 ]









:winBin:sw:win:ROI_1 [ 0, 0, 2560, 2160 ]



:bufferEnable false


MAN-0008, Rev F 97


Figure 38: DAT - 2-D Tunable Instrument, Spectropolarimetry Scenario #1, Option #2


MAN-0008, Rev F 98

6. Java Utility Classes for Convenient Handling of CSS Metadata

The $ATST/src/java/atst/css/util/metadata directory contains several classes which are convenient for

handling CSS metadata. These classes are organized in a hierarchical class structure which closely

mimics CSS metadata namespaces. Metadata attribute values form the leaf nodes of the hierarchy as

final public member variables of the appropriate java type. Additionally, Java enum types are created

for string metadata attributes which define discrete states.

Figure 39: CSS Metadata Class Diagram

The interface is designed so that a user creates the entire hierarchy at once via construction of a

css.util.BdtMetaData object. This constructor recursively calls all component class constructors which

retrieve attribute values, validate them if necessary and use them to populate the leaf node class member

variables and enumerations. If any metadata is missing, invalid or corrupt, an

InvalidMetaDataException is thrown and construction fails. Upon successful construction the user is

guaranteed to have a complete set of metadata in a strongly typed ready-to-use form.

The below examples demonstrate various simple use cases:

Example 1 – Scrub Detection and Processing 6.1.

BdtMetaData meta = new BdtMetaData( bdtBuffer );

if ( meta.css.pub != null )

processFPA( bdtBuffer.getData(), meta.pub.fpa );

if ( meta.css.scrub != null ) {

Log.warn( “DAT scrub due to “ + meta.css.scrub.causedBy );

cancelCurrentOrPendingAction( meta.css.scrub );

}

Note that only variables documented as being potentially null can be so. These are generally metadata

elements that conditionally exist such as ROIs. Thus users do not need to check for null for every leaf

node accessed. Typically another variable exists which should be checked first (e.g. ROI count).

Example 2 – Burst Index Management 6.2.

Users of the CSS can create bursts by increasing the execCount of an execution block. The following

illustrates how to use the metadata to keep track of burst indices.


MAN-0008, Rev F 99

int dataTierIndex = meta.css.pub.dataTier.numDataTiers - 1;

int burstCount = meta.css.pub.dataTier.idCurrCount[ dataTierIndex ];

int burstSize = meta.css.pub.dataTier.idExecCount[ dataTierIndex ];

int burstID = meta.css.pub.dataTier.currentID[ dataTierIndex ];

Example 3 – Switch on Discrete States 6.3.

This example uses the camera mode in a switch statement:

switch ( meta.css.pub.global.camMode ) {

case PREVIEW:

case PRECONFIGURE:

Log.note( “Camera is idling, ignoring FPA.” );

break;

case START_WITHOUT_SAVE:

case START_WITH_SAVE:

processFPA( bdtBuffer );

default:

throw new IllegalArgumentException( “Invalid camera mode.” );

}


MAN-0008, Rev F 100

7. Advanced Topics

Parameter-set Database 7.1.

This section contains details on how execution of pkgDevel for the CSS configures the default camera

configuration and how to create and insert your own CSS parameter-sets and inserting them into the

parameter-set database.

7.1.1. Default Camera Configuration

The default camera configuration for your instance of the CSS is determined upon execution of pkgDevel

for the CSS under the following conditions:

./admin/pkgDevel css --make-all

./admin/pkgDevel css --load-prop

./admin/pkgDevel css --load-psets

For the sake of this discussion, execution of “./admin/pkgDevel css” with any of the above

command line flags will be referred to as cssDevel. Execution of cssDevel assures that there is an

executable default camera configuration in the parameter-set database for your installation.

The contents of the default camera configuration are dependent on the camera for which the CSS is being

configured. This is determined by the cssSite.config parameter CSS_CAMERA_NAME. The name

provided by this parameter leads cssDevel to the property table of the named camera which contains the

sensor size for that camera. cssDevel uses the sensor size to generate an “XxY” string. This string is

contained in the description field of the factory default camera configuration. cssDevel then uses this

string to compare what is currently the default in the parameter-set database vs. what the default should be

based on the selected camera. If a mismatch is detected, cssDevel re-generates “cc_default.pset” for the

selected camera.

By default, the contents of “cc_default.pset” are inserted into the parameter-set database using

category=”css”, name=”default”, id=”cc_default” (See Section 7.1.3 for additional details on the

Parameter-Set Database Category, Name, and ID).

If you defined a different parameter-set category and/or name with the cssSite.config parameters

CSS_PSETDB_CATEGORY and/or CSS_PSETDB_NAME then this same parameter-set is installed

using category=CSS_PSETDB_CATEGORY, name=CSS_PSETDB_NAME, id=”cc_default”.

To help eliminate repeated insertion of a default camera configuration into the parameter-set database,

cssDevel examines the contents of the database for category=”css”, name=”default”, id=”cc_default” and,

if defined category=CSS_PSETDB_CATEGORY, name=CSS_PSETDB_NAME, id=”cc_default” and

only re-inserts if a change is sensor size is detected.

See Section 7.1.3.4 for details on defining your own default camera configuration.

Once the CSS enters the running state, the default camera configuration (cc_default) simply generates a

single FPA-set with one(1) FPA. The rate is set to 1Hz and the size of the FPA will match that of the

sensor for the currently selected camera.

7.1.2. Creating your own parameter-set

At some point you will want to define your own CSS Parameter-set Category, Name, and a set of Camera

Configuration and Execution Block parameter-sets for use in your system. You are encouraged to define

your own default camera configuration and execution block parameter-sets and insert them into the

database for automatic recall when a DAT is started. To assist you in this, two parameter-set templates are

provided:

$ATST/admin/css/param/templates/cc_camConfig.pset.template

$ATST/admin/css/param/templates/eb_execBlock.pset.template

Each file contains notes and instructions for the respective attribute sets.


MAN-0008, Rev F 101

Follow the guidelines set forth in SPEC-0022-1, Section 10.7 regarding Parameter-set Database

Category and Name.

Copy the template file to “aNameOfYourChoosing.pset”, open with your favorite editor, and set the

attribute values as required.

1) By convention, a CSS parameter-set file uses the extension “.pset”.

2) Although not required, it is recommended that “aNameOfYourChoosing” assume the same value

that you assign to the camera configuration or execution block ID defined for the parameter-set.

This will assist you in quickly identifying any given parameter-set file based on the

corresponding ID.

7.1.3. Parameter-set Database Category, Name, and ID

Parameter-sets are inserted into the database with the CSF utility $ATST/bin/AddParamSet. To view

the options available with this utility do the following:

$ $ATST/bin/AddParamSet --help

When a parameter-set is inserted into the parameter-set database you must supply a Category, Name, ID,

and an optional Description. There are two methods that this can be accomplished.

7.1.3.1. In-file parameters

When you open your copy of the .template files you will notice the following:

# category = <user defined>

# name = <user defined>

# id = <must match value defined in .camConfig:ID below>

# description = <something to describe id>

These lines are parsed by the $ATST/bin/AddParamSet utility and are used to define the category, name,

id, and description respectively that will be used when the parameter-set is inserted into the database. If

you choose to use this mechanism to define the category, name, ID, and description then replace the text

following the equal sign with your desired values.

If you choose not to use this mechanism then simply delete these lines from your parameter-set file.

NOTE: The CSS retrieves parameter-sets from the database based the current category, name and either a

supplied ID or IDs it encounters while traversing a DAT. Therefore, the ID used to insert any given

parameter-set into the database must match the value defined in either the .camConfig:ID or

.execBlock:ID attribute contained in the parameter-set. If these values do not match then automatic

parameter-set retrieval from the database will fail.

7.1.3.2. Command-line Options

If you choose not to use the in-file parameters then you must define the category, name, ID, and optional

description with the AddParamSet command line options. These options are:

--category=your_category

--name=your_name

--id=cc_xxx or eb_xxx

--descriptio=your_description

7.1.3.3. Inserting into the Parameter-set Database

If you have defined the category, name, ID, and description in the .pset file then simply execute the

following:


MAN-0008, Rev F 102

$ $ATST/bin/AddParamSet --file=aNameOfYourChoosing.pset

If you have opted to not define the category, name, ID, and description in the .pset file then execute the

following:

$ $ATST/bin/AddParamSet --category=your_category --name=your_name

--id=cc_xxx -or- --id-eb_xxx --description=your_description

--file=aNameOfYourChoosing.pset

Again, the value supplied for --id MUST match the value defined for either the .camConfig:ID or

.execBlock:ID attribute (depending on the parameter-set being inserted).

7.1.3.4. Defining Your Own Default Camera Configuration

You can configure your VC to use a camera configuration of your choosing as the default. To change the

default camera configuration ID that your VC will start with, edit $ATST/admin/css/cssSite.config, set the

value of CSS_DEFAULT_CCID to the ID of your choosing and re-execute pkgDevel (see Section 3.1 for

complete details). You must assure that a camera configuration parameter-set with the specified camera

configuration ID has been added to the parameter-set database.

WARNING: The camera configuration ID “cc_default” is reserved for CSS use only! If you choose

to define your own default camera configuration, do not use the id “cc_default”! Configuration of

the CSS always includes installation of “cc_default” into the category and name of “css” and

”default” respectively. If defined, “cc_default” will also be added to CSS_PSETDB_CATEGORY

and CSS_PSETDB_NAME.

If you decide to change the startup category and name you must also, using the same Category and Name,

add a camera configuration to the Parameter-set Database. Using the steps outlined above, create a

camera configuration parameter-set and insert it into the database using the Category and Name you

defined during CSS installation in Section 3.1.

See SPEC-0098 for complete details on camera configurations and other functional aspects of the

CSS.

7.1.3.5. Verifying Database Contents

Following any parameter-set insertion into the database, it is recommended that you verify that the

parameter-set is properly registered. To do this use the DKIST utility $ATST/bin/ShowParamSet using the

following command-line options:

-–category=your_category

--name=your_name

--id=cc_xxx –or- eb_xxx

For example, executing ShowParamSet using the default category, name, and ID of the CSS should result

in something similar to the following:

$ $ATST/bin/ShowParamSet --category=css --name=default --id=cc_default

category: css

name: default

id: cc_default

version: 1218 NOTE: This number will vary

description: CSS default for 2560x2160 sensor.

---------------------------------

ParamSetServer.camConfig:ID,cc_default

ParamSetServer.camConfig:accum:numCycles,1

ParamSetServer.camConfig:accum:numberOf,1

ParamSetServer.camConfig:accum:posAtRefT0,1

ParamSetServer.camConfig:accum:sequence,1

ParamSetServer.camConfig:bufferEnable,false

ParamSetServer.camConfig:description, CSS default for 2560x2160 sensor.

ParamSetServer.camConfig:exposure:rate,1.0

ParamSetServer.camConfig:exposure:rateMultiplier,1

ParamSetServer.camConfig:exposure:ratePhase,0.0


MAN-0008, Rev F 103

ParamSetServer.camConfig:exposure:time,20.0

ParamSetServer.camConfig:normalization:method,none

ParamSetServer.camConfig:normalization:value,0.0

ParamSetServer.camConfig:winBin:hw:binSize,1\,1

ParamSetServer.camConfig:winBin:hw:win:ROI_1,0\,0\,2560\,2160

ParamSetServer.camConfig:winBin:hw:win:numberOfROIs,1

ParamSetServer.camConfig:winBin:sw:binSize,1\,1

ParamSetServer.camConfig:winBin:sw:win:ROI_1,0\,0\,2560\,2160

ParamSetServer.camConfig:winBin:sw:win:numberOfROIs,1

ParamSetServer.camConfig:winBin:sw:win:roiType,vertical

Of course, the values of various camera configuration attributes would reflect your modifications.

Also of note, the camera configuration attributes are preceded with “ParamSetServer”. This is because the

camera configuration was inserted into the database without a FQPrefix. The CSS uses the defined

Category, Name, and ID to retrieve a parameter-set from the database and will automatically replace

“ParamSetServer” with the FQPrefix of your top level VC Management Controller (a.b.c.vccNN)

Simulation Data Files 7.2.

The CSS uses a set of data files as the source of data that, under normal operations, emulates the raw

frames delivered by camera hardware to the CSS. The requirements for a simulation data file set are

summarized as follows: A simulation data file set must consist of N files (N ≥ 1) where each file contains:

The same number of pixels in both the X and Y dimensions as the sensor contained in the camera

being simulated.

The same bit-depth and bytes-per-pixel as the sensor contained in the camera being simulated.

This data must be in a form that emulates what the physical camera would deliver where it

commanded to expose and no on-board (camera hardware) data processing were applied.

As stated in Section 4.7.5 the CSS utilizes a set of .csh:interface attributes to define the behavior of the

system with respect to camera interactions.

When .csh:interface:commType=File_IO then data presented to the CSS for processing and, ultimately,

publication on a BDT camera line of the DHS, are obtained from disk files. The initial sets of data files

provided by DKIST are provided in the sizes which correspond to sensors currently (or soon to be)

supported by the CSS and pixel bit-depths supported by these sensors. These sizes are: 2048x2048,

2072x2072, and 2560x2160 with pixel bit depths of 10, 12, 14, and 16 bits-per-pixel. Sizes are given in

X/Y pixels. The images contained in these files contain a sunspot surrounded by granulation. You are free

to uses these files or, if you prefer, define your own set(s) of data files for use with the VC Simulator. The

following sections describe the requirements for creating a set of simulation data files.

7.2.1. Simulation Data Path

The path for your simulation data can be any valid path that is currently mounted on your system. For the

remainder of this section, this will be referred to as: /your/sim/data/path. If you followed the default

installation procedures for the CSS simulation data files (see Section 3.6) then you should have a set of

files that were extracted and installed in /your/sim/data/path/cssSimData/12-bit.

If you decide to create and use your own set of simulation data you will probably want to configure your

VC to use the new path as the default. This is accomplished via the cssSite.config file where:

CSS_SIM_DATA_PATH=/your/sim/data/path

Once you have set this value, re-execute pkgDevel. Refer to Section 3.1 for details.


MAN-0008, Rev F 104

7.2.2. Base Filename

The base filename is a name of your choosing and is used to differentiate different types of data. By

default, the CSS ships with a set of data files whose base name are “cssSim_XxY” where XxY reflect the

X and Y dimensions of the simulation data.

If you decide to create and use your own base filename you will probably want to configure your VC to

use the new base filename as the default. This is accomplished via the cssSite.config file where:

CSS_SIM_DATA_BASE_FILENAME=baseFilename


7.2.3. # of Files Per Set

Each time the camera is triggered (exposed) the CSS supplies the contents of a simulation data file to the

camera controller where it is processed according to the current camera configuration. The CSS will

circularly iterate through the data files in /your/sim/data/path directory but it needs to know how many

files are contained in a set.

By default, the CSS ships with 100 data files per set. If you decide to create and use your own files sets

you may want to change this value and configure your VC to use the new number. This is accomplished

via the cssSite.config file where:

CSS_SIM_DATA_FILES_PER_SET=N where: 1 ≤ N ≤ 100


7.2.4. Final Filename Format

The base filename is combined with a counter and the “.raw” extension to create the final filename. The

filename format is as follows:

<baseFilename>.nnn.raw

Where:

<baseFileName> = Value set in Section 7.2.2

nnn = A zero-padded counter where ‘000’ < nnn < # Files per Set as determined in Section 7.2.3

7.2.5. File Sizes

The file size for each simulation data file is determined by the number of pixels and the bytes-per-pixel as

normally delivered by camera hardware. Under normal circumstances, pixel size should be 2-bytes/pixel.

7.2.6. Example

Assume that you want to create a set of simulation data files for a sensor size of 2072x2072 and

2560x2160.

a) You decide that these files will contain “flats”.

b) You want 50 files per set.

c) Each set of “flats” will be contained in its own sub-directory based on the sensor size.

d) Each pixel of data contains 14-bits of significance. Therefore, each pixel of data in the file

occupies 16-bits (2 bytes).

e) You decide to reflect both the type of data and sensor size in the file name. Therefore, you decide

that the base filenames will be “flat_2072x2072” and “flat_2560x2160”.


MAN-0008, Rev F 105

Based on this information you could create a set of data files as follows:

/your/sim/data/path/2072x2072/flats/flat_2072x2072.000.raw -thru- flat_2072x2072.049.raw

Each file in the “flat_2072x2072” set will have a size of 8,586,368 bytes.

/your/sim/data/path/2560x2160/flats/flat_2560x2160.000.raw -thru- flat_2560x2160.049.raw

Each file in the “flat_2560x2160” set will have a size of 11,059,200 bytes.

World Coordinate Information 7.3.

TN-0213, World Coordinate Information and the DKIST Bulk Data Transport define the facilities

available to the instrument and CSS for creating World Coordinate Information (WCI) from the

instruments wPos and TCS’s cPos and cStatus events. The CSF provides the WciWatch utility for

monitoring these events, collecting and calculating required values, and providing those values as either

an attribute table or a CSV encoded string from which an attribute table can be generated.

See TN-0213 for complete details on World Coordinate Information (WCI). The remainder of this section

details the parameters and attributes available to the user for configuring the CSS to gather and publish

WCI meta-data.

7.3.1. Configuring via cssSite.config

As outlined in Table 4, the CSS provides two parameters that may be used to provide an initial

configuration to the CSS for monitoring a wPos event and gather WCI meta-data for publication. These

parameters are CSS_WCI_WPOS_SOURCE and CSS_WCI_WPOS_UPD_INTERVAL and have default

values of “source.for.wPos.event.not.defined” and 1000 respectively. The default source name was

selected for two reasons: 1) If left unchanged, then meta-data published with the FPA will clearly indicate

that no source was selected for the wPos event; 2) It contains a value that is not likely to match a wPos

event named by the instrument.

If you defined a different source or update interval via cssSite.config then the CSS will use those values

and configure WciWatch to monitor the named source at the specified interval for the wPos event.

It is important that you not supply “.wPos” as part of the source name. The CSF WciWatch facility, used

by the CSS to gather WCI meta-data, will automatically append “.wPos” to the supplied name when it is

created.

7.3.2. Configuring programmatically

The underlying attributes that are initially configured by the aforementioned cssSite.config paramters may

be accessed programmatically. These attributes are: .global:wci:wPosSource and

.global:wci:wPosUpdInterval and have analogous meaning to their cssSite.config counterparts.

Use CSF get() to retrieve the current value of these attributes.

Use CSF submit() to modify one or both values. When these attributes are submitted, the CSS will drop

its current instance of WciWatch and create a new one with the current values. You are free to configure

one or both attributes at a time.

7.3.3. WCI Acquisition and publication

As defined in TN-0213, the WCI meta-data is encoded as a CSV string. The CSS will attempt to obtain a

new meta-data string during raw-frame processing of the first raw frame of each FPA-set. The CSS will

publish the same WCI meta-data string for each FPA of the FPA set.

The CSS provides three meta-data attributes for tracking the source and rate for the wPos event and

current value of WCI meta-data.


MAN-0008, Rev F 106

css.pub:global:wci:wPosSource - The value as contained in .global:wci:wPosSource which defines

the source name of the wPos event that WciWatch will monitor for inclusion in the WCI CSV

encoded string when requested by the CSS.

css.pub:global:wci:wPosUpdInterval - The value as contained in .global:wci:wPosUpdInterval which

defines the interval (in ms) that WciWatch will use to monitor the wPos event.

css.pub:metaData:wci – The CSV encoded string containing the WCI meta-data. The value of this

attribute may contain the empty string (i.e. css.pub:metaData:wci=””) if there is no TCS cPos and

cStatus event and the wPos source cannot be monitored. Otherwise, the contents of this string will be

a CSV encoded attribute table containing the WCI from the available sources. The CSF’s WciWatch

class contains the method getImageInfo() which will take a string as an argument and return an

attribute table. Use this method to convert the WCI CSV string to an attribute table for use in your

data processing plug-in.


MAN-0008, Rev F 107

Appendix A DKIST Assigned Camera Names

Each camera supported by the CSS is identified by a unique name and camera ID. The name and ID of

each camera are assigned by DKIST and are not user configurable. The camera name is used by the CSS

to properly configure the virtual camera for a specific camera. The camera ID is used to determine

whether the physical camera attached to the system matches corresponds to the camera name as

configured via the cssSite.config parameter CSS_CAMERA_NAME (See Section 3.3.2).

The camera name also corresponds to a property table for the camera that will be loaded during system

startup.

The following table contains the list of cameras supported by the CSS. The table includes the DKIST

assigned name and ID, and other pertinent reference information.

Camera Name ID Assigned To Model Sensor

Size Protocol IP

“Dkist_Generic.01” 1 N/A Simulator 2560x2160 N/A N/A

A generic development camera for engineering/testing.

“ImperxBobcat.01” 2 WFC B2021M 2072x2072 GigE 10.0.74.101

“ImperxBobcat.02” 3 E2E/TAS B2021M 2072x2072 GigE 10.0.74.102

“ImperxBobcat.03” 4 CSS B2021M 2072x2072 GigE 10.0.74.103

“ImperxBobcat.04” 5 VBI B2021M 2072x2072 GigE 10.0.74.104

“ImperxBobcat.05” 6 VBI B2021M 2072x2072 GigE 10.0.74.105

“ImperxBobcat.06” 7 TBD B2021M 2072x2072 GigE 10.0.74.106



“ImperxBobcat.09” 10 Cryo-NIRSP B2021M 2072x2072 GigE 10.0.74.109

Table 22 List of Camera Names


MAN-0008, Rev F 109

Appendix B Imperx Bobcat Hardware Considerations

The Imperx Bobcat communicates with the host computer using the GigE Vision interface standard. To

connect your camera to the host system you will need:

1. A free Gigabit (1000Base-T) Ethernet connection on your host system.

2. A network cable of appropriate length (preferably Cat 6 but Cat 5e is sufficient).

3. A place to mount your camera.

B.1 Network Interface Adaptor

Pleora, the manufacturer of the ebus-PureGEV Linux SDK used within the Imperx Bobcat SDK,

recommends an Intel PRO-1000 (Gigabit) network card or an 8254x-based PCI Ethernet Adaptor or

Chipset Integrated NIC. This does not appear to be a hard requirement. Examination of the device drivers

on the CSS engineering system reveals that it is using the NVIDIA MPC55 chipset in conjunction with

the “forcedeth” kernel module which is a Reverse Engineered nForce Ethernet driver.

The only hard requirement is that the Ethernet adaptor you use must support jumbo frames with an MTU

of 4096 or greater.

B.2 Network Connection

Each Imperx Bobcat camera used within DKIST has been assigned a name and Ethernet address by CSS

engineering. The Ethernet address assigned utilizes the 10.0.74 subnet (See Table 22 List of Camera

Names in Appendix A). In order for your system to communicate with your camera, you must configure

the Ethernet adaptor you will be using to be on the 10.0.74 subnet. Use either the “ifconfig” command

line utility or the “Network Connections” GUI utility (CentOS) to configure the IPv4 settings of your

Ethernet adaptor as follows:

Method: Manual

Address: 10.0.74.xxx (recommended value: 20 <= xxx < 100)

Netmask: 255.255.255.0

Gateway: 10.0.74.1

To verify that your network settings have taken effect, execute ifconfig from the command line and

examine the output for the Ethernet adaptor you configured (i.e. eth1 or eth2). If using multiple cameras,

repeat this process for each Ethernet adaptor.

NOTE: The “Bobcat GEV Linux Installer Manual” included with the CSS tools (available upon

completion of “./admin/createDevel --make-all” in Section 3.4) contains instructions on

configuring your network adaptor.

B.3 Connecting the camera to your computer

1. Mount the camera in your preferred location.

2. Plug one end of your network cable into the Ethernet port you just configured on your computer

and the other end of your network cable into the back of the camera.

3. Plug the circular connector from the power supply to the camera. The connector is keyed and will

“snap” in place when fully connected. Gently pull on the cable to assure it is securely connected.

4. Plug the power supply in to your AC source. The center LED on the back of the camera will

flicker red and then turn solid green. The left side power/activity indicator LED of the Ethernet

connection will flicker green for a few seconds and then turn solid green. The right side

power/activity indicator LED of the Ethernet connection will light solid amber.


MAN-0008, Rev F 110

B.4 Operational Notes

This section contains any operational notes related to the Imperx Bobcat B2021M camera. Throughout

this section this camera will simply be referred to as the Bobcat.

B.4.1 Windowing and Binning

This section provides details of windowing and binning as it applies to the Bobcat camera. An overview

is presented which provides background information on the Bobcat implementation of windowing and

binning including restrictions and limitations of the camera. This is then followed by a discussion on how

the Bobcat implementation influences hardware applied binning and ROIs as contained in a camera

configuration including the mathematical formulas used to derive windowing origin and size, limits, and

specifies additional rules that apply. Finally, a summary is provided containing all rules. A set of tables is

also provided which cross-references binning size to ROI origin and size limits.

B.4.1.1 Bobcat implementation and CSS adaptation

As defined in SPEC_0098, a camera configuration provides for application of windowing and binning in

hardware and software. In both cases, the CSS defines that windowing is applied before binning.

Therefore, the origin and size of a Region-of-Interest (ROI) are defined in un-binned space. When applied

in hardware this is the un-binned space of the sensor and when applied in software it is the un-binned

space of the raw frame delivered by camera hardware to the CSS data acquisition and processing pipeline.

The Bobcat camera hardware applies windowing, also referred to as Area-of-Interest(AOI) and binning as

follows:

Vertical binning is done in the time domain where data from lines (rows) to be binned are added

in the CCD. Along the vertical axis, binning is performed first and the vertical AOI is second.

Horizontal binning is done in the digital domain where the data from the columns to be binned

are added digitally. Along the horizontal axis, binning is performed first and horizontal AOI is

second.

The Bobcat supports one Master AOI (MAOI) up to 6 slave AOIs as follows:

All pixels that lie outside of the MAOI are discarded.

Slave AOIs must be encompassed by the MAOI and are defined to be either “included” or

“excluded”.

Slave AOIs that are defined to be “included” will have their pixel values retained.

Slave AOIs that are defined to be “excluded” will have their pixel values set to 0 (black).

Pixels that lie within the MAOI and outside the slave AOIs have their values set to 0 (black).

The maximum camera speed is strictly determined by the number of lines (rows, height,

size-Y) of the MAOI. A reduction in the number of lines of the MAOI will allow for an increase

in speed.

To increase the maximum frame rate available to the user the Bobcat camera is configured for dual-tap

readout. When configured in this mode the width (X-dimension) of the MAOI and any slave AOIs have

the following restrictions:

The minimum width is 8.

The width must be evenly divisible by 8.

Because the Bobcat incorporates an “include”/”exclude” scheme for the slave AOIs within the bounds of

the MAOI, and because there is no requirement or use for defining “excluded” AOIs within the context of

the CSS, the only possible use the CSS has is to set slave AOIs as “included”. When multiple slave AOIs,

which correlate with the hardware applied ROIs in a camera configuration, are used then this results in a

pseudo-checkerboard pattern: Pixels which lie outside “included” AOIs being 0 (black), and pixels which


MAN-0008, Rev F 111

line inside “included” AOIs retaining their values. The CSS requires that the raw frame delivered from

camera hardware to the CSS data processing pipeline contain a rectangular area of pixels with no “gaps”.

This is not possible with the data delivered by the Bobcat when multiple slave AOIs are defined due to

the pseudo-checkerboard pattern. In fact, there is no benefit to programming the Bobcat for any slave

AOIs. Therefore, when a camera configuration defines multiple ROIs to be applied in camera hardware

the CSS will not use the slave AOI feature of the camera.

What the CSS will do is, based on the hardware applied binning and ROIs defined in a camera

configuration, determine an MAOI that encompasses the desired hardware applied ROIs and then apply

software processing to extract the desired hardware applied ROIs from the MAOI. Speed increase can still

be realized when hardware applied ROIs are defined when the overall vertical dimension of the rectangle

which encompasses these ROIs contains fewer rows than the full sensor.

B.4.1.2 Deriving limits

The MAOI is defined by an X/Y origin, a width (sizeX), and a height (sizeY). The MAOI origin can be

adjusted in increments of 1 in both the X/Y dimensions. As mentioned previously, in dual tap mode the

Bobcat imposes the restrictions that the MAOI have a minimum width of 8 and that the overall width

be evenly divisible by 8. Recall that the MAOI is defined in binned space but hardware applied ROIs in a

camera configuration are defined in un-binned space. This requires that ROIs defined in a camera

configuration must be mapped to binned spaced within the MAOI. As such the following apply when

defining the hardware applied ROIs in a camera configuration.

Assume that hardware applied ROIs are defined as:

(𝑟𝑜𝑖𝑂𝑟𝑖𝑔𝑛𝑥, 𝑟𝑜𝑖𝑂𝑟𝑖𝑔𝑖𝑛𝑦, 𝑟𝑜𝑖𝑆𝑖𝑧𝑒𝑥, 𝑟𝑜𝑖𝑆𝑖𝑧𝑒𝑦)

Also assume that hardware applied binning is defined as:

(𝑏𝑥 , 𝑏𝑦)

The ROI width must be evenly divisible by the applied binning size × 8:

𝑟𝑜𝑖𝑆𝑖𝑧𝑒𝑥

(𝑏𝑥 × 8)= {𝑟𝑥; 𝑟𝑥 𝑖𝑠 𝑎𝑛 𝑖𝑛𝑡𝑒𝑔𝑒𝑟; 𝑎𝑛𝑑 𝑟𝑥 ≥ 1}

The maximum ROI width is:

𝑟𝑜𝑖𝑆𝑖𝑧𝑒𝑀𝑎𝑥𝑥 = ⌊𝑆𝑒𝑛𝑠𝑜𝑟𝑥

(𝑏𝑥 × 8)⌋ × (𝑏𝑥 × 8)

The ROI height must be evenly divisible by the applied binning size:

𝑟𝑜𝑖𝑆𝑖𝑧𝑒𝑦

𝑏𝑦= {𝑟𝑦; 𝑟𝑦 𝑖𝑠 𝑎𝑛 𝑖𝑛𝑡𝑒𝑔𝑒𝑟; 𝑎𝑛𝑑 𝑟𝑦 ≥ 1}

The maximum ROI height is:

𝑟𝑜𝑖𝑆𝑖𝑧𝑒𝑀𝑎𝑥𝑦 = ⌊𝑆𝑒𝑛𝑠𝑜𝑟𝑦

𝑏𝑦⌋ × 𝑏𝑦

The ROI origin in both the X/Y dimensions must be evenly divisible by the binning size in that

dimension. This is expressed as:

𝑟𝑜𝑖𝑂𝑟𝑖𝑔𝑖𝑛𝑥

𝑏𝑥 = {𝑜𝑥; 𝑜𝑥 𝑖𝑠 𝑎𝑛 𝑖𝑛𝑡𝑒𝑔𝑒𝑟; 𝑎𝑛𝑑 𝑜𝑥 ≥ 1}

𝑟𝑜𝑖𝑂𝑟𝑖𝑔𝑖𝑛𝑦

𝑏𝑦 = {𝑜𝑦; 𝑜𝑦 𝑖𝑠 𝑎𝑛 𝑖𝑛𝑡𝑒𝑔𝑒𝑟; 𝑎𝑛𝑑 𝑜𝑦 ≥ 1}


MAN-0008, Rev F 112

The minimum ROI origin for both the X and Y axis is:

𝑟𝑜𝑖𝑂𝑟𝑖𝑔𝑖𝑛𝑀𝑖𝑛𝑥 = 0

𝑟𝑜𝑖𝑂𝑟𝑖𝑔𝑖𝑛𝑀𝑖𝑛𝑦 = 0

The maximum ROI origin along the X-axis is:

𝑟𝑜𝑖𝑂𝑟𝑖𝑔𝑖𝑛𝑀𝑎𝑥𝑥 = 𝑆𝑒𝑛𝑠𝑜𝑟𝑥 − (𝑏𝑥 × 8)

The maximum ROI origin along the Y-axis is:

𝑟𝑜𝑖𝑂𝑟𝑖𝑔𝑖𝑛𝑀𝑎𝑥𝑦 = 𝑟𝑜𝑖𝑆𝑖𝑧𝑒𝑀𝑎𝑥𝑦 − 𝑏𝑦

B.4.1.3 Additional rules and restrictions

The following additional restrictions are also imposed on hardware applied ROIs on the Bobcat:

1) The upper left corner of the sensor has origin coordinates of (0,0).

SPEC-0098 discusses both hardware and software applied ROIs and defines that sensor pixel

with coordinates (0, 0) is the lower left corner but also defers to the manufacturer

implementation. In this case, the Bobcat camera defines sensor pixel with coordinates (0, 0) as the

upper left corner of the sensor.

NOTE: Software applied ROIs are still defined with pixel coordinate (0, 0) being the lower left

corner of the raw frame.

2) ROIs are of the Horizontal type.

Horizontal ROIs are ROIs which are disjoint and vertically displaced from each other. The rules

that apply to horizontal ROIs are as follows:

a. All defined ROIs are vertically disjoint meaning that no two ROIs may share a common

row (Y) address.

b. All defined ROIs must have the same X-dimension (sizex).

c. The number of rows (sizey) of each ROI may be different.

Horizontal type ROIs are being enforced for the following reasons:

The Bobcat will realize a speed increase when the number of lines in the MAOI is

reduced. Through definition, horizontal type ROIs lend themselves better to naturally

reducing the number of lines.

If vertical type ROIs were allowed, the user may desire a speed increase by reducing the

number of columns through ROI definitions but a reduction in columns will not have an

effect on readout speed of the camera.

See SPEC-0098 for a detailed discussion on Horizontal type ROIs.

3) All ROIs must share a common X-origin value.

This rule is being imposed to eliminate the edge case where 𝑏𝑥 > 1, 𝑟𝑜𝑖𝑆𝑖𝑧𝑒𝑥 ≡ 𝑟𝑜𝑖𝑆𝑖𝑧𝑒𝑀𝑎𝑥𝑥,

but the ROIs have differing origins (i.e. 𝑟𝑜𝑖𝑂𝑟𝑖𝑔𝑖𝑛1𝑥 ≠ 𝑟𝑜𝑖𝑂𝑟𝑖𝑔𝑖𝑛2𝑥. In this case, it is not

possible to define an MAOI which encompasses ROI 1 and ROI2 yet still adheres to having a

width that is evenly divisible by (𝑏𝑥 × 8).

B.4.1.4 Binning and Windowing Summary

The following is a summary of the rules imposed on hardware applied ROIs for the Imperx Bobcat:

1) The sensor has dimensions of 2072x2072. The upper left corner of the sensor is designated (0, 0).

2) Hardware applied ROIs are of the horizontal type AND must all share a common x-origin.


MAN-0008, Rev F 113

3) The width (size-X) of an ROI has a minimum value of (𝑏𝑥 × 8) and the width must be an even

multiple of (𝑏𝑥 × 8). Table 23 summarizes the origin and size limits for an ROI along the x-axis.

Bin X ROI Origin X ROI Size X

Minimum Maximum Increment Minimum Maximum Increment

1 0 2064 1 8 2072 8

2 0 2056 2 16 2064 16

3 0 2046 3 24 2064 24

4 0 2040 4 32 2048 32

8 0 2008 8 64 2048 64

Table 23: Imperx Bobcat B2021M ROI Origin/Size X Limits

4) The height (size-Y) of an ROI has a minimum value of 𝑏𝑦 and the height must be an even

multiple of 𝑏𝑦. Table 24 summarizes the origin and size limits for an ROI along the y-axis.

Bin Y ROI Origin Y ROI Size Y

Minimum Maximum Increment Minimum Maximum Increment

1 0 2071 1 1 2072 1

2 0 2070 2 2 2072 2

3 0 2067 3 3 2070 3

4 0 2068 4 4 2072 4

8 0 2064 8 8 2072 8

Table 24: Imperx Bobcat B2021M ROI Origin/Size Y Limits

5) The (origin + size) in X and Y cannot exceed the sensor size in X and Y:

𝑟𝑜𝑖𝑂𝑟𝑖𝑔𝑖𝑛𝑥 + 𝑟𝑜𝑖𝑆𝑖𝑧𝑒𝑥 ≤ 𝑆𝑒𝑛𝑠𝑜𝑟𝑥

𝑟𝑜𝑖𝑂𝑟𝑖𝑔𝑖𝑛𝑦 + 𝑟𝑜𝑖𝑆𝑖𝑧𝑒𝑦 ≤ 𝑆𝑒𝑛𝑠𝑜𝑟𝑦

The CSS will enforce these rules and limits during Camera Configuration validation!

B.4.1.5 Hardware applied ROI Application Notes

The following are a couple of notes regarding hardware applied ROIs and the Bobcat camera:

1) The CSS will extract hardware applied ROIs as defined in a camera configuration from the

MAOI programmed on the camera that encompasses these ROIs. This extraction is performed

with software using the same process that software applied ROIs are extracted. In order to cut

down on the software processing required you may choose to simply define a single hardware

applied ROI that encompasses the desired pixels and then define software applied ROIs.

For example, assume you desire 2x2 hardware binning and two hardware applied ROIs each of

size 2064x400 and separated by 600 pixels with the first ROI beginning at origin (0,200).

A completely valid, and natural method to define this would be:

.camConfig:winBin:hw:binSize = 2,2

.camConfig:winBin:hw:win:numberOfROIs = 2

.camConfig:winBin:hw:win:ROI_1 = 0,200,2064,400


.camConfig:winBin:sw:binSize = 1,1

.camConfig:winBin:sw:win:roiType = horizontal

.camConfig:winBin:sw:win:numberOfROIs = 1

.camConfig:winBin:sw:win:ROI_1 = 0,0,1032,400

As an alternative you could define the following:

.camConfig:winBin:hw:binSize = 2,2

.camConfig:winBin:hw:win:numberOfROIs = 1


MAN-0008, Rev F 114


.camConfig:winBin:sw:binSize = 1,1

.camConfig:winBin:sw:win:roiType = horizontal

.camConfig:winBin:sw:win:numberOfROIs = 2



For this camera, the alternative method will reduce the amount of software processing required.

Otherwise, both methods are equivalent.

2) On a spectrograph type instrument, one possible use for ROIs is to encompass spectral lines of

interest with an ROI retaining all pixels within the spatial dimension of the slit but perhaps

eliminating unnecessary pixels along the spectral dimension of your slit.

If you are observing spectral lines and want to define multiple hardware applied ROIs that

encompass the spectral lines in order to reduce the number of pixels read from the camera, throw

away unnecessary pixels along the spectral dimension, and increase the available exposure rate,

assure that the X-axis of the camera sensor is parallel to the slit of your instrument. Recall that

only a reduction in the total number of lines (rows) being read from the sensor can result in an

increase in speed. By rotating the camera such that the lines(rows) of the sensor are parallel to the

slit, decreasing the total number of lines will be coincident with discarding unwanted spectral

dimension data while retaining all spatial information along the slit. This is crudely illustrated

below. Rectangles in red are the ROIs that need to be defined to realize a reduction in lines and an

increase in speed. Rotation of the sensor allows these ROIs to align with the spectra.

Figure 40: Aligning the Imperx Bobcat with Spectral Lines

MAN-0008 CSS Installation and User's Guide - atst.nso.edu

Documents

Transcript of MAN-0008 CSS Installation and User's Guide - atst.nso.edu