+ ?i}Rt^RIHt^RIt^RIt^RIHtHtHtHtH t H t H t H t H t Ht^RIt^RIt^RIHtHtHt^RIHtHt]P2!]4t!RR4t!RR 4t!R R ]4tR R ltR#)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)PluginV3ImagePropertiesc]tRt^@tRtRR9RR:RR;RR/t/RR?bR R ]P!.R@O4^ 3bR RAbR RBbR RCbRRDbRREbRRFbRRGbRRHbRRIbRRJbRRKbRRLbRRMbRRNbRROb/RRPbRRQbRRRbRRSbRRTbRRUbR RVbR!RWbR"RXbR#RYbR$RZbR%R[bR&R\bR'R]bR(R^bR)R_bR*R`bCR+RaR,RbR-RcR.RdR/ReR0RfR1RgRR/ CtR6t ^]P!]P4^]P!]P4^]P!]P4^]P!]P4^]P!]P4/t.RlOt.RmOtR,.tR7tR8#)nSpeca/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 m>j{k{ [  |lV3R?ll4t] V3R@lV3RAll4t] RIV3RBlV3RClll4tRDtVtV;t#)JSDTControlSpecaExtract 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änJanFebuMärMarAprMaiMayJunJulAugSepOktOctNovDezDecSEQUstandardSETOTOCCSLKINEr}SEAR arbitrarycRa]tRt^toRt]R3V3RlRlltV3RltRtVt R#)SDTControlSpec.CommentDescz>Describe how to extract a metadata entry from a comment stringNc Z<V^8dQhRS[RS[RS[S[.S[3,RS[S[,/#)rXnslicecvtscale)intrrstrrr float)format __classdict__s"r __annotate__'SDTControlSpec.CommentDesc.__annotate__sB    3%*%  E? rc6WnW nW0nW@nR#N)rrrr)selfrrrrs&&&&&r__init__#SDTControlSpec.CommentDesc.__init__sFJHJrcv<V^8dQh/S[;R&S[;R&S[S[.S[3,;R&S[RS[3,;R&#)rXrrrNr)rrrrrr r)rrs"rrrsK   seSj !!T5[!!r)rrrr) r~rrrrrr__annotate_func__r__classdictcell__)rs@r CommentDescrs/L 8><1 ),%)  rrsdt_major_versionsdt_minor_versionsdt_controller_name exposure_time color_codedetection_channelsbackground_subtractionc VR8H#)BrGxs&rSDTControlSpec.s18r em_activec VR8H#)ErGrs&rrrsa3hrem_gainmodulation_activec VR8H#)ArGrs&rrr sa3hr pixel_sizeg? sequence_typec*<SPV,#r)sequence_types)r __class__s&rrr s9+C+CA+Frgridn_macro delay_macron_mini delay_minin_micro delay_micro n_subpics delay_shutterdelay_prebleach bleach_time recovery_timebleach_piezo_activec VR8H#)zrGrs&rrrs 1PS8rcL<V^8dQhRS[S[,RS[S[S[3,/#)rXr:return)r rr r)rrs"rrSDTControlSpec.__annotate__"s'hsmc3hrc V^,R,R8wdR#\V^,R,4\V^,R,43# \dRu#i;i)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. :FLNCOMVER:rNN:rPN)r)r ValueError)r:s&rget_comment_version"SDTControlSpec.get_comment_version!sZ A;u  )M x{5)*C E0B,CC C M s1A AAch<V^8dQhRS[S[,RS[S[S[3,RS[S[S[3,/#)rXr:versionr)r rr rrr)rrs"rrr6s9003-0*/S/0 c3h0rc  </p\V^,^,4FpS PV^,V3,pTP4F\wrVTP YP ,TP ,4pTPeYvP,pYrT&K^ K VS P9dVRP\RS P44p \P!RV^, RV^,R R V R 24V^,V^,,p V P4VR &V# \dEK5i;i \d-p\P!RT RT 24RY%&Rp?EK;Rp?ii;i) 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 Nz-Failed to decode SDT-control metadata field `z`: z, c.V^, RV^,R 2#)rW.02rGrs&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.comment)rangecomment_fieldsKeyErroritemsrrrr Exceptionwarningswarnjoinmapstrip) r:rsdt_mdminorcmtnamespecve supported_verrrs && rparse_commentsSDTControlSpec.parse_comments5sv"71:>*E  ..wqz5/@A"iik  (&&!1$**!=>Azz-ZZ#$4L *+( )22 2 II193K3KLM MM;GAJ2SDTControlSpec.extract_metadata..s%f1ufsTFzSDT-control comments not found.Nr%r2rr=modulation_scriptzHFailed to decode SDT-control laser modulation script. Bad char_encoding?r3r$) ranyrdebugrpopupdaterdecodeUnicodeDecodeErrorrr)rr comversdt_metadtsp4rs&& rextract_metadataSDTControlSpec.extract_metadatas$..tJ/?@ 3%f%333%f% % % LL: ; ++D,%E!E+*E+rG)rsrWgư>gMbP?)rs)latin1)r~rrrrrrrrrrrr staticmethodrrrr2rr __classcell__rrs@@rrrs 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  [5Bd \ R4hi;i)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.r5rrrrrrzThe file header of z claims there are z frames, but there are actually z frames.z)SPE plugin cannot read the provided file.) superrr#io_moderwriterrrDeprecationWarning_char_encoding _sdt_metar<get_file_file _parse_headerrr_file_header_verr_dtype_shape_lenseekosSEEK_ENDtellritemsizefilenameminr) rr<r=r r/rdata_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 /GJJindex.c:<V^8dQhRS[RS[P/#rXrXr)rrndarray)rrs"rrr?s#'#'S#'2::#'rc JV\Jdh\PpVP^,VP^,,VP,pVP.VPO5pMV^8d\ RV R24hWP8d\ RV RVP R24h\PWP^,,VP^,,VP P,,pVP^,VP^,,pVPpVPPV4\P!VPVP VR7pVPV4#)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. zIndex `z` is smaller than 0.z5` exceeds the number of frames stored in this file (`z`).rcount) EllipsisrrrLrM IndexErrorrKrRrHrNrfromfilereshape)rrX read_offsetr^ out_shapedatas&$ rreadSpePlugin.reads8 H //KKKNT[[^3dii?E1T[[1I QYwug-ABC C ii % UVZV_V_U``cd  ++a.(4;;q>9DKK>hrzz*>rc BaV3Rl\SP44#)zRIterate over the frames in the file Yields ------ A Numpy array of pixel values. c3H<"TFpSPVR7xK R#5i))rXN)rf)r#irs& rr%!SpePlugin.iter..0s!=,E$)),<==rc N<V^8dQhRS[RS[RS[RS[RS[S[S[3,/#)rXrXexclude_appliedr  sdt_controlr)rr>rrr)rrs"rrr?2sLR(R(R(R( R(  R( c3h R(rc VP^8dFVPe VPpVPe VPpVPW44#VP 4#)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 )rJrErF_metadata_pre_v3_metadata_post_v3)rrXrqr rrs&&&&&rrSpePlugin.metadata2s]X  1 $"". $ 3 3 ~~)"nn ((D D%%''rcB<V^8dQhRS[RS[RS[S[S[3,/#)rXr rrr)rr>rr)rrs"rrr?s0DDcDDcSVhDrc VP\PV4pVPRR4pV^8d^MTp\ VR,RV4VR&RUu.uFqSPVR4NK upVR&RUu.uFqSPVR4NK upVR&RUu.uFqSPVR4NK upVR&RUu.uFqSPVR4NK upVR&VR,Uu.uFp\ V4NK upVR&.pVPR ^4pV^,'dVP R 4V^,'dVP R 4V^,'dVP R 4WsR &VR ,p ^T u;8:d\\P48:d&MM"\PV ^, ,VR &MRVR &VR,p ^T u;8:d\\P48:d&MM"\PV ^, ,VR&MRVR&RFp\W5,4W5&K V'd\PW14V#uupiuupiuupiuupiuupi)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. rNr chip_sizevirt_chip_size pre_pixels post_pixelsr:r;rotatereversefliprCrE)rr)rr)r>r@)r?rA)r+r-r.r0) rIrrr*roi_array_to_dictrappendlenrrr>rr2) rr rrmnrkr$gftrs &&& rrtSpePlugin._metadata_pre_v3s-"   t}}m < UU8T "q&Qb%ain5& 3II2HQ%%4.2HI+7QR7Q!uuQ~7QR 3OP3Oa55D>3OP,4RS4RqEE!TN4RS-*+:7AQ7*   EE+q ! q55 HHX  q55 HHY  q55 HHV + fI  *S))* *((Q/AfIAfI n   ,S++, , $ 2 21q5 9An  $An  A :AD     + +A =YJRPS8sI0>I5"I:I?1Jc6<V^8dQhRS[S[S[3,/#ri)rrr)rrs"rrr?Ls  4S> rc VP\PR4pVPP VR,4VPP 4pRV/#)zqExtract XML metadata from SPE v3 files Returns ------- dict with key `"__xml"`, whose value is the XML metadata r5r__xml)rIrrrHrNrf)rrxmls& rruSpePlugin._metadata_post_v3LsJ!!$**h7 012jjoo~rc&<V^8dQhRS[RS[/#rZ)rr)rrs"rrr?YsUUUoUrc V\Jd<\VP.VPO5VPVPRR7#\VPVPRR7#)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)r_rrMrLrK)rrXs&&r propertiesSpePlugin.propertiesYsV" H "yy/4;;/kk   T[[ eTTrcX<V^8dQhRS[S[S[3,RS[RS[S[S[3,/#)rXrr r)rrr rr)rrs"rrr?ss6,,CJ',8;, c3h,rc a/p\P!V3Rl4pVP4FwrVVPP V^,4\ V4^8d^MV^,p\P !VPV^,VR7pVPPR8XdV\P9d V!V4pVP4pWV&K V# \d\P!RT R24LBi;i \d\P !T4pLXi;i)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&<VPS4#r)r,)rr s&rr)SpePlugin._parse_header..s(?rr]SzFailed to decode "z3" metadata string. Check `char_encoding` parameter.)r vectorizerrHrNrrarkindrrrrritemrsqueeze) rrr retr,r spcntrs &&f rrISpePlugin._parse_headerss&?@ HD JJOOBqE "2w{!1C DJJbe3?Aww||s"t4>>'Aq A "FFHI)%* !MM,TF3CC "JJqM "s$ C.D.%DD!D=<D=)rErKrHrJrMrFrL)TNN).Tr5T).)r~rrrrrfrnrrtrurrIrrr7r8s@@rr:r:soNSNS`#'3#'#'J>>R(R(hDDL  UU4,,,rr:cV^8dQhR\PR\\\\\ ,3,,/#)rXar)rr[rrrr)rs"rrrs0T#tCy.-A(Brc .pV.RO,pVF\wr#rErgR\V4\V4.R\V4\V4.R\V4\V4./pVPV4K^ V#)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. top_left bottom_rightbin)rMrPrNrQrOrR)rr) r dict_listsxsyexeygxgyroi_dicts & rrrszI BCA"# R#b'* SWc"g. CGSW%  " #$ r) rrloggingrOtypingrrrrrrr r r r rnumpyr core.requestr rrcore.v3_plugin_apirr getLoggerr~rrrr:rrGrrrst!F    ??:   8 $~~Bn!n!bmm`r