# -*- coding: utf-8 -*-
# imageio is distributed under the terms of the (new) BSD License.
""" SPE file reader
"""
import os
import logging
import numpy as np
from .. import formats
from ..core import Format
logger = logging.getLogger(__name__)
class Spec:
"""SPE file specification data
Tuples of (offset, datatype, count), where offset is the offset in the SPE
file and datatype is the datatype as used in `numpy.fromfile`()
`data_start` is the offset of actual image data.
`dtypes` translates SPE datatypes (0...4) to numpy ones, e. g. dtypes[0]
is dtype("<f") (which is np.float32).
`controllers` maps the `type` metadata to a human readable name
`readout_modes` maps the `readoutMode` metadata to something human readable
although this may not be accurate since there is next to no documentation
to be found.
"""
basic = {
"datatype": (108, "<h"), # dtypes
"xdim": (42, "<H"),
"ydim": (656, "<H"),
"xml_footer_offset": (678, "<Q"),
"NumFrames": (1446, "<i"),
"file_header_ver": (1992, "<f"),
}
metadata = {
# ROI information
"NumROI": (1510, "<h"),
"ROIs": (
1512,
np.dtype(
[
("startx", "<H"),
("endx", "<H"),
("groupx", "<H"),
("starty", "<H"),
("endy", "<H"),
("groupy", "<H"),
]
),
10,
),
# chip-related sizes
"xDimDet": (6, "<H"),
"yDimDet": (18, "<H"),
"VChipXdim": (14, "<h"),
"VChipYdim": (16, "<h"),
# other stuff
"controller_version": (0, "<h"),
"logic_output": (2, "<h"),
"amp_high_cap_low_noise": (4, "<H"), # enum?
"mode": (8, "<h"), # enum?
"exposure_sec": (10, "<f"),
"date": (20, "<10S"),
"detector_temp": (36, "<f"),
"detector_type": (40, "<h"),
"st_diode": (44, "<h"),
"delay_time": (46, "<f"),
# shutter_control: normal, disabled open, disabled closed
# But which one is which?
"shutter_control": (50, "<H"),
"absorb_live": (52, "<h"),
"absorb_mode": (54, "<H"),
"can_do_virtual_chip": (56, "<h"),
"threshold_min_live": (58, "<h"),
"threshold_min_val": (60, "<f"),
"threshold_max_live": (64, "<h"),
"threshold_max_val": (66, "<f"),
"time_local": (172, "<7S"),
"time_utc": (179, "<7S"),
"adc_offset": (188, "<H"),
"adc_rate": (190, "<H"),
"adc_type": (192, "<H"),
"adc_resolution": (194, "<H"),
"adc_bit_adjust": (196, "<H"),
"gain": (198, "<H"),
"comments": (200, "<80S", 5),
"geometric": (600, "<H"), # flags
"sw_version": (688, "<16S"),
"spare_4": (742, "<436S"),
"XPrePixels": (98, "<h"),
"XPostPixels": (100, "<h"),
"YPrePixels": (102, "<h"),
"YPostPixels": (104, "<h"),
"readout_time": (672, "<f"),
"xml_footer_offset": (678, "<Q"),
"type": (704, "<h"), # controllers
"clockspeed_us": (1428, "<f"),
"readout_mode": (1480, "<H"), # readout_modes
"window_size": (1482, "<H"),
"file_header_ver": (1992, "<f"),
}
data_start = 4100
dtypes = {
0: np.dtype(np.float32),
1: np.dtype(np.int32),
2: np.dtype(np.int16),
3: np.dtype(np.uint16),
8: np.dtype(np.uint32),
}
controllers = [
"new120 (Type II)",
"old120 (Type I)",
"ST130",
"ST121",
"ST138",
"DC131 (PentaMax)",
"ST133 (MicroMax/Roper)",
"ST135 (GPIB)",
"VTCCD",
"ST116 (GPIB)",
"OMA3 (GPIB)",
"OMA4",
]
# This was gathered from random places on the internet and own experiments
# with the camera. May not be accurate.
readout_modes = ["full frame", "frame transfer", "kinetics"]
# Do not decode the following metadata keys into strings, but leave them
# as byte arrays
no_decode = ["spare_4"]
class SpeFormat(Format):
""" Some CCD camera software produces images in the Princeton Instruments
SPE file format. This plugin supports reading such files.
Parameters for reading
----------------------
char_encoding : str
Character encoding used to decode strings in the metadata. Defaults
to "latin1".
check_filesize : bool
The number of frames in the file is stored in the file header. However,
this number may be wrong for certain software. If this is `True`
(default), derive the number of frames also from the file size and
raise a warning if the two values do not match.
Metadata for reading
--------------------
ROIs : list of dict
Regions of interest used for recording images. Each dict has the
"top_left" key containing x and y coordinates of the top left corner,
the "bottom_right" key with x and y coordinates of the bottom right
corner, and the "bin" key with number of binned pixels in x and y
directions.
comments : list of str
The SPE format allows for 5 comment strings of 80 characters each.
controller_version : int
Hardware version
logic_output : int
Definition of output BNC
amp_hi_cap_low_noise : int
Amp switching mode
mode : int
Timing mode
exp_sec : float
Alternative exposure in seconds
date : str
Date string
detector_temp : float
Detector temperature
detector_type : int
CCD / diode array type
st_diode : int
Trigger diode
delay_time : float
Used with async mode
shutter_control : int
Normal, disabled open, or disabled closed
absorb_live : bool
on / off
absorb_mode : int
Reference strip or file
can_do_virtual_chip : bool
True or False whether chip can do virtual chip
threshold_min_live : bool
on / off
threshold_min_val : float
Threshold minimum value
threshold_max_live : bool
on / off
threshold_max_val : float
Threshold maximum value
time_local : str
Experiment local time
time_utc : str
Experiment UTC time
adc_offset : int
ADC offset
adc_rate : int
ADC rate
adc_type : int
ADC type
adc_resolution : int
ADC resolution
adc_bit_adjust : int
ADC bit adjust
gain : int
gain
sw_version : str
Version of software which created this file
spare_4 : bytes
Reserved space
readout_time : float
Experiment readout time
type : str
Controller type
clockspeed_us : float
Vertical clock speed in microseconds
readout_mode : {"full frame", "frame transfer", "kinetics", ""}
Readout mode. Empty string means that this was not set by the
Software.
window_size : int
Window size for Kinetics mode
file_header_ver : float
File header version
chip_size : [int, int]
x and y dimensions of the camera chip
virt_chip_size : [int, int]
Virtual chip x and y dimensions
pre_pixels : [int, int]
Pre pixels in x and y dimensions
post_pixels : [int, int],
Post pixels in x and y dimensions
geometric : list of {"rotate", "reverse", "flip"}
Geometric operations
"""
def _can_read(self, request):
return (
request.mode[1] in self.modes + "?" and request.extension in self.extensions
)
def _can_write(self, request):
return False
class Reader(Format.Reader):
def _open(self, char_encoding="latin1", check_filesize=True):
self._file = self.request.get_file()
self._char_encoding = char_encoding
info = self._parse_header(Spec.basic)
self._file_header_ver = info["file_header_ver"]
self._dtype = Spec.dtypes[info["datatype"]]
self._shape = (info["ydim"], info["xdim"])
self._len = info["NumFrames"]
if check_filesize:
# Some software writes incorrect `NumFrames` metadata.
# To determine the number of frames, check the size of the data
# segment -- until the end of the file for SPE<3, until the
# xml footer for SPE>=3.
data_end = (
info["xml_footer_offset"]
if info["file_header_ver"] >= 3
else os.path.getsize(self.request.get_local_filename())
)
l = data_end - Spec.data_start
l //= self._shape[0] * self._shape[1] * self._dtype.itemsize
if l != self._len:
logger.warning(
"The file header of %s claims there are %s frames, "
"but there are actually %s frames.",
self.request.filename,
self._len,
l,
)
self._len = min(l, self._len)
self._meta = None
def _get_meta_data(self, index):
if self._meta is None:
if self._file_header_ver < 3:
self._init_meta_data_pre_v3()
else:
self._init_meta_data_post_v3()
return self._meta
def _close(self):
# The file should be closed by `self.request`
pass
def _init_meta_data_pre_v3(self):
self._meta = self._parse_header(Spec.metadata)
nr = self._meta.pop("NumROI", None)
nr = 1 if nr < 1 else nr
self._meta["ROIs"] = roi_array_to_dict(self._meta["ROIs"][:nr])
# chip sizes
self._meta["chip_size"] = [
self._meta.pop("xDimDet", None),
self._meta.pop("yDimDet", None),
]
self._meta["virt_chip_size"] = [
self._meta.pop("VChipXdim", None),
self._meta.pop("VChipYdim", None),
]
self._meta["pre_pixels"] = [
self._meta.pop("XPrePixels", None),
self._meta.pop("YPrePixels", None),
]
self._meta["post_pixels"] = [
self._meta.pop("XPostPixels", None),
self._meta.pop("YPostPixels", None),
]
# comments
self._meta["comments"] = [str(c) for c in self._meta["comments"]]
# geometric operations
g = []
f = self._meta.pop("geometric", 0)
if f & 1:
g.append("rotate")
if f & 2:
g.append("reverse")
if f & 4:
g.append("flip")
self._meta["geometric"] = g
# Make some additional information more human-readable
t = self._meta["type"]
if 1 <= t <= len(Spec.controllers):
self._meta["type"] = Spec.controllers[t - 1]
else:
self._meta["type"] = ""
m = self._meta["readout_mode"]
if 1 <= m <= len(Spec.readout_modes):
self._meta["readout_mode"] = Spec.readout_modes[m - 1]
else:
self._meta["readout_mode"] = ""
# bools
for k in (
"absorb_live",
"can_do_virtual_chip",
"threshold_min_live",
"threshold_max_live",
):
self._meta[k] = bool(self._meta[k])
# frame shape
self._meta["frame_shape"] = self._shape
def _parse_header(self, spec):
ret = {}
# Decode each string from the numpy array read by np.fromfile
decode = np.vectorize(lambda x: x.decode(self._char_encoding))
for name, sp in spec.items():
self._file.seek(sp[0])
cnt = 1 if len(sp) < 3 else sp[2]
v = np.fromfile(self._file, dtype=sp[1], count=cnt)
if v.dtype.kind == "S" and name not in Spec.no_decode:
# Silently ignore string decoding failures
try:
v = decode(v)
except Exception:
logger.warning(
'Failed to decode "{}" metadata '
"string. Check `char_encoding` "
"parameter.".format(name)
)
try:
# For convenience, if the array contains only one single
# entry, return this entry itself.
v = v.item()
except ValueError:
v = np.squeeze(v)
ret[name] = v
return ret
def _init_meta_data_post_v3(self):
info = self._parse_header(Spec.basic)
self._file.seek(info["xml_footer_offset"])
xml = self._file.read()
self._meta = {"__xml": xml}
def _get_length(self):
if self.request.mode[1] in "vV":
return 1
else:
return self._len
def _get_data(self, index):
if index < 0:
raise IndexError("Image index %i < 0" % index)
if index >= self._len:
raise IndexError("Image index %i > %i" % (index, self._len))
if self.request.mode[1] in "vV":
if index != 0:
raise IndexError("Index has to be 0 in v and V modes")
self._file.seek(Spec.data_start)
data = np.fromfile(
self._file,
dtype=self._dtype,
count=self._shape[0] * self._shape[1] * self._len,
)
data = data.reshape((self._len,) + self._shape)
else:
self._file.seek(
Spec.data_start
+ index * self._shape[0] * self._shape[1] * self._dtype.itemsize
)
data = np.fromfile(
self._file, dtype=self._dtype, count=self._shape[0] * self._shape[1]
)
data = data.reshape(self._shape)
return data, self._get_meta_data(index)
def roi_array_to_dict(a):
"""Convert the `ROIs` structured arrays to :py:class:`dict`
Parameters
----------
a : numpy.ndarray
Structured array containing ROI data
Returns
-------
list of dict
One dict per ROI. Keys are "top_left", "bottom_right", and "bin",
values are tuples whose first element is the x axis value and the
second element is the y axis value.
"""
l = []
a = a[["startx", "starty", "endx", "endy", "groupx", "groupy"]]
for sx, sy, ex, ey, gx, gy in a:
d = {
"top_left": [int(sx), int(sy)],
"bottom_right": [int(ex), int(ey)],
"bin": [int(gx), int(gy)],
}
l.append(d)
return l
fmt = SpeFormat("spe", "SPE file format", ".spe", "iIvV")
formats.add_format(fmt, overwrite=True)