hxSrSSKrSSKrSSKrSSKrSSKJr SSKJ r J r SSK J r SSK JrJrJrJr SS KJr SS KJr \ rS r"S S \5r"SS\5rg)a .. note:: imageio is under construction, some details with regard to the Reader and Writer classes may change. These are the main classes of imageio. They expose an interface for advanced users and plugin developers. A brief overview: * imageio.FormatManager - for keeping track of registered formats. * imageio.Format - representation of a file format reader/writer * imageio.Format.Reader - object used during the reading of a file. * imageio.Format.Writer - object used during saving a file. * imageio.Request - used to store the filename and other info. Plugins need to implement a Format class and register a format object using ``imageio.formats.add_format()``. N)Path)Arrayasarray) ImageMode) known_pluginsknown_extensions PluginConfig FileExtension)_original_order)imopencbSn[U5RR5[;a$[U5RR5nOrU[;aOgUR5[;aUR5nO>SUR5-[;aSUR5-nO[ SUS35eUb[[UVVs/sHnUR HnUPM M snnH'n[UR(dMUn [U$ [U$s snnf)zLOld Plugin resolution logic. Remove once we remove the old format manager. N.zNo format known by name `z`.)rsuffixlowerr r IndexErrorpriority is_legacy)pluginextension_namefile_extensionx plugin_names M/var/www/fran/franai/venv/lib/python3.13/site-packages/imageio/core/format.py _get_configr4s N F|  "&66f,,224 =  + + v||~ !1 1v||~-4VHB?@@!#3>"B "B#,, , "B K [)333$        s D+c\rSrSrSrSSjrSrSr\S5r \S5r \S 5r \S 5r \S 5r S rS rSrSrSrSr"SS\5r"SS\5r"SS\5rSrg)FormatTuRepresents an implementation to read/write a particular file format A format instance is responsible for 1) providing information about a format; 2) determining whether a certain file can be read/written with this format; 3) providing a reader/writer class. Generally, imageio will select the right format and use that to read/write an image. A format can also be explicitly chosen in all read/write functions. Use ``print(format)``, or ``help(format_name)`` to see its documentation. To implement a specific format, one should create a subclass of Format and the Format.Reader and Format.Writer classes. See :class:`imageio.plugins` for details. Parameters ---------- name : str A short name of this format. Users can select a format using its name. description : str A one-line description of the format. extensions : str | list | None List of filename extensions that this format supports. If a string is passed it should be space or comma separated. The extensions are used in the documentation and to allow users to select a format by file extension. It is not used to determine what format to use for reading/saving a file. modes : str A string containing the modes that this format can handle ('iIvV'), “i” for an image, “I” for multiple images, “v” for a volume, “V” for multiple volumes. This attribute is used in the documentation and to select the formats when reading/saving a file. Nc XUR5UlX lUc/nO6[U[5(a!UR SS5R S5n[U[[45(aJ[UVs/sH-oU(dM SURS5R5-PM/ sn5Ul O [S5eU=(d SUl [UR[5(d [S5eURHnUS;dM [S 5e gs snf) uDInitialize the Plugin. Parameters ---------- name : str A short name of this format. Users can select a format using its name. description : str A one-line description of the format. extensions : str | list | None List of filename extensions that this format supports. If a string is passed it should be space or comma separated. The extensions are used in the documentation and to allow users to select a format by file extension. It is not used to determine what format to use for reading/saving a file. modes : str A string containing the modes that this format can handle ('iIvV'), “i” for an image, “I” for multiple images, “v” for a volume, “V” for multiple volumes. This attribute is used in the documentation and to select the formats when reading/saving a file. N, rz#Invalid value for extensions given.zInvalid value for modes given.ziIvV?zInvalid value for mode given.)upper_name _description isinstancestrreplacesplittupleliststripr _extensions ValueError_modes)selfname description extensionsmodesems r__init__Format.__init__xs0ZZ\ '  J  C ( (#++C5;;C@J j5$- 0 0$5?EZ1+qwws|))++ZE D BC Ckr $++s++=> >A !@AAFs < D' &D'c@SUR<SUR<S3$)Nz)r2r3r1s r__repr__Format.__repr__s%)YY0@0@AAcUR$N)docr=s r__str__Format.__str__s xxr@cvUR<SUR<SURR5<S3$)zCThe documentation for this format (name + description + docstring).r;z  )r2r3__doc__r-r=s rrC Format.docs. II    LL     r@cUR$)zThe name of this format.)r%r=s rr2 Format.nameszzr@cUR$)z#A short description of this format.)r&r=s rr3Format.descriptions   r@cUR$)z`A list of file extensions supported by this plugin. These are all lowercase with a leading dot. )r.r=s rr4Format.extensionss r@cUR$)z:A string specifying the modes that this format can handle.)r0r=s rr5 Format.modess{{r@cURSS;aURSOSnX R;a0[SURSURRS35eUR X5$)zget_reader(request) Return a reader object that can be used to read data and info from the given file. Users are encouraged to use imageio.get_reader() instead. riIvVr#Format z cannot read in  mode)moder5 RuntimeErrorr2 image_modeReaderr1request select_modes r get_readerFormat.get_readersl*1aF)Bgll1o jj ($))$4W\\5L5L4MUS {{4))r@cURSS;aURSOSnX R;a0[SURSURRS35eUR X5$)zget_writer(request) Return a writer object that can be used to write data and info to the given file. Users are encouraged to use imageio.get_writer() instead. rrSr#rTz cannot write in rU)rVr5rWr2rXWriterrZs r get_writerFormat.get_writersl*1aF)Bgll1o jj ($))$5gll6M6M5NeT {{4))r@c$URU5$)zQcan_read(request) Get whether this format can read data from the specified uri. ) _can_readr1r[s rcan_readFormat.can_reads ~~g&&r@c$URU5$)zQcan_write(request) Get whether this format can write data to the speciefed uri. ) _can_writeres r can_writeFormat.can_writes w''r@cg)aCheck if Plugin can read from ImageResource. This method is called when the format manager is searching for a format to read a certain image. Return True if this format can do it. The format manager is aware of the extensions and the modes that each format can handle. It will first ask all formats that *seem* to be able to read it whether they can. If none can, it will ask the remaining formats if they can: the extension might be missing, and this allows formats to provide functionality for certain extensions, while giving preference to other plugins. If a format says it can, it should live up to it. The format would ideally check the request.firstbytes and look for a header of some kind. Parameters ---------- request : Request A request that can be used to access the ImageResource and obtain metadata about it. Returns ------- can_read : bool True if the plugin can read from the ImageResource, False otherwise. Nres rrdFormat._can_reads8r@cg)aCheck if Plugin can write to ImageResource. Parameters ---------- request : Request A request that can be used to access the ImageResource and obtain metadata about it. Returns ------- can_read : bool True if the plugin can write to the ImageResource, False otherwise. Nrmres rriFormat._can_writesr@c|\rSrSrSrSr\S5r\S5rSr Sr Sr S r \S 5r SS jrS rSrSrg )Format._BaseReaderWriteri,zBase class for the Reader and Writer class to implement common functionality. It implements a similar approach for opening/closing and context management as Python's file objects. cSUlSUlXlX lUR"S0UR R R5D6 g)NFrm)_BaseReaderWriter__closed_BaseReaderWriter_last_index_format_request_openr[kwargscopy)r1formatr[s rr8!Format._BaseReaderWriter.__init__2s=!DM02D -!L#M JJ 4,,113 4r@cUR$)zOThe :class:`.Format` object corresponding to the current read/write operation. )rwr=s rr|Format._BaseReaderWriter.format:s << r@cUR$)zPThe :class:`.Request` object corresponding to the current read/write operation. )rxr=s rr[ Format._BaseReaderWriter.requestAs == r@c&UR5 U$rB) _checkClosedr=s r __enter__"Format._BaseReaderWriter.__enter__Hs    Kr@c,UcUR5 ggrB)close)r1typevalue tracebacks r__exit__!Format._BaseReaderWriter.__exit__Ls} r@cFUR5 g![a gf=frB)r Exceptionr=s r__del__ Format._BaseReaderWriter.__del__Qs"    s   cUR(agSUlUR5 URR5 g)zVFlush and close the reader/writer. This method has no effect if it is already closed. NT)ru_closer[finishr=s rrFormat._BaseReaderWriter.closeWs.}} DM KKM LL   !r@cUR$)z$Whether the reader/writer is closed.)rur=s rclosedFormat._BaseReaderWriter.closedbs== r@NcUR(a/URRnU=(d SU-n[U5eg)z8Internal: raise an ValueError if reader/writer is closedzI/O operation on closed %s.N)r __class____name__rW)r1msgwhats rr%Format._BaseReaderWriter._checkClosedgs8{{~~..C;dB"3''r@c [5e)z_open(**kwargs) Plugins should probably implement this. It is called when reader/writer is created. Here the plugin can do its initialization. The given keyword arguments are those that were given by the user at imageio.read() or imageio.write(). NotImplementedErrorr1rzs rryFormat._BaseReaderWriter._openps &' 'r@c[5e)z_close() Plugins should probably implement this. It is called when the reader/writer is closed. Here the plugin can do a cleanup, flush, etc. rr=s rrFormat._BaseReaderWriter._close| &' 'r@)rv__closedrwrxrB)r __module__ __qualname____firstlineno__rHr8propertyr|r[rrrrrrryr__static_attributes__rmr@r_BaseReaderWriterrr,sk  5     !  !      "  !  ! ( ( (r@rc^\rSrSrSrSrSrSrSrSSjr S r S r S r S r S rSrSrg) Format.Readeria The purpose of a reader object is to read data from an image resource, and should be obtained by calling :func:`.get_reader`. A reader can be used as an iterator to read multiple images, and (if the format permits) only reads data from the file when new data is requested (i.e. streaming). A reader can also be used as a context manager so that it is automatically closed. Plugins implement Reader's for different formats. Though rare, plugins may provide additional functionality (beyond what is provided by the base reader class). c"UR5$)a%get_length() Get the number of images in the file. (Note: you can also use ``len(reader_object)``.) The result can be: * 0 for files that only have meta data * 1 for singleton images (e.g. in PNG, JPEG, etc.) * N for image series * inf for streams (series of unknown length) ) _get_lengthr=s r get_lengthFormat.Reader.get_lengths##% %r@c UR5 XlUR"U40UD6up4[ X45$![a [ U5ef=f)a/get_data(index, **kwargs) Read image data from the file, using the image index. The returned image has a 'meta' attribute with the meta data. Raises IndexError if the index is out of range. Some formats may support additional keyword arguments. These are listed in the documentation of those formats. )rrv _get_data StopIterationrr)r1indexrzimmetas rget_dataFormat.Reader.get_datasX    05 - (>>%:6:? "! ( '' (s 8Ac BUR"URS-40UD6$)zget_next_data(**kwargs) Read the next image from the series. Some formats may support additional keyword arguments. These are listed in the documentation of those formats. r)rrvrs r get_next_dataFormat.Reader.get_next_datas#==!B!BQ!FQ&Q Qr@c UR5 UR5n[[US- S5U5Ulg)zset_image_index(index) Set the internal pointer such that the next call to get_next_data() returns the image specified by the index rrtN)rrminmaxrv)r1rrzns rset_image_indexFormat.Reader.set_image_indexs6    !A03C 24F0JD -r@NcUR5 URU5n[U[5(d"[ SUR R -5eU$)aget_meta_data(index=None) Read meta data from the file. using the image index. If the index is omitted or None, return the file's (global) meta data. Note that ``get_data`` also provides the meta data for the returned image as an attribute of that image. The meta data is a dict, which shape depends on the format. E.g. for JPEG, the dict maps group names to subdicts and each group is a dict with name-value pairs. The groups represent the different metadata formats (EXIF, XMP, etc.). z Meta data must be a dict, not %r)r_get_meta_datar'dictr/rr)r1rrs r get_meta_dataFormat.Reader.get_meta_datasS    &&u-DdD)) 69P9PPKr@c# # UR5 UR5nSnX!:a.URU5up4[ X45v US- nX!:aM-gg![a g[a U[ S5:Xagef=f7f)zjiter_data() Iterate over all images in the series. (Note: you can also iterate over the reader object.) rNinfr)rrrrrfloatr)r1rirrs r iter_dataFormat.Reader.iter_datas    !AA%#~~a0HBBo%Q%%!E%L(s9(BABB B#B%B=B?BBc"UR5$rB)rr=s r__iter__Format.Reader.__iter__s>># #r@cdUR5nU[S5:Xa[RnU$)Nr)rrsysmaxsize)r1rs r__len__Format.Reader.__len__s(!AE%L KKHr@c[5e)z_get_length() Plugins must implement this. The returned scalar specifies the number of images in the series. See Reader.get_length for more information. rr=s rrFormat.Reader._get_length &' 'r@c[5e)z_get_data() Plugins must implement this, but may raise an IndexError in case the plugin does not support random access. It should return the image and meta data: (ndarray, dict). rr1rs rrFormat.Reader._get_datarr@c[5e)z_get_meta_data(index) Plugins must implement this. It should return the meta data as a dict, corresponding to the given index, or to the file's (global) meta data if index is None. rrs rrFormat.Reader._get_meta_datarr@)rvrB)rrrrrHrrrrrrrrrrrrrmr@rrYrs@  & #$ R K , 0 $  ( ( (r@rYc4\rSrSrSrS SjrSrSrSrSr g) Format.Writeri&a The purpose of a writer object is to write data to an image resource, and should be obtained by calling :func:`.get_writer`. A writer will (if the format permits) write data to the file as soon as new data is provided (i.e. streaming). A writer can also be used as a context manager so that it is automatically closed. Plugins implement Writer's for different formats. Though rare, plugins may provide additional functionality (beyond what is provided by the base writer class). NcUR5 [U[R5(d [ S5e0n[ US5(a:[UR [5(aURUR 5 UcO1[U[5(d [ S5eURU5 [U5nURX5$)zappend_data(im, meta={}) Append an image (and meta data) to the file. The final meta data that is used consists of the meta data on the given image (if applicable), updated with the given meta data. z)append_data requires ndarray as first argrMeta must be a dict.) rr'npndarrayr/hasattrrrupdater _append_data)r1rr total_metas r append_dataFormat.Writer.append_data5s    b"**-- !LMMJr6""z"''4'@'@!!"''*|d++ !788!!$'B$$R4 4r@cUR5 [U[5(d [S5eUR U5$)aset_meta_data(meta) Sets the file's (global) meta data. The meta data is a dict which shape depends on the format. E.g. for JPEG the dict maps group names to subdicts, and each group is a dict with name-value pairs. The groups represents the different metadata formats (EXIF, XMP, etc.). Note that some meta formats may not be supported for writing, and individual fields may be ignored without warning if they are invalid. r)rr'rr/_set_meta_datar1rs r set_meta_dataFormat.Writer.set_meta_dataPs:    dD)) !788**400r@c[5erBr)r1rrs rrFormat.Writer._append_datae %' 'r@c[5erBrrs rrFormat.Writer._set_meta_datairr@rmrB) rrrrrHrrrrrrmr@rr`r&s  56 1* ( (r@r`)r&r.r0r%)NN)rrrrrHr8r>rDrrCr2r3r4r5r]rarfrjrdriobjectrrYr`rrmr@rrrTs!F/BbB  !!   * *'(<&Y(FY(zY("Y(zE("E(r@rcn\rSrSrSr\S5rSrSrSr Sr Sr S r SS jr S rS rS rSrSrg) FormatManagerinz The FormatManager is a singleton plugin factory. The format manager supports getting a format object using indexing (by format name or extension). When used as an iterator, this object yields all registered format objects. See also :func:`.help`. c[5n[R"5HUn[R"[ 5 UR (aURbURU5 SSS5 MW U$!,(df  Mj=frB) r,r values contextlibsuppress ImportErrorrr|append)r1available_formatsconfigs r_formatsFormatManager._formatsysd F#**,F$$[1## (A%,,V421- ! 21s 0A;; B c4S[UR5S3$)Nzlenrr=s rr>FormatManager.__repr__s-c$--.@-AAUVVr@c:[SUR55$)Nc38# UHoRv M g7frB)r|).0rs r )FormatManager.__iter__..s4mHHms)iterrr=s rrFormatManager.__iter__s4dmm444r@c,[UR5$rBrr=s rrFormatManager.__len__s4==!!r@c/nURHGnURSnURSnURSUSUS3nURU5 MI SR U5$)Nr4r3r;z []rG)r legacy_argsr2rjoin)r1ssrextdescss rrDFormatManager.__str__sl mmF$$\2C%%m4D;;-s4&3%q1A IIaL $ yy}r@c[R"S[SS9 [U[5(d [ S5eUS:Xa [ S5e[ U5R5(a[USSS 9R$[UR55nUR$![ a N2f=f![a' [S URS URS 35ef=f) NzjThe usage of `FormatManager` is deprecated and it will be removed in Imageio v3. Use `iio.imopen` instead.r stacklevelz;Looking up a format should be done by name or by extension.r#z#No format matches the empty string.rT legacy_modezThe `z4` format is not installed. Use `pip install imageio[z]` to install it.)warningswarnDeprecationWarningr'r(r/ris_filerrwrr$r|rr2 install_name)r1r2rs r __getitem__FormatManager.__getitem__s  ?   $$$M  2:BC C :     dCT:BBB TZZ\* ==     }%,,2,?,?+@@QS  s+B& B6& B32B361C'c^[R"S[SS9 UHHm[T[5(d [ S5e[ U4SjS55(dM?[S5e [U5S:HnU(a[nUVs/sH(o3S :wdM UR5R5PM* nn[R"5VVs/sH oUHofPM M nnnUHnU(aUR5 M[U5HumUR V s/sHoPM sn HRn U R#T5(dMUR$R'U 5 UR$R)SU 5 MT Mw M [*R,"5n [*R."5 UH#mU R1TS 5n U cMU [*T'M% [*R2"U 5 g s snfs snnfs sn f) asort(name1, name2, name3, ...) Sort the formats based on zero or more given names; a format with a name that matches one of the given names will take precedence over other formats. A match means an equal name, or ending with that name (though the former counts higher). Case insensitive. Format preference will match the order of the given names: using ``sort('TIFF', '-FI', '-PIL')`` would prefer the FreeImage formats over the Pillow formats, but prefer TIFF even more. Each time this is called, the starting point is the default format order, and calling ``sort()`` with no arguments will reset the order. Be aware that using the function can affect the behavior of other code that makes use of imageio. Also see the ``IMAGEIO_FORMAT_ORDER`` environment variable. a6`FormatManager` is deprecated and it will be removed in ImageIO v3. Migrating `FormatManager.sort` depends on your use-case: - modify `iio.config.known_plugins` to specify the search order for unrecognized formats. - modify `iio.config.known_extensions[].priority` to control a specific extension.rrz)formats.sort() accepts only string names.c3,># UH oT;v M g7frBrm)rcr2s rr %FormatManager.sort..s+d9dsz.,zHNames given to formats.sort() should not contain dots `.` or commas `,`.rr#N)rrr r'r( TypeErroranyr/rr r-r$r rresetreverseddefault_priorityendswithrremoveinsertr r{clearpopr) r1names should_resetr2 sane_namesext_listrflat_extensions extensionrr old_orders ` rsortFormatManager.sorts(   0  DdC(( KLL+d+++ 6 5zQ #E7<Kut *djjl((*u K!1 7 7 9 9HXcCXC 9  )I! ,*3*D*DE*DQq*DEFt,,!**11&9!**11!V<F- )"&&( D]]4.F!&, d# Y'3L Fs G9"G9G># Hc [R"S[SS9 [U[5(d [ S5eU(d7UR UR5;a[ SUR S35e[UR R5URRURRSSUR URS RUR5UR S .S 9nU["UR 'URHVn[%UUR /S S UR S3S9n[&R("U[+55R-U5 MX g)zadd_format(format, overwrite=False) Register a format, so that imageio can use it. If a format with the same name already exists, an error is raised, unless overwrite is True, in which case the current format is replaced. z`FormatManager` is deprecated and it will be removed in ImageIO v3.To migrate `FormatManager.add_format` add the plugin directly to `iio.config.known_plugins`.rrz/add_format needs argument to be a Format objectzA Format named z8 is already registered, use `overwrite=True` to replace.Tunknownr")r2r3r4r5)r2 class_name module_namerr"rz Unique Formatz7A format inserted at runtime. It is being read by the `z ` plugin.)r8rr2r3N)rrr r'rr/r2get_format_namesr r$rrrr3rr4r5r r r setdefaultr,r)r1 iio_format overwriterr8rs r add_formatFormatManager.add_formatsP   *   *f--NO Oz$2G2G2II!*//!2300  &&(!++44",,77"")55!hhz'<'<=#))   &, fkk"#..I# ++$--3[[MD C  ' ' 46 : A A# F/r@c[XRRSS9R$![a [ R "S[SS9 g[a gf=f)zsearch_read_format(request) Search a format that can read a file according to the given request. Returns None if no appropriate format was found. (used internally) TrzrImageIO now uses a v3 plugin when reading this format. Please migrate to the v3 API (preferred) or use imageio.v2.rrN rrVio_moderwAttributeErrorrrr r/res rsearch_read_format FormatManager.search_read_format5] '<<#7#7TJRR R  MMO"     '*$A AAc[XRRSS9R$![a [ R "S[SS9 g[a gf=f)zsearch_write_format(request) Search a format that can write a file according to the given request. Returns None if no appropriate format was found. (used internally) TrzrImageIO now uses a v3 plugin when writing this format. Please migrate to the v3 API (preferred) or use imageio.v2.rrNrGres rsearch_write_format!FormatManager.search_write_formatLrLrMc[R"S[SS9 URVs/sHoRPM sn$s snf)z(Get the names of all registered formats.z`FormatManager` is deprecated and it will be removed in ImageIO v3.To migrate `FormatManager.get_format_names` use `iio.config.known_plugins.keys()` instead.rr)rrr rr2)r1fs rr@FormatManager.get_format_namescs<   i   !% . 1 ...sAc[U5 g)z1Show a nicely formatted list of available formatsN)printr=s rshowFormatManager.showos  d r@rmN)F)rrrrrHrrr>rrrDr#r:rDrJrOr@rVrrmr@rrrnsX ! !W5"!FF(P1Gf.. /r@r)rHrrrnumpyrpathlibrr#rrr[rrr r r r config.pluginsr r MODENAMESrrrrrmr@rr\sW8 QQ,  !@W(VW(tCFCr@