camera.formats.raw (version 638)		index
d:\00_ip\spmdev\tripod\applications\python\packages\camera\formats\raw.py

Module raw provides access to frame and channel information of Camera raw files.
 
Camera is the control and analysis application for the Leiden Probe Microscopy
Scanning Tunneling Microscope (STM) and for the Atomic Force Microscope (AFM).
Camera is the acronym for Computer Aided Measurement Environment for Realtime
Atomic imaging.
 
During a measurement Camera collects the data in a 'swap file'. When the measurement
has been completed, Camera creates a 'raw file' from the data in the named swap file.
 
Raw File Format
 
   The raw file contains information about the measurements and the image data itself.
   This information is roughly organized as follows:
 
                           (class RawFileReader)
      .-------------------------------------------------.
      | Header             (class RawFileHeader)        |
      |-------------------------------------------------|
      | Frame 0 info       (class RawFileFrameInfo)     |
      |   Channel 0 info   (class RawFileChannelInfo    |
      |   Channel 0 image  (class RawFileChannelImage)  |
      |          ...                                    |
      |   Channel K info                                |
      |   Channel K image                               |
      |-------------------------------------------------|
      |                     ...                         |
      |-------------------------------------------------|
      | Frame N info                                    |
      |   Channel 0 info                                |
      |   Channel 0 image                               |
      |          ...                                    |
      |   Channel K info                                |
      |   Channel K image                               |
      '-------------------------------------------------'
 
Header
 
   The file contains a single header with information such as hardware interface
   id and version and channels used and their names. For example:
 
      header: file version id: RAW1305
      header: interface id: CameraSTM_d
      header: interface version: 4.0
      header: frame count: 434
      header: channel mask: 0x7, 0b111
      header: channel count: 3
      header: channel0 name: Topographical height map
      header: channel1 name: Topographical height map [dZ]
      header: channel2 name:
      header: channel3 name:
      header: channel4 name:
      header: channel5 name:
      header: channel6 name:
      header: channel7 name:
      header: channel0 unit: nm
      header: channel1 unit: nm
      header: channel2 unit:
      header: channel3 unit:
      header: channel4 unit:
      header: channel5 unit:
      header: channel6 unit:
      header: channel7 unit:
 
   The header is represented by class RawFileHeader.
 
Frame Information
 
   For each frame there is a section with information about the measurement, such
   as the acquisition time, the scanned physical area (RawFileFrameScanArea) and
   the measurement (device) settings (RawFileFrameDeviceInfo). For example:
 
      frame 0: id: 0
      frame 0: acquisition time: 1275418042, Tue Jun 01 18:47:22 2010
      frame 0: x-offset [pm]: 35000
      frame 0: y-offset [pm]: 95000
      frame 0: x-step [pm]: 19.53125
      frame 0: x-step [pm]: 19.53125
      frame 0: x-size [pixels]: 512
      frame 0: y-size [pixels]: 512
      frame 0: scan angle [rad]: 0.0
      frame 0: sizeof device info: 440
      frame 0: pixel clock [kHz]: 80.0
      frame 0: sample per point: 8
      frame 0: oversampling factor: 8
      frame 0: z-gain: 32
      frame 0: dz-gain: 1
      frame 0: bandwidth [kHz]: 600
      frame 0: z-offset [??]: -1.85
      frame 0: zoverdz: 1.0
      frame 0: x-rounding [%]: 0.0
      frame 0: backwardstroke: 1024
      frame 0: u-sample [V]: 2.0
      frame 0: triangle attenuation: 0, 0x0
      frame 0: sawtooth attenuation: 0, 0x0
      frame 0: x-sample slope: 0
      frame 0: y-sample slope: 0
      frame 0: integration time code: 112
      frame 0: proportional gain code: 6
      frame 0: setvalue code: 46
      frame 0: 3D measurements per pixel: 0
      frame 0: 3D display index: 0
      frame 0: 3D frame number: 0
      frame 0: extra mixer offset [V]: 0.0
      frame 0: extra mixer x-gain: 0
      frame 0: extra mixer y-gain: 0
      frame 0: extra mixer attenuation: 4
      frame 0: extra mixer slewrate: 65535
      frame 0: adc channels: array('H', [0, 0, 0, 0, 42076, 271, 0, 0])
      frame 0: iv name:
 
   The frame information is represented by class RawFileFrameInfo.
 
   Please note that the frames are selected by their sequence number in the file,
   not by their frameId; these may differ if frames have been deleted.
 
Channel Information
 
   For each channel in a frame there is information about the size of the image
   and of the scaling of its data. For example frame 0, channel 0:
 
      channel 0.0: flags: 3, 0b11
      channel 0.0: x-size: 512
      channel 0.0: y-size: 513
      channel 0.0: pixels: 525312
      channel 0.0: data scale factor: 0.00074065625
      channel 0.0: data offset: -193986
      channel 0.0: parameter mask: 7, 0b111
      channel 0.0: x-slope [?]: 0.0
      channel 0.0: y-slope [?]: 0.0
      channel 0.0: average [?]: 162.075654087
      channel 0.0: z-min: -32768
      channel 0.0: z-max: 32766
 
   The channel information is represented by class RawFileChannelInfo.
 
Channel Images
 
   And finally for each channel in a frame there is the image information
   (16-bit signed integers), represented by class RawFileChannelImage.
 
 
Classes, Exceptions and Functions
 
Classes
   - RawFileReader - provide access to the various parts of a Camera raw file
   - RawFileHeader - provide access to the elements of the file header
   - RawFileFrameInfo - provide access to the elements of a frame header
   - RawFileChannelInfo - provide access to the elements of a channel header
   - RawFileChannelImage - provide access to the channel image data
 
Exceptions
   - RawFileReaderError - module's exception class
 
Functions
   - supportedRawFileFormats() - provide a list of the supported raw file formats
 
 
Examples
 
   Below are several examples how the classes in this module can be used to retrieve
   the various parts of the Camera raw files.
 
   #
   # Obtain raw file header, and last frame, last channel information:
   #
   from camera.formats.raw import *
 
   f = open( path, "rb" )
   reader = RawFileReader( f )
 
   # can also use: reader = RawFileReader( path )
 
   print( reader.header )
 
   frame = reader.frameCount - 1
   channel = reader.channelCount - 1
 
   print( reader.frameInfo( frame ) )
   print( reader.channelInfo( frame, channel ) )
   print( reader.channelImage( frame, channel ) )
 
   #
   # Iterate over all frame information headers:
   #
   for info in reader.frameInfoIter():
      print( 'frame {frm}:'.format( frm=info.frame ) )
      print( info )
 
   #
   # Iterate over all channel information headers:
   #
   for info in reader.channelInfoIter():
      print( 'channel {frm}.{chn}:'.format( frm=info.frame, chn=info.channel ) )
      print( info )
 
   #
   # Iterate over all channel images:
   #
   for image in reader.imageIter():
      print( 'image {frm}.{chn}:'.format( frm=image.frame, chn=image.channel ) )
      print( image )
      print()
 
 
References
 
   The C++ code with reading of the raw file and relevant data structures are at:
 
   method CScanDocument::BuildInternalDataStructureFromRAW()
   - https://svn.eld.leidenuniv.nl/repos/ip-camera/application/trunk/Camera/ScanDocument.h
   - https://svn.eld.leidenuniv.nl/repos/ip-camera/application/trunk/Camera/ScanDocument.cpp
   - see Python class RawFileReader, method _createIndex()
 
   struct __SpmScanPosition
   - https://svn.eld.leidenuniv.nl/repos/ip-camera/application/trunk/Camera/InterfaceDll.h
   - see Python class RawFileFrameScanArea
 
   struct __SpmCameraDeviceSpecificFrameData
   - https://svn.eld.leidenuniv.nl/repos/ip-camera/application/trunk/CameraDll/CameraDll.h
   - see Python class RawFileFrameDeviceInfo
 
 
Weblinks
 
   IP: Interface Physics, http://www.physics.leidenuniv.nl/sections/cm/ip/
   LPM: Leiden Probe Microscopy, http://www.leidenprobemicroscopy.com/
 
   See also http://www.physics.leidenuniv.nl/sections/cm/ip/Internal/Camera/Camera-MainPage.html

 
Modules
       
io
numpy
string
sys
time
camera.formats.util

 
Classes
       
__builtin__.object
RawFileChannelImage
RawFileChannelInfo
RawFileFrameInfo
RawFileHeader
RawFileReader
__builtin__.type(__builtin__.object)
_metacls
exceptions.Exception(exceptions.BaseException)
RawFileReaderError

 
class RawFileChannelImage(__builtin__.object)
    Class to read and represent channel image data of a Camera raw file.
 
  Methods defined here:
__init__(self, f, pos, cinfo)
Create the image from the given channel information and from the
data in the file at the specified position.
 
Keyword arguments:
pos -- position in stream
cinfo -- channel information object
__str__(self)
String representation: present an image as 2-dimensional textual data
asArray(self, direction=None)
Provide the image data as a two-dimensional array (numpy module)
Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)
channel
'channel' property.
flags
'flags' property.
frame
'frame' property.
pixels
'pixels' property.
xsize
'xsize' property.
ysize
'ysize' property.

 
class RawFileChannelInfo(__builtin__.object)
    Class to read and represent channel information of a Camera raw file.
 
  Methods defined here:
__init__(self, f, pos, frame=None, channel=None)
Create the channel information from a file object at the specified position.
 
Keyword arguments:
f -- stream object
pos -- position in stream
frame -- frame index
channel -- channel index
 
See also RawFileFrameInfo.
__str__(self)
String representation.
Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)
average
'average' property.
channel
'channel' property.
dataOffset
'dataOffset' property.
dataScaleFactor
'dataScaleFactor' property.
flags
'flags' property.
frame
'frame' property.
parameterMask
'parameterMask' property.
pixels
'pixels' property.
sizeOf
'sizeOf' property.
sizeOfImage
'sizeOfImage' property: size (in bytes) of all stored pixels
xsize
'xsize' property.
xslope
'xslope' property.
ysize
'ysize' property.
yslope
'yslope' property.
zmax
'zmax' property.
zmin
'zmin' property.
Data and other attributes defined here:
LR = 1
LRRL = 3
RL = 2

 
class RawFileFrameInfo(__builtin__.object)
    Class to read and represent the header of a frame of a Camera raw file.
 
  Methods defined here:
__init__(self, f, pos, frame=None)
Create the collection from a file object at the specified position.
Note that the frames are selected by their sequence number in the file,
not by their frameId; index and id may differ if frames have been deleted.
 
Keyword arguments:
f -- stream object
pos -- position in stream
frame -- frame index
__str__(self)
String representation.
Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)
acquisitionTime
'acquisitionTime' property; seconds since epoch (1970).
adcChannels
'adcChannels' property; yields list.
backwardstroke
'backwardstroke' property.
bandwidth_kHz
'bandwidth_kHz' property.
d3DisplayIndex
'3dDisplayIndex' property.
d3FrameNumber
'3dFrameNumber' property.
d3MeasurementsPerPixel
'3dMeasurementsPerPixel' property.
deviceInfo
'deviceInfo' property.
dzgain
'dzgain' property.
extraMixerAttenuation
'extraMixerAttenuation' property.
extraMixerOffset
'extraMixerOffset' property.
extraMixerSlewrate
'extraMixerSlewrate' property.
extraMixerXgain
'extraMixerXgain' property.
extraMixerYgain
'extraMixerYgain' property.
frame
'frame' property.
frameId
'frameId' property.
integrationTimeCode
'integrationTimeCode' property.
ivname
'ivname' property.
oversamplingFactor
'oversamplingFactor' property.
pixelclock_kHz
'pixelclock_kHz' property.
proportionalGainCode
'proportionalGainCode' property.
samplesPerPoint
'samplesPerPoint' property.
sawtoothAttenuation
'sawtoothAttenuation' property.
scanArea
'scanArea' property.
scanangle_rad
'scan angle [rad]' property.
setvalueCode
'setvalueCode' property.
sizeOf
'sizeOf' property.
sizeOfScanArea
'sizeofInfo' property.
sizeofDeviceInfo
'sizeofInfo' property.
timeformat
'timeformat' property.
triangleAttenuation
'triangleAttenuation' property.
usample_V
'usample_V' property.
xoffset_pm
'x-offset [pm]' property.
xrounding_pct
'xrounding_pct' property.
xsampleSlope
'xsampleSlope' property.
xsize_pix
'x-size [pixels]' property.
xstep_pm
'x-step [pm]' property.
yoffset_pm
'y-offset [pm]' property.
ysampleSlope
'ysampleSlope' property.
ysize_pix
'y-size [pixels]' property.
ystep_pm
'y-step [pm]' property.
zgain
'zgain' property.
zoffset_QQ
'zoffset_QQ' property.
zoverdz
'zoverdz' property.

 
class RawFileHeader(__builtin__.object)
    Class to read and represent a header of a Camera raw file.
 
The header class can be treated as a dictionary and the funtions items(),
keys() and values() enable iteration over it.
 
Please note that this (currently) is not true for the classes RawFileFrameInfo
and RawFileChannelInfo. It is not yet clear to me (Martin) if being a dictionary
is a useful property of the class.
 
  Methods defined here:
__getitem__(self, k)
Provide item
__init__(self, f)
Create the header from a file object.
__iter__(self)
Provide iterator on header
__str__(self)
String representation.
channelName(self, i)
Name of the specified channel.
channelUnit(self, i)
Unit of the specified channel.
items(self)
Provide iteration over items
keys(self)
Provide iteration over keys
values(self)
Provide iteration over values
Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)
channel0Name
'channel0Name' property.
channel0Unit
'channel0Unit' property.
channel1Name
'channel1Name' property.
channel1Unit
'channel1Unit' property.
channel2Name
'channel2Name' property.
channel2Unit
'channel2Unit' property.
channel3Name
'channel0Name' property.
channel3Unit
'channel0Unit' property.
channel4Name
'channel4Name' property.
channel4Unit
'channel4Unit' property.
channel5Name
'channel5Name' property.
channel5Unit
'channel5Unit' property.
channel6Name
'channel6Name' property.
channel6Unit
'channel6Unit' property.
channel7Name
'channel0Name' property.
channel7Unit
'channel0Unit' property.
channelCount
'channelCount' derived (ro) property.
channelMask
'channelMask' property.
fileVersionId
'versionId' property.
frameCount
'frameCount' property.
interfaceId
'interfaceId' property.
interfaceVersionMajor
'interfaceVersionMajor' property.
interfaceVersionMinor
'interfaceVersionMinor' property.
sizeOf
'sizeOf' property.

 
class RawFileReader(__builtin__.object)
    Reader for Camera raw files.
 
  Methods defined here:
__del__(self)
Clean-up: close file if we opened it.
__init__(self, inp)
Create the reader from a file object or from a path.
 
Keyword arguments:
inp -- the stream (file) object, or the path to the file
channelImage(self, fi, ci)
Provide the image of the channel given by its indices.
Note that the frames are selected by their sequence number in the file,
not by their frameId; these may differ if frames have been deleted.
 
Keyword arguments:
fi -- frame index
ci -- channel index
 
See also RawFileChannelImage.
channelInfo(self, fi, ci)
Provide the channel information of the channel given by its indices.
Note that the frames are selected by their sequence number in the file,
not by their frameId; these may differ if frames have been deleted.
 
Keyword arguments:
fi -- frame index
ci -- channel index
 
See also RawFileChannelInfo.
channelInfoIter(self)
Iterator for channel information, see also RawFileChannelInfo.
frameInfo(self, fi)
Provide the frame information of the frame given by its index.
Note that the frames are selected by their sequence number in the file,
not by their frameId; these may differ if frames have been deleted.
 
Keyword arguments:
fi -- frame index
 
See also RawFileFrameInfo.
frameInfoIter(self)
Iterator for frame information, see also RawFileFrameInfo.
imageIter(self)
Iterator for images, see also RawFileChannelImage.
Data descriptors defined here:
__dict__
dictionary for instance variables (if defined)
__weakref__
list of weak references to the object (if defined)
channelCount
'channelCount' property.
frameCount
'frameCount' property.
header
'header' property. See also RawFileHeader.
timeformat
'timeformat' property. See also strftime(),
http://opengroup.org/onlinepubs/007908799/xsh/strftime.html

 
class RawFileReaderError(exceptions.Exception)
    Exception class for this module.
 
 
Method resolution order:
RawFileReaderError
exceptions.Exception
exceptions.BaseException
__builtin__.object
Methods defined here:
__init__(self, value)
Create the exception with the given value.
__str__(self)
String representation.
Data descriptors defined here:
__weakref__
list of weak references to the object (if defined)
Data and other attributes inherited from exceptions.Exception:
__new__ = <built-in method __new__ of type object>
T.__new__(S, ...) -> a new object with type S, a subtype of T
Methods inherited from exceptions.BaseException:
__delattr__(...)
x.__delattr__('name') <==> del x.name
__getattribute__(...)
x.__getattribute__('name') <==> x.name
__getitem__(...)
x.__getitem__(y) <==> x[y]
__getslice__(...)
x.__getslice__(i, j) <==> x[i:j]
 
Use of negative indices is not supported.
__reduce__(...)
__repr__(...)
x.__repr__() <==> repr(x)
__setattr__(...)
x.__setattr__('name', value) <==> x.name = value
__setstate__(...)
__unicode__(...)
Data descriptors inherited from exceptions.BaseException:
__dict__
args
message
__metaclass__ = <class 'camera.formats.raw._metacls'>

 
Functions
       
supportedRawFileFormats()
Provide a list of raw file formats supported by this module, e.g. ['RAW1305'].

 
Data
        __all__ = ['supportedRawFileFormats', 'RawFileReaderError', 'RawFileReader', 'RawFileHeader', 'RawFileFrameInfo', 'RawFileChannelInfo', 'RawFileChannelImage']
__author__ = 'Martin Moene <m.j.moene@eld.physics.LeidenUniv.nl>'
__url__ = 'http://www.physics.leidenuniv.nl/sections/cm/ip/Internal/Camera/Camera-MainPage.html'
__version__ = '$Revision: 638 $'
__version_date__ = '$Date: 2012-01-09 18:04:51 +0100 (Mon, 09 Jan 2012) $'

 
Author
        Martin Moene <m.j.moene@eld.physics.LeidenUniv.nl>