NDFileTIFF

author:Mark Rivers, University of Chicago

Overview

NDFileTIFF inherits from NDPluginFile. This plugin saves data in the TIFF file format, which is a popular file format for storing images. There is TIFF support for almost all languages and programs such as IDL and Matlab.

The TIFF plugin supports all 8 NDArray data types (signed and unsigned 8, 16, 32 bit integers, 32 and 64 bit floating point. It supports all color modes (Mono, RGB1, RGB2, and RGB3). Note that many TIFF readers do not support 16 or 32 bit integer TIFF files, floating point TIFF files, and 16 or 32 bit color files. NDFileTIFF is limited to a single array per file, but capture and stream mode are supported by writing multiple TIFF files.

Tests were done with IDL, ImageJ, and the Python Imaging Library (PIL) to read TIFF files with all 8 data types. IDL can read all 8 types, although it does not support signed 8-bit integers so it treats them as unsigned. ImageJ can read all types except NDFloat64. PIL cannot read NDInt8, NDUInt32, or NDFloat64.

The TIFF plugin writes four NDArray class members as TIFF tags starting with tag number 65000. For historical reasons these tags do not have labels. They are the following NDArray class members converted to ASCII:

-  65000: timeStamp
-  65001: uniqueID
-  65002: epicsTS (seconds)
-  65003: epicsTS (nano-seconds)

The TIFF plugin also writes all NDAttributes attached to the NDArray as TIFF ASCII file tags, up to a maximum of 536 attributes. These tags start with number 65010. The NDAttributes are converted to ASCII with attribute name, followed by a colon and the attribute value. This information can be displayed, for example, with the tiffinfo program:

>tiffinfo ~/scratch/test_001.tif
TIFF Directory at offset 0x400008 (4194312)
Image Width: 1024 Image Length: 1024
Bits/Sample: 32
Sample Format: IEEE floating point
Compression Scheme: None
Photometric Interpretation: min-is-black
Samples/Pixel: 1
Rows/Strip: 1024
Planar Configuration: single image plane
Make: Unknown
Model: Unknown
Software: EPICS areaDetector
Tag 65000: 854478417.972736
Tag 65001: 3059
Tag 65002: 854478418
Tag 65003: 1977554
Tag 65010: ColorMode:0
Tag 65011: RingCurrent:100.010157
Tag 65012: RingCurrent_EGU:mA
Tag 65013: ID_Energy:42.181675
Tag 65014: ID_Energy_EGU:keV
Tag 65015: ImageCounter:3059
Tag 65016: MaxSizeX:1024
Tag 65017: MaxSizeY:1024
Tag 65018: CameraModel:Basic simulator
Tag 65019: AttributesFileParam:simDetectorAttributes.xml
Tag 65020: AttributesFileNative:1139
Tag 65021: AttributesFileString:simDetectorAttributes.xml
Tag 65022: CameraManufacturer:Simulated detector
Tag 65023: Pi:3.141593
Tag 65024: E:2.718282
Tag 65025: Ten:10
Tag 65026: Gettysburg:Four score and seven years ago our fathers

If there is an NDAttribute of type NDAttrString named TIFFImageDescription then this attribute is written to the TIFFTAG_IMAGEDESCRIPTION tag in the TIFF file. This is the output of tiffinfo on a file written by the TIFF plugin. The data is from a Pilatus detector. The areaDetector ADPilatus driver reads the TIFFTAG_IMAGEDESCRIPTION data from the original TIFF file that camserver writes, and adds it to the NDArray as the TIFFImageDescription attribute. Note that the ImageDescription data is present twice, both in the standard TIFF ImageDesciption tag and in user tag 65010 in the TIFF file with all other NDAttributes. This is OK because some data processing code may expect to find the information in one location or the other.

>tiffinfo ~/scratch/pilatus_test_000.tif
TIFF Directory at offset 0x5cbdc (379868)
  Image Width: 487 Image Length: 195
  Bits/Sample: 32
  Sample Format: signed integer
  Compression Scheme: None
  Photometric Interpretation: min-is-black
  Samples/Pixel: 1
  Rows/Strip: 195
  Planar Configuration: single image plane
  ImageDescription: # Pixel_size 172e-6 m x 172e-6 m
# Silicon sensor, thickness 0.000320 m
# Exposure_time 1.0000000 s
# Exposure_period 1.0000000 s
# Tau = 203.0e-09 s
# Count_cutoff 1390572 counts
# Threshold_setting: 7000 eV
# Gain_setting: mid gain (vrf = -0.200)
# N_excluded_pixels = 0
# Excluded_pixels: (nil)
# Flat_field: (nil)
# Trim_file: p100k0118_E10000_T7000_vrf_m0p20.bin
# Image_path: .../Data/gpd_user/data/idc/2017/run1/setup_603/setup/images/
# Wavelength 1.54000 A
# Energy_range (0, 0) eV
# Detector_distance 1.00000 m
# Detector_Voffset 0.00000 m
# Beam_xy (0.00, 0.00) pixels
# Flux 0.000000
# Filter_transmission 1.0000
# Start_angle 0.0000 deg.
# Angle_increment 0.1000 deg.
# Detector_2theta 0.0000 deg.
# Polarization 0.990
# Alpha 0.0000 deg.
# Kappa 0.0000 deg.
# Phi 0.0000 deg.
# Phi_increment 0.1000 deg.
# Omega 0.0000 deg.
# Omega_increment 0.1000 deg.
# Chi 0.0000 deg.
# Chi_increment 0.1000 deg.
# Oscillation_axis X, CW
# N_oscillations 1

  Make: Unknown
  Model: Unknown
  Software: EPICS areaDetector
  Tag 65000: 854479056.813133
  Tag 65001: 1
  Tag 65002: 854479058
  Tag 65003: 208583261
  Tag 65010: TIFFImageDescription:# Pixel_size 172e-6 m x 172e-6 m
# Silicon sensor, thickness 0.000320 m
# Exposure_time 1.0000000 s
# Exposure_period 1.0000000 s
# Tau = 203.0e-09 s
# Count_cutoff 1390572 counts
# Threshold_setting: 7000 eV
# Gain_setting: mid gain (vrf = -0.200)
# N_excluded_pixels = 0
# Excluded_pixels: (nil)
# Flat_field: (nil)
# Trim_file: p100k0118_E10000_T7000_vrf_m0p20.bin
# Image_path: .../Data/gpd_user/data/idc/2017/run1/setup_603/setup/images/
# Wavelength 1.54000 A
# Energy_range (0, 0) eV
# Detector_distance 1.00000 m
# Detector_Voffset 0.00000 m
# Beam_xy (0.00, 0.00) pixels
# Flux 0.000000
# Filter_transmission 1.0000
# Start_angle 0.0000 deg.
# Angle_increment 0.1000 deg.
# Detector_2theta 0.0000 deg.
# Polarization 0.990
# Alpha 0.0000 deg.
# Kappa 0.0000 deg.
# Phi 0.0000 deg.
# Phi_increment 0.1000 deg.
# Omega 0.0000 deg.
# Omega_increment 0.1000 deg.
# Chi 0.0000 deg.
# Chi_increment 0.1000 deg.
# Oscillation_axis X, CW
# N_oscillations 1

The NDFileNetTIFF class documentation describes this class in detail.

Configuration

The NDFileTIFF plugin is created with the NDFileTIFFConfigure command, either from C/C++ or from the EPICS IOC shell.

NDFileTIFFConfigure (const char *portName, int queueSize, int blockingCallbacks,
                     const char *NDArrayPort, int NDArrayAddr, size_t maxMemory,
                     int priority, int stackSize)

For details on the meaning of the parameters to this function refer to the detailed documentation on the NDFileTIFFConfigure function in the NDFileTIFF.cpp documentation and in the documentation for the constructor for the NDFileTIFF class.