⨽g}$dZddlmZddlZddlZddlmZmZmZmZm Z m Z m Z m Z m Z mZddlZddlZddlmZmZmZddlmZmZej2eZGdd ZGd d ZGd d eZdej>de ee e e!ffdZ"y)a Read SPE files. This plugin supports reading files saved in the Princeton Instruments SPE file format. Parameters ---------- 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. char_encoding : str Deprecated. Exists for backwards compatibility; use ``char_encoding`` of ``metadata`` instead. sdt_meta : bool Deprecated. Exists for backwards compatibility; use ``sdt_control`` of ``metadata`` instead. Methods ------- .. note:: Check the respective function for a list of supported kwargs and detailed documentation. .. autosummary:: :toctree: SpePlugin.read SpePlugin.iter SpePlugin.properties SpePlugin.metadata )datetimeN) AnyCallableDictIteratorListMappingOptionalSequenceTupleUnion)RequestIOModeInitializationError)PluginV3ImagePropertiescneZdZdZdddddddZid d d d ej gd dfdddddddddddddddddd d!d"d#d$d%d&d'd(d)d*d+d,id-d.d/d0d1d2d3d4d5d6d7d8d9d:d;d<d=d>d?d@dAdBdCdDdEdFdGdHdIdJdKdLdMdNdOdPdQdRdSdTdUddVdWdXdYddZ Zd[Zej ejej ejej ejej ejej ejd\Zgd]Zgd^Zd_gZy`)aSpecaWSPE 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(" J?B@ jABF :GBH zIBJ zKBL zMBN jOBP ZQBR jSBT ZUBV lWBX LYBZ k[B\ K]B^ K_B` +aBb +cBd  eBf $gBh [iBj$! "!"#(%$#'CBHHJ 288BJJ  288BHH  288BHH  288BII  288BII  F K"AM IrrceZdZdZiddddddddd dd d d d dd ddddddddddddddddddZdd d!d"d#ZGd$d%Zid&ed ed'd(ed)ed ed(d*ed+ed ed,de d-eded.d/e d0d1ed edd2e d3ed ed4d5ed6ed d2d7d8ed d9d:d;ed edd?d@ed edAd<e dBdCed eddfdDdEed ed5dAe d0dFeded,d edGededdHe dIdJeded dedKededHd<e d0ededdeededDescribe how to extract a metadata entry from a comment stringnslicecvtNscalec<||_||_||_||_yN)rrrr)selfrrrrs r__init__z#SDTControlSpec.CommentDesc.__init__s DFDJDHDJr)rrrrint__annotations__rrstrrr floatr rrrr CommentDescrs}L 7 > seSj !!<T5[!!1 ),%)   3%*%  E? rrsdt_major_versionrRDsdt_minor_versionFsdt_controller_namer exposure_timerPIgư> color_coder/detection_channelsr1background_subtractionc |dk(S)NBrxs rzSDTControlSpec.s 18r em_active c |dk(S)NErrs rrzSDTControlSpec. s a3hrem_gainmodulation_active!c |dk(S)NArrs rrzSDTControlSpec. s a3hr pixel_sizeg? sequence_typec"j|Sr)sequence_types)r __class__s rrzSDTControlSpec.s9+C+CA+Frgridn_macro delay_macrogMbP?n_mini delay_mini%OrB7)n_micro delay_micro n_subpics delay_shutterdelay_prebleach bleach_time recovery_timebleach_piezo_active"#c |dk(S)Nzrrs rrzSDTControlSpec.s 1PS8r))rfr)rfrwrdreturnc~|ddddk7ry t|dddt|dddfS#t$rYywxYw)a-Get the version of SDT-control metadata encoded in the comments Parameters ---------- comments List of SPE file comments, typically ``metadata["comments"]``. Returns ------- Major and minor version. ``-1, -1`` if detection failed. r5rLCOMVER)rNP)r ValueError)rds rget_comment_versionz"SDTControlSpec.get_comment_version"s\ A;r"  ) x{2b)*C Br0B,CC C  s !0 <<versionc i}t|ddzD]{} j|d|f}|jD]Q\}} |j ||j |j }|j||jz}|||<S}| jvrLdjtd j} tjd|dd |dd d | d |d|d z} | j|d<|S#t$rYwxYw#t$r+}tjd|d|d||<Yd}~d}~wwxYw)aCExtract SDT-control metadata from comments Parameters ---------- comments List of SPE file comments, typically ``metadata["comments"]``. version Major and minor version of SDT-control metadata format Returns ------- Dict of metadata rwrNz-Failed to decode SDT-control metadata field `z`: z, c|dd|ddS)Nr.rw02rrs rrz/SDTControlSpec.parse_comments..^s1a!Ry1rz)Unsupported SDT-control metadata version rrz. Only versions z@ are supported. Some or all SDT-control metadata may be missing.rcomment)rangecomment_fieldsKeyErroritemsrrrr Exceptionwarningswarnjoinmapstrip) rdrsdt_mdminorcmtnamespecve supported_verrrs rparse_commentszSDTControlSpec.parse_comments6s"71:>* (E  ..wqz5/@A"iik ( d ($&&!1$**!=>Azz-TZZ#$F4L ( (( )22 2 II193K3KLM MM;GAJz2SDTControlSpec.extract_metadata..s%q1u%szSDT-control comments not found.Nr9rSrrmmodulation_scriptzHFailed to decode SDT-control laser modulation script. Bad char_encoding?rVr8) ranyrdebugrpopupdaterdecodeUnicodeDecodeErrorrr )rrcomversdt_metadtsp4rs rextract_metadatazSDTControlSpec.extract_metadatas..tJ/?@ %f% % LL: ; ++D, q q    q  q q q q q q q r r r!" r#$ r%F. N2 Qb" s!C Qb" s!C  ";q%1+s#C  [E"bM5&I  +ar2<  !+ar2"D   %k!R9K&L  Q,>?  {1eBmS9  Q4F!G  +ar2sC  [5B$r t dwxYw)aInstantiate a new SPE file plugin object Parameters ---------- request : Request A request object representing the resource to be operated on. check_filesize : bool If True, compute the number of frames from the filesize, compare it to the frame count in the file header, and raise a warning if the counts don't match. (Certain software may create files with char_encoding : str Deprecated. Exists for backwards compatibility; use ``char_encoding`` of ``metadata`` instead. sdt_meta : bool Deprecated. Exists for backwards compatibility; use ``sdt_control`` of ``metadata`` instead. zcannot write SPE filesNz{Passing `char_encoding` to the constructor is deprecated. Use `char_encoding` parameter of the `metadata()` method instead.ztPassing `sdt_meta` to the constructor is deprecated. Use `sdt_control` parameter of the `metadata()` method instead.r0r rrrrrxrrrwzThe file header of z claims there are z frames, but there are actually z frames.z)SPE plugin cannot read the provided file.) superrr6io_moderwriterrr DeprecationWarning_char_encoding _sdt_metar6get_file_file _parse_headerrr_file_header_verr_dtype_shape_lenseekosSEEK_ENDtellritemsizefilenameminr) rr6r7rr,rdata_endliners rrzSpePlugin.__init__s4 ! <<  6<< /%&>? ?  $ MM#   ,   MM#   "\\**,  S%%djj(;D$():$;D !++d:&67DK<f6DK[)DI )*a/#$78HJJOOAr{{3#zz0H$//1Q$++a.84;;;O;OOO499$MM-dll.C.C-DDV99+%EdV8U!$D$)) 4DI JJOODOO , S%&QR R Ss )FH99I.indexrPc|turWtj}|jd|jdz|jz}|jg|j}n|dkrt d|d||jk\rt d|d|jdtj||jdz|jdz|j jzz}|jd|jdz}|j}|jj|tj|j|j |}|j|S)a<Read a frame or all frames from the file Parameters ---------- index : int Select the index-th frame from the file. If index is `...`, select all frames and stack them along a new axis. Returns ------- A Numpy array of pixel values. rrwzIndex `z` is smaller than 0.z5` exceeds the number of frames stored in this file (`z`).rcount) EllipsisrrrDrE IndexErrorrCrJr@rFrfromfilereshape)rrP read_offsetrS out_shapedatas rreadzSpePlugin.reads< H //KKKNT[[^3dii?E1T[[1I QYwug-ABC C dii % UVZV_V_U``cd  $++a.(4;;q>9DKK.1s=q  "=s)rrE)rs`riterzSpePlugin.iter)s>E$)),<==rexclude_applied sdt_controlc|jdkrB|j |j}|j |j}|j||S|j S)uaSPE specific metadata. Parameters ---------- index : int Ignored as SPE files only store global metadata. exclude_applied : bool Ignored. Exists for API compatibility. char_encoding : str The encoding to use when parsing strings. sdt_control : bool If `True`, decode special metadata written by the SDT-control software if present. Returns ------- metadata : dict Key-value pairs of metadata. Notes ----- SPE v3 stores metadata as XML, whereas SPE v2 uses a binary format. .. rubric:: Supported SPE v2 Metadata fields 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 sdt_major_version : int (only for files created by SDT-control) Major version of SDT-control software sdt_minor_version : int (only for files created by SDT-control) Minor version of SDT-control software sdt_controller_name : str (only for files created by SDT-control) Controller name exposure_time : float (only for files created by SDT-control) Exposure time in seconds color_code : str (only for files created by SDT-control) Color channels used detection_channels : int (only for files created by SDT-control) Number of channels background_subtraction : bool (only for files created by SDT-control) Whether background subtraction war turned on em_active : bool (only for files created by SDT-control) Whether EM was turned on em_gain : int (only for files created by SDT-control) EM gain modulation_active : bool (only for files created by SDT-control) Whether laser modulation (“attenuate”) was turned on pixel_size : float (only for files created by SDT-control) Camera pixel size sequence_type : str (only for files created by SDT-control) Type of sequnce (standard, TOCCSL, arbitrary, …) grid : float (only for files created by SDT-control) Sequence time unit (“grid size”) in seconds n_macro : int (only for files created by SDT-control) Number of macro loops delay_macro : float (only for files created by SDT-control) Time between macro loops in seconds n_mini : int (only for files created by SDT-control) Number of mini loops delay_mini : float (only for files created by SDT-control) Time between mini loops in seconds n_micro : int (only for files created by SDT-control) Number of micro loops delay_micro : float (only for files created by SDT-control) Time between micro loops in seconds n_subpics : int (only for files created by SDT-control) Number of sub-pictures delay_shutter : float (only for files created by SDT-control) Camera shutter delay in seconds delay_prebleach : float (only for files created by SDT-control) Pre-bleach delay in seconds bleach_time : float (only for files created by SDT-control) Bleaching time in seconds recovery_time : float (only for files created by SDT-control) Recovery time in seconds comment : str (only for files created by SDT-control) User-entered comment. This replaces the "comments" field. datetime : datetime.datetime (only for files created by SDT-control) Combines the "date" and "time_local" keys. The latter two plus "time_utc" are removed. modulation_script : str (only for files created by SDT-control) Laser modulation script. Replaces the "spare_4" key. bleach_piezo_active : bool (only for files created by SDT-control) Whether piezo for bleaching was enabled rx)rBr=r>_metadata_pre_v3_metadata_post_v3)rrPr`rras rrzSpePlugin.metadata3s_X  1 $"". $ 3 3 ~~)"nn (( D D%%''rcf|jtj|}|jdd}|dkrdn|}t |dd||d<dDcgc]}|j|dc}|d<dDcgc]}|j|dc}|d<d Dcgc]}|j|dc}|d <d Dcgc]}|j|dc}|d <|d Dcgc] }t |c}|d <g}|jdd}|dzr|j d|dzr|j d|dzr|j d||d<|d} d| cxkrttjkrnntj| dz |d<nd|d<|d} d| cxkrttjkrnntj| dz |d<nd|d<dD]}t||||<|rtj|||Scc}wcc}wcc}wcc}wcc}w)aZExtract metadata from SPE v2 files Parameters ---------- char_encoding String character encoding sdt_control If `True`, try to decode special metadata written by the SDT-control software. Returns ------- dict mapping metadata names to values. r!Nrwr")r*r, chip_size)r.r0virt_chip_size)rnrp pre_pixels)rorq post_pixelsrdrgrrotaterreverser5fliprsru)rErIrKrO) rArrr'roi_array_to_dictrappendlenrrboolrr/) rrramnrkr"gftrs rrczSpePlugin._metadata_pre_v3s "   t}}m < UU8T "q&Qb%ain5& 3IIQ!%%4.I+7QR!quuQ~R 3OPa155D>P,4RSqAEE!TNS-*+:7AQ7*   EE+q ! q5 HHX  q5 HHY  q5 HHV + fI  *S))* *((Q/AfIAfI n   ,S++, , $ 2 21q5 9An  $An   A !:AaD     + +A} =YJRPS8sH7HH$=H)#H.c|jtjd}|jj |d|jj }d|iS)zExtract XML metadata from SPE v3 files Returns ------- dict with key `"__xml"`, whose value is the XML metadata r0r__xml)rArrr@rFr[)rrxmls rrdzSpePlugin._metadata_post_v3MsJ!!$**h7 012jjoo~rc|tur;t|jg|j|j|jdSt|j|jdS)aStandardized ndimage metadata. Parameters ---------- index : int If the index is an integer, select the index-th frame and return its properties. If index is an Ellipsis (...), return the properties of all frames in the file stacked along a new batch dimension. Returns ------- properties : ImageProperties A dataclass filled with standardized image metadata. T)shapern_imagesis_batchF)r|rr~)rTrrErDrC)rrPs r propertieszSpePlugin.propertiesZsV" H "yy/4;;/kk   T[[ eTTrrcHi}tjfd}|jD]\}}|jj |dt |dkrdn|d}tj |j|d|}|jjdk(r|tjvr ||} |j}|||<|S#t$rtjd|d Y>wxYw#t$rtj |}YQwxYw) aGet information from SPE file header Parameters ---------- spec Maps header entry name to its location, data type description and optionally number of entries. See :py:attr:`Spec.basic` and :py:attr:`Spec.metadata`. char_encoding String character encoding Returns ------- Dict mapping header entry name to its value c&|jSr)r))rrs rrz)SpePlugin._parse_header..s(?rrrxrwrrRSzFailed to decode "z3" metadata string. Check `char_encoding` parameter.)r vectorizerr@rFrorVrkindrrrrr itemrsqueeze) rrrretr)rspcntrs ` rrAzSpePlugin._parse_headerts&?@  HD" JJOOBqE "2w{!1C DJJbe3?Aww||s"t4>>'Aq A "FFHCI) * !MM,TF3CC "JJqM "s$6C?D"C=<C=D! D!)TNN).Tr0T).)rrrrrpr rrrrndarrayr[rr_rrrrcrdrrr r rAr2r3s@rr5r5s\ $'+#' NSNSNS } NS 4. NS  NS`$'#'S#'2::#'J>hrzz*> $% R(R(R( R(  R( c3h R(hDcDDcSVhDL 4S> UUoU4,CJ',8;, c3h,rr5arcg}|gd}|D]\\}}}}}}t|t|gt|t|gt|t|gd}|j|^|S)a\Convert the `ROIs` structured arrays to :py:class:`dict` Parameters ---------- a Structured array containing ROI data Returns ------- 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. )r#r&r$r'r%r()top_left bottom_rightbin)rrn) r dict_listsxsyexeygxgyroi_dicts rrmrmsI BCA"##BBBR#b'* Wc"g.GSW%  " # r)#rrloggingrGtypingrrrrrr r r r r rnumpyr core.requestrrrcore.v3_plugin_apirr getLoggerrrrrr5rrrrmrrrrs!F    ??:   8 $~~Bn!n!bmm`T#tCy.-A(Br