From 6e153c9574e031e1afe88324f23f269e38234ee2 Mon Sep 17 00:00:00 2001 From: watts Date: Mon, 5 Oct 2026 14:47:21 +0200 Subject: [PATCH] Update PixelatorControllerSettings --- PixelatorControllerSettings.md | 600 ++++++++++++++++----------------- 1 file changed, 300 insertions(+), 300 deletions(-) diff --git a/PixelatorControllerSettings.md b/PixelatorControllerSettings.md index f4eba63..4606a1f 100644 --- a/PixelatorControllerSettings.md +++ b/PixelatorControllerSettings.md @@ -1,301 +1,301 @@ -The first argument passed to PixelatorController start script is the filename -of the settings file. Some of the settings in that file are filenames -of other settings files. This article describes these settings files with -one section per file. - -The file format is [JSON](http://www.json.org/) - -Some options affect data recorded in the HDF5 files produced by Pixelator scans, which are based on the [NXstxm](https://doi.org/10.1063/1.4937536) application definition of the [NeXus](https://www.nexusformat.org/) data format. - -# Settings - -## Scan Files: Directory -Every scan creates an hdf5 file. Thus, all scan data is recorded and the following parameters indicate where the scan file is written. The directory that the scan files are stored in is: -_base directory/YYYY-mm-dd/_ - -**NeXusBaseDirectory**::
- base directory to save scan files - -**NeXusLocalBaseDirectory**::
- base directory used when **Save local** is active - -**defaultSaveLocal**::
- Save local setting on startup.
- "yes": use **NeXusLocalBaseDirectory** directory
- anything else: use **NeXusBaseDirectory** directory - -Files are initially written to a "discard" subdirectory. Once the scan has completed, the file may be moved out of this subdirectory if the scan type is set to be "archived". - - **NeXusDiscardSubDirectory**::
- Sub directory for files not archived. A scan in progress is recorded into a file in this subdirectory and then may be moved to the parent directory, depending on the ScanType_Archive status (see below). - -The **ScanType_Archive_Default** options define a default archive flag for each scan type. -They are used when **ScanType_Archive** is missing. - - **Sample_Archive_Default**::
- **Focus_Archive_Default**::
- **OSA_Archive_Default**::
- **OSA Focus_Archive_Default**::
- **Detector_Archive_Default**::
- **Motor_Archive_Default**::
- **Motor2D_Archive_Default**::
- "yes": files are archived (moved out of the "discard" subdirectory)
- "no": files are left in the "discard" subdirectory
- "locked": as yes, but users cannot toggle the archive flag for this scan type
- **Default**: "locked" - -Users can toggle the archive flag for a scan type (unless locked). -When they do so, **ScanType_Archive** is added or updated. - - Sample_Archive::
- Focus_Archive::
- OSA_Archive::
- OSA Focus_Archive::
- Detector_Archive::
- Motor_Archive::
- Motor2D_Archive::
- "yes": files are archived
- "no": files are put in the discard sub directory
- **Default**: **ScanType_Archive_Default** - -### Scan Files -The name of the file is: -_ScanType_YYYY-mm-dd_ScanNumber_.hdf5 - -For Sample scans, the spatial type -- _Point_ -- _Line_ -- _Image_ -- _Stack_ - -is added after _ScanType_. - -ScanNumber is a three digit number, starting with 001 every day. - -**NeXusScanNumber**::
- ScanNumber counter
- Updated every time a new scan file is created (beginning of the scan). Reset to 0 when starting a new scan after midnight.
- **Default**: 0 - -**NeXusScanDate**::
- `YYYY-MM-DD` string used for creation of file paths.
- Automatically updated to current date.
- **Default**: 0 - - **compression**::
- "LZW": Use LZW compression in hdf5 file
- "NONE": No compression
- **Default**: "NONE" - - **beamline**::
- String value that is written into the scan file at _/entry*/collection/beamline_ in order to identify the instrument. - -### scripts - **changeUserScript**::
- name of the script that is run on startup and whenever the user is changed (not really used yet - placeholder for future features)
- **Optional**: no script is run when this setting is missing - - **defaultUsername**::
- username set on startup (not really used yet - placeholder for future features) - - **endOfScanScript**::
- name of the script that is run on the controller at the end of every scan
- **Optional**: no script is run when this setting is missing - -### ZeroMQ Ports - **publisherPort**::
- TCP port used by _PixelatorController_ to publish messages to the various user interfaces, e.g. _PixelatorGUI_ - - **requestPort**::
- TCP port used to listen for requests - -### missing data check -At the end of a point by point line, some data of asynchronous detectors may be missing. Pixelator will wait and keep trying to read data from the asynchronous detector until either no more data is missing, or it has reached the maximum number of tries (i.e. **missingDataCheckMaxChecks**). The product of **missingDataCheckInterval** and **missingDataCheckMaxChecks** is the maximum time that Pixelator will wait before moving on to the next line of scan points. - - **missingDataCheckInterval**::
- interval (in seconds) at which missing data is read
- **Default**: 0.1 seconds - - **missingDataCheckMaxChecks**::
- maximum number of times missing data is read
- **Default**: 5 - -### User interface - **nexusBookmark**::
- A JSON structure that presents a set of "label" and "target" values that is passed to the user interface to simplify user navigation between different parts of the available file system. For example: - -```json - "NeXusBookmarks" : [ - { - "label" : "today e-mnt", - "target" : "/home/control/e-mnt/Data1/YYYY-MM-DD" - }, - { - "label" : "e-mnt", - "target" : "/home/control/e-mnt/Data1" - }, - { - "label" : "Local", - "target" : "/home/control/LocalData/Data1" - }, - { - "label" : "PLV", - "target" : "/home/control/PLV" - } - ] -``` - - -### settings files names -The following settings define the name of additional settings files. -Each of these settings files is described in a section below. - - **axisConfigFileName**::
- [Axis](#axis) - - **controllerConfigFileName**::
- [Controller](Config_Controller) - - **detectorConfigFileName**::
- [Detector](Config_Detector) - - **epicsConfigFileName**::
- [Epics](#epics) - - **instrumentConfigFileName**::
- [Instrument](Config_Instrument) - - **log4cppPropertiesFileName**::
- [Log4cpp Properties](#log4cpp-properties) - - **microscopeControlConfigFileName**::
- [Microscope Control](#microscope-control) - - **pixelClockConfigFileName**::
- [Pixel Clock](Config_PixelClock) - -~~**polarizationConfigFileName**::~~
- This config file is no longer used. - - **positionerConfigFileName**::
- [Positioner](Config_Positioner) - - **topupConfigFileName**::
- **Optional**: no topup handling when this setting is missing or the file cannot be read.
- [Topup](Config_Topup) - - **zonePlateConfigFileName**::
- [Zone Plate](Config_ZonePlate) - -## Axis -Definition of coordinate axes names to be referenced by positioners with the **axisName** setting. - - **nexus_name**::
- String value defines the label string to be used in NeXus files, since these must conform to a specific naming scheme. - -Example: -```json -{ - "SampleX" : { - "nexus_name" : "sample_x" - }, - "SampleY" : { - "nexus_name" : "sample_y" - }, - "SampleZ" : { - "nexus_name" : "sample_z" - } -} -``` - -## Epics -This file contains global epics settings. - - **search_timeout**::
- Float value defines the timeout (in seconds) used in - * EpicsDetector and EpicsPositioner for - * searching channels (casearch) - * Epics for - * searching channel (casearch) (Topup) - * searching channel (casearch) (getStringValue) - - **Default**: 5.0 - - **get_timeout**::
- Float value defines the timeout (in seconds) used in - * EpicsDetector and EpicsPositioner for - * initializing channels (cainfo, caget) - * setup monitors (ca_add_event, ca_add_array_event) - * set position (ca_put_callback) - * Epics for - * initializing channel (cainfo) (Topup) - * setup monitors (ca_add_event) (Topup) - * initializing channel (caget) (getStringValue) - - **Default**: 1.0 - -Example: -```json -{ - "search_timeout" : 5.0, - "get_timeout" : 1.0 -} -``` - -## Log4cpp Properties -Configuration of logging utility. Example: -```properties -log4cpp.rootCategory=WARN, stdout -log4cpp.appender.stdout=org.apache.log4cpp.ConsoleAppender -log4cpp.appender.stdout.layout=org.apache.log4cpp.PatternLayout -log4cpp.appender.stdout.layout.ConversionPattern=%d [%t] %-5p %c - %m%n -log4cpp.category.ch_semafor_stxm.test=INFO -``` - -Details can be found [here](https://logging.apache.org/log4j/2.x/manual/configuration.html#configuration-with-properties). In order to see more messages, set the standard output (i.e. stdout) to DEBUG with `log4cpp.rootCategory=DEBUG, stdout`. - -## Microscope Control -This file contains a JSON structure that provides _named positions_ and is passed to the user interface. This can be used to configure buttons that move a positioner (or set of positioners) to a predefined value (e.g. "OSA out" could move OSAX to -3000 and OSAY to 4000). The JSON structure contains one field called "InOut", whose value is another structure with the name of each field corresponding to a separate _named position_. Each of these _named position_ fields contains a list (one entry per involved positioner) of structure with 3 fields: - - **positioner**::
- String value defining the positioner to be moved. - - **positionIn**::
- Double value defining the "in" value of the positioner. - - **positionOut**::
- Double value defining the "out" value of the positioner. - -Example: -```json -{ - "InOut" : { - "OSA" : [ - { - "positionIn" : 0.0, - "positionOut" : -3000.0, - "positioner" : "OSAX" - }, - { - "positionIn" : 0.0, - "positionOut" : 4000.0, - "positioner" : "OSAY" - } - ], - "Sample" : [ - { - "positionIn" : 5000.0, - "positionOut" : 10000.0, - "positioner" : "CoarseZ" - } - ], - "ZonePlate" : [ - { - "positionIn" : -5000, - "positionOut" : -18000.0, - "positioner" : "Zoneplate" - } - ] - } -} +The first argument passed to PixelatorController start script is the filename +of the settings file. Some of the settings in that file are filenames +of other settings files. This article describes these settings files with +one section per file. + +The file format is [JSON](http://www.json.org/) + +Some options affect data recorded in the HDF5 files produced by Pixelator scans, which are based on the [NXstxm](https://doi.org/10.1063/1.4937536) application definition of the [NeXus](https://www.nexusformat.org/) data format. + +# Settings + +## Scan Files: Directory +Every scan creates an hdf5 file. Thus, all scan data is recorded and the following parameters indicate where the scan file is written. The directory that the scan files are stored in is: +_base directory/YYYY-mm-dd/_ + +**NeXusBaseDirectory**::
+ base directory to save scan files + +**NeXusLocalBaseDirectory**::
+ base directory used when **Save local** is active + +**defaultSaveLocal**::
+ Save local setting on startup.
+ "yes": use **NeXusLocalBaseDirectory** directory
+ anything else: use **NeXusBaseDirectory** directory + +Files are initially written to a "discard" subdirectory. Once the scan has completed, the file may be moved out of this subdirectory if the scan type is set to be "archived". + + **NeXusDiscardSubDirectory**::
+ Sub directory for files not archived. A scan in progress is recorded into a file in this subdirectory and then may be moved to the parent directory, depending on the ScanType_Archive status (see below). + +The **ScanType_Archive_Default** options define a default archive flag for each scan type. +They are used when **ScanType_Archive** is missing. + + **Sample_Archive_Default**::
+ **Focus_Archive_Default**::
+ **OSA_Archive_Default**::
+ **OSA Focus_Archive_Default**::
+ **Detector_Archive_Default**::
+ **Motor_Archive_Default**::
+ **Motor2D_Archive_Default**::
+ "yes": files are archived (moved out of the "discard" subdirectory)
+ "no": files are left in the "discard" subdirectory
+ "locked": as yes, but users cannot toggle the archive flag for this scan type
+ **Default**: "locked" + +Users can toggle the archive flag for a scan type (unless locked). +When they do so, **ScanType_Archive** is added or updated. + + Sample_Archive::
+ Focus_Archive::
+ OSA_Archive::
+ OSA Focus_Archive::
+ Detector_Archive::
+ Motor_Archive::
+ Motor2D_Archive::
+ "yes": files are archived
+ "no": files are put in the discard sub directory
+ **Default**: **ScanType_Archive_Default** + +### Scan Files +The name of the file is: +_ScanType_YYYY-mm-dd_ScanNumber_.hdf5 + +For Sample scans, the spatial type +- _Point_ +- _Line_ +- _Image_ +- _Stack_ + +is added after _ScanType_. + +ScanNumber is a three digit number, starting with 001 every day. + +**NeXusScanNumber**::
+ ScanNumber counter
+ Updated every time a new scan file is created (beginning of the scan). Reset to 0 when starting a new scan after midnight.
+ **Default**: 0 + +**NeXusScanDate**::
+ `YYYY-MM-DD` string used for creation of file paths.
+ Automatically updated to current date.
+ **Default**: 0 + + **compression**::
+ "LZW": Use LZW compression in hdf5 file
+ "NONE": No compression
+ **Default**: "NONE" + + **beamline**::
+ String value that is written into the scan file at _/entry*/collection/beamline_ in order to identify the instrument. + +### scripts + **changeUserScript**::
+ name of the script that is run on startup and whenever the user is changed (not really used yet - placeholder for future features)
+ **Optional**: no script is run when this setting is missing + + **defaultUsername**::
+ username set on startup (not really used yet - placeholder for future features) + + **endOfScanScript**::
+ name of the script that is run on the controller at the end of every scan
+ **Optional**: no script is run when this setting is missing + +### ZeroMQ Ports + **publisherPort**::
+ TCP port used by _PixelatorController_ to publish messages to the various user interfaces, e.g. _PixelatorGUI_ + + **requestPort**::
+ TCP port used to listen for requests + +### missing data check +At the end of a point by point line, some data of asynchronous detectors may be missing. Pixelator will wait and keep trying to read data from the asynchronous detector until either no more data is missing, or it has reached the maximum number of tries (i.e. **missingDataCheckMaxChecks**). The product of **missingDataCheckInterval** and **missingDataCheckMaxChecks** is the maximum time that Pixelator will wait before moving on to the next line of scan points. + + **missingDataCheckInterval**::
+ interval (in seconds) at which missing data is read
+ **Default**: 0.1 seconds + + **missingDataCheckMaxChecks**::
+ maximum number of times missing data is read
+ **Default**: 5 + +### User interface + **nexusBookmark**::
+ A JSON structure that presents a set of "label" and "target" values that is passed to the user interface to simplify user navigation between different parts of the available file system. For example: + +```json + "NeXusBookmarks" : [ + { + "label" : "today e-mnt", + "target" : "/home/control/e-mnt/Data1/YYYY-MM-DD" + }, + { + "label" : "e-mnt", + "target" : "/home/control/e-mnt/Data1" + }, + { + "label" : "Local", + "target" : "/home/control/LocalData/Data1" + }, + { + "label" : "PLV", + "target" : "/home/control/PLV" + } + ] +``` + + +### settings files names +The following settings define the name of additional settings files. +Each of these settings files is described in a section below. + + **axisConfigFileName**::
+ [Axis](#axis) + + **controllerConfigFileName**::
+ [Controller](Config_Controller) + + **detectorConfigFileName**::
+ [Detector](Config_Detector) + + **epicsConfigFileName**::
+ [Epics](#epics) + + **instrumentConfigFileName**::
+ [Instrument](Config_Instrument) + + **log4cppPropertiesFileName**::
+ [Log4cpp Properties](#log4cpp-properties) + + **microscopeControlConfigFileName**::
+ [Microscope Control](#microscope-control) + + **pixelClockConfigFileName**::
+ [Pixel Clock](Config_PixelClock) + +~~**polarizationConfigFileName**::~~
+ This config file is no longer used. + + **positionerConfigFileName**::
+ [Positioner](Config_Positioner) + + **topupConfigFileName**::
+ **Optional**: no topup handling when this setting is missing or the file cannot be read.
+ [Topup](Config_Topup) + + **zonePlateConfigFileName**::
+ [Zone Plate](Config_ZonePlate) + +## Axis +Definition of coordinate axes names to be referenced by positioners with the **axisName** setting (those with a combination of coarse and fine stages). + + **nexus_name**::
+ String value defines the label string to be used in NeXus files, since these must conform to a specific naming scheme. This name will be written into the fieldname for coordinate values in NXdata and NXmonitor groups. The NXstxm specification requires these names to be the same as in the following example. + +Example: +```json +{ + "SampleX" : { + "nexus_name" : "sample_x" + }, + "SampleY" : { + "nexus_name" : "sample_y" + }, + "SampleZ" : { + "nexus_name" : "sample_z" + } +} +``` + +## Epics +This file contains global epics settings. + + **search_timeout**::
+ Float value defines the timeout (in seconds) used in + * EpicsDetector and EpicsPositioner for + * searching channels (casearch) + * Epics for + * searching channel (casearch) (Topup) + * searching channel (casearch) (getStringValue) + + **Default**: 5.0 + + **get_timeout**::
+ Float value defines the timeout (in seconds) used in + * EpicsDetector and EpicsPositioner for + * initializing channels (cainfo, caget) + * setup monitors (ca_add_event, ca_add_array_event) + * set position (ca_put_callback) + * Epics for + * initializing channel (cainfo) (Topup) + * setup monitors (ca_add_event) (Topup) + * initializing channel (caget) (getStringValue) + + **Default**: 1.0 + +Example: +```json +{ + "search_timeout" : 5.0, + "get_timeout" : 1.0 +} +``` + +## Log4cpp Properties +Configuration of logging utility. Example: +```properties +log4cpp.rootCategory=WARN, stdout +log4cpp.appender.stdout=org.apache.log4cpp.ConsoleAppender +log4cpp.appender.stdout.layout=org.apache.log4cpp.PatternLayout +log4cpp.appender.stdout.layout.ConversionPattern=%d [%t] %-5p %c - %m%n +log4cpp.category.ch_semafor_stxm.test=INFO +``` + +Details can be found [here](https://logging.apache.org/log4j/2.x/manual/configuration.html#configuration-with-properties). In order to see more messages, set the standard output (i.e. stdout) to DEBUG with `log4cpp.rootCategory=DEBUG, stdout`. + +## Microscope Control +This file contains a JSON structure that provides _named positions_ and is passed to the user interface. This can be used to configure buttons that move a positioner (or set of positioners) to a predefined value (e.g. "OSA out" could move OSAX to -3000 and OSAY to 4000). The JSON structure contains one field called "InOut", whose value is another structure with the name of each field corresponding to a separate _named position_. Each of these _named position_ fields contains a list (one entry per involved positioner) of structure with 3 fields: + + **positioner**::
+ String value defining the positioner to be moved. + + **positionIn**::
+ Double value defining the "in" value of the positioner. + + **positionOut**::
+ Double value defining the "out" value of the positioner. + +Example: +```json +{ + "InOut" : { + "OSA" : [ + { + "positionIn" : 0.0, + "positionOut" : -3000.0, + "positioner" : "OSAX" + }, + { + "positionIn" : 0.0, + "positionOut" : 4000.0, + "positioner" : "OSAY" + } + ], + "Sample" : [ + { + "positionIn" : 5000.0, + "positionOut" : 10000.0, + "positioner" : "CoarseZ" + } + ], + "ZonePlate" : [ + { + "positionIn" : -5000, + "positionOut" : -18000.0, + "positioner" : "Zoneplate" + } + ] + } +} ``` \ No newline at end of file