9i}&SrSSKJr SSKrSSKrSSKJrJrJrJrJ r J r J r J r J r Jr SSKrSSKrSSKJrJrJr SSKJrJr \R2"\5r"SS 5r"S S 5r"S S \5rS\R>S\ \\ \ \!44Sjr"g)aRead 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)PluginV3ImagePropertiescv\rSrSrSrSSSSSSS .r0S S _S S \R"/SQ5S4_SS_SS_SS_SS_SS_SS_SS_SS_S S!_S"S#_S$S%_S&S'_S(S)_S*S+_S,S-_0S.S/_S0S1_S2S3_S4S5_S6S7_S8S9_S:S;_SS?_S@SA_SBSC_SDSE_SFSG_SHSI_SJSK_SLSM_SNSO_ESPSQSRSSSTSUSVSSWSXSYSZSS[. ErS\r \R"\R5\R"\R5\R"\R5\R"\R5\R"\R5S].r/S^Qr/S_QrS`/rSargb)cSpecAa/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(" 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 88BJJ  88BHH  88BHH  88BII  88BII  F K"AM Irrc^\rSrSrSr0SS_SS_SS_SS _S S _S S _S S_SS_SS_SS_SS_SS_SS_SS_SS_SS_SS_rS S!S"S#S$.r"S%S&5r0S'\"S \"S(S)5\ 5_S*\"S \"S)S+5\ 5_S,\"S \"S-S5\ 5_S.\"S\"S/S05\ S15_S2\"S \"SS35\ 5_S4\"S \"S5S65\ 5_S7\"S S3S85_S9\"S S:S;5_S<\"S \"S=S:5\ 5_S>\"S S?S@5_SA\"S \"SBS=5\ SC5_SD\"S \"SS5U4SEj5_SF\"S \"S6SB5\ S15_SG\"S\"S-S 5\ 5_SH\"S\"SSI5\ SJ5_SK\"S\"S S5\ 5_SL\"S\"SIS=5\ S15_\"S\"SS5\ 5\"S\"S=SM5\ S15\"S\"SS5\ 5\"S\"S0SN5\ S15\"S\"SMSO5\ S15\"S\"SOSP5\ S15\"S\"SPS/5\ S15SQ.ESR\"S \"SSST5SU50SV.r \ SW\\ SX\\ \ 44SYj5r\ SW\\ SZ\\ \ 4SX\\ \44U4S[jj5r\ S\\ S]\ SX\\S^44U4S_jj5r\ SdS`\Sa\ 4U4Sbjjj5rScrU=r$)eSDTControlSpecr`aExtract metadata written by the SDT-control software Some of it is encoded in the comment strings (see :py:meth:`parse_comments`). Also, date and time are encoded in a peculiar way (see :py:meth:`get_datetime`). Use :py:meth:`extract_metadata` to update the metadata dict. uJänrxJanFebruMärryMarAprr6MairgMayJunr,JulAugr8Sep Oktr*OctNov Dez DecstandardTOCCSLr arbitrary)SEQUSETOKINESEARc \rSrSr%Sr\\S'\\S'\\ /\ 4\S'\ S\ 4\S'\ S4S\S\S\\ /\ 4S\ \ 4SjjrS rg) SDTControlSpec.CommentDescz>Describe how to extract a metadata entry from a comment stringnslicecvtNscalec4XlX lX0lX@lgN)rrrr)selfrrrrs r__init__#SDTControlSpec.CommentDesc.__init__sFJHJr)rrrr)rrrrrint__annotations__rrstrrr floatr rrrrr CommentDescrsL 7 > seSj !!<T5[!!1 ),%)   3%*%  E?  rrsdt_major_versionrSDsdt_minor_versionFsdt_controller_namer exposure_timerQIgư> color_coder0detection_channelsr2background_subtractionc US:H$)NBrxs rSDTControlSpec.s18r em_active c US:H$)NErrs rrr sa3hrem_gainmodulation_active!c US:H$)NArrs rrr sa3hr pixel_sizeg? sequence_typec">TRU$r)sequence_types)r __class__s rrrs9+C+CA+Frgridn_macro delay_macrogMbP?n_mini delay_mini%OrC7)n_micro delay_micro n_subpics delay_shutterdelay_prebleach bleach_time recovery_timebleach_piezo_active"#c US:H$)Nzrrs rrrs 1PS8r))rgr)rgrxrereturncUSSSS:wag[USSS5[USSS54$![a gf=f)zGet 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. r6rLCOMVER)rNP)r ValueError)res rget_comment_version"SDTControlSpec.get_comment_version"s\ A;r"  ) x{2b)*C Br0B,CC C  s !1 >>versionc >0n[USS-5H{nT RUSU4nUR5HOupVUR XR UR 5nURbXvR-nXrU'MQ M} UT R;aMSR[ST R55n [R"SUSS USS S U S 35 USUS -n U R5US'U$![a GM f=f![a,n[R"SUSU35 SX%'SnAGMSnAff=f)zExtract 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 rxrNz-Failed to decode SDT-control metadata field `z`: z, cUSSUSS3$)Nr.rx02rrs rr/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) rersdt_mdminorcmtnamespecve supported_verr rs rparse_commentsSDTControlSpec.parse_comments6sv"71:>*E  ..wqz5/@A"iik  (&&!1$**!=>Azz-ZZ#$4L *+( )22 2 II193K3KLM MM;GAJTRUSSn[[USS5U[USS5[USS5[USS5[USS55$![a#n[R SUS35 S nAg S nAff=f) aTurn date and time saved by SDT-control into proper datetime object Parameters ---------- date SPE file date, typically ``metadata["date"]``. time SPE file date, typically ``metadata["time_local"]``. Returns ------- File's datetime if parsing was succsessful, else None. rrgrrr6r,z1Failed to decode date from SDT-control metadata: rN)monthsrrrloggerinfo)r:rmonthrrs r get_datetimeSDTControlSpec.get_datetimeis R$$T!AY/ED1ID1ID1ID1ID1I   R KKKA3aP Q Q RsAA!! B+B  Bmeta char_encodingcf>TRUS5n[SU55(a[RS5 gTR USU5nUR S5 UR U5 TRUSUS5nU(a&X@S'UR S5 UR S5 USnURU5US 'UR S5 UR S 5 UR S 5 g![a [R"S 5 NEf=f) a*Extract SDT-control metadata from SPE metadata SDT-control stores some metadata in comments and other fields. Extract them and remove unused entries. Parameters ---------- meta SPE file metadata. Modified in place. char_encoding Character encoding used to decode strings in the metadata. rec3*# UH oS:v M g7f)rNr).0cs r 2SDTControlSpec.extract_metadata..s%f1ufszSDT-control comments not found.Nr:rTrrnmodulation_scriptzHFailed to decode SDT-control laser modulation script. Bad char_encoding?rWr9) ranyr"debugrpopupdater%decodeUnicodeDecodeErrorrr)r'r(comversdt_metadtsp4rs rextract_metadataSDTControlSpec.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[TU]U5 URR[R :Xa [ S5eUb[R"S[5 X0l Ub[R"S[5 X@l URR5UlUR[ R"S5nUSUl[ R&USUlUSUS 4UlUS UlU(GaUSS :aUS nODURR/S [0R25 URR55nU[ R6- nXpR*S UR*S-UR(R8--nXpR,:waX[R"SURR:SUR,SUS35 [=XpR,5UlURR/[ R65 g![>a [ S5ef=f)aiInstantiate 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.r<r!rrrr ryrrrxzThe file header of z claims there are z frames, but there are actually z frames.z)SPE plugin cannot read the provided file.) superrr7io_moderwriterrrDeprecationWarning_char_encoding _sdt_metarBget_file_file _parse_headerrr_file_header_verr_dtype_shape_lenseekosSEEK_ENDtellritemsizefilenameminr) rrBrCr(r7r#data_endliners rrSpePlugin.__init__s4 ! <<  6<< /%&>? ?  $ MM#   ,   MM#   "\\**,  S%%djj(;D$():$;D !++d:&67DK<f6DK[)DI )*a/#$78HJJOOAr{{3#zz0H$//1Q$++a.84;;;O;OOO99$MM-dll.C.C-DDV99+%EdV8U!$D)) 4DI JJOODOO , S%&QR R Ss ,FII.indexr]cU[LaW[RnURSURS-UR-nUR/URQ7nOUS:a[ SUS35eXR:a[ SUSURS35e[RXRS-URS-UR R--nURSURS-nURnURRU5 [R"URUR US9nURU5$)zRead 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. rrxzIndex `z` is smaller than 0.z5` exceeds the number of frames stored in this file (`z`).rcount) EllipsisrrrPrQ IndexErrorrOrVrLrRrfromfilereshape)rr] read_offsetr` out_shapedatas rreadSpePlugin.reads8 H //KKKNT[[^3dii?E1T[[1I QYwug-ABC C ii % UVZV_V_U``cd  ++a.(4;;q>9DKK# UHnTRUS9v M g7f)r\N)rh)r+irs rr-!SpePlugin.iter..1s=,E$)),<==rexclude_applied sdt_controlcURS:aCURb URnURb URnURX45$UR 5$)uqSPE 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 ry)rNrIrJ_metadata_pre_v3_metadata_post_v3)rr]rpr(rqs rrSpePlugin.metadata3s]X  1 $"". $ 3 3 ~~)"nn ((D D%%''rcUR[RU5nURSS5nUS:aSOUn[ USSU5US'SVs/sHoSRUS5PM snUS'SVs/sHoSRUS5PM snUS'S Vs/sHoSRUS5PM snUS 'S Vs/sHoSRUS5PM snUS 'US Vs/sHn[ U5PM snUS '/nURSS5nUS-(aUR S5 US-(aUR S5 US-(aUR S5 XsS'USn SU s=::a[[R5::aO O[RU S- US'OSUS'USn SU s=::a[[R5::aO O[RU S- US'OSUS'SHn[X55X5'M U(a[RX15 U$s snfs snfs snfs snfs snf)aExtract 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"Nrxr#)r+r- chip_size)r/r1virt_chip_size)rorq pre_pixels)rprr post_pixelsrerhrrotaterreverser6fliprtrv)rFrJrLrP) rMrrr2roi_array_to_dictrappendlenrrboolrr:) rr(rqmnrkr,gftrs rrsSpePlugin._metadata_pre_v3s'"   t}}m < UU8T "q&Qb%ain5& 3II2HQ%%4.2HI+7QR7Q!uuQ~7QR 3OP3Oa55D>3OP,4RS4RqEE!TN4RS-*+:7AQ7*   EE+q ! q5 HHX  q5 HHY  q5 HHV + fI  *S))* *((Q/AfIAfI n   ,S++, , $ 2 21q5 9An  $An  A :AD     + +A =YJRPS8sH<:III ,IcUR[RS5nURR US5 URR 5nSU0$)zqExtract XML metadata from SPE v3 files Returns ------- dict with key `"__xml"`, whose value is the XML metadata r<r__xml)rMrrrLrRrh)rr#xmls rrtSpePlugin._metadata_post_v3MsJ!!$**h7 012jjoo~rcU[La8[UR/URQ7URURSS9$[URURSS9$)a~Standardized 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)rrr)rarrQrPrO)rr]s r propertiesSpePlugin.propertiesZsV" H "yy/4;;/kk   T[[ eTTrrcX^0n[R"U4Sj5nUR5HupVURR US5 [ U5S:aSOUSn[R "URUSUS9nURRS:XaU[R;a U"U5nUR5nXU'M U$![a [R"SUS 35 NAf=f![a [R "U5nNVf=f) aNGet 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&>URT5$r)r4)rr(s rr)SpePlugin._parse_header..s(?rrryrxrr_SzFailed to decode "z3" metadata string. Check `char_encoding` parameter.)r vectorizerrLrRrrcrkindrrrrritemrsqueeze) rrr(retr4rspcntrs ` rrMSpePlugin._parse_headerts&?@ HD JJOOBqE "2w{!1C DJJbe3?Aww||s"t4>>'Aq A "FFHI)%* !MM,TF3CC "JJqM "s$9CD$DD D)(D))rIrOrLrNrQrJrP)TNN).Tr<T).)rrrrrrr rrrrndarrayrhrrnrrrrsrtrrr r rMrr>r?s@rrArAsh $'+#' NSNSNS } NS 4. NS  NSNS`$'#'S#'2::#'J>hrzz*> $% R(R(R( R(  R( c3h R(hDcDDcSVhDL 4S> UUoU4,CJ',8;, c3h,,rrAarc/nU/SQnUHZup#pEpg[U5[U5/[U5[U5/[U5[U5/S.nURU5 M\ U$)a4Convert 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)rr) r dict_listsxsyexeygxgyroi_dicts rr~r~stI BCA"#R#b'* Wc"g.GSW%  " #$ r)#rrloggingrStypingrrrrrr r r r r rnumpyr core.requestrrrcore.v3_plugin_apirr getLoggerrr"rrrArrrr~rrrrs!F    ??:   8 $~~Bn!n!bmm`T#tCy.-A(Br