tifffile
v2024.9.20
Tifffile 是一個 Python 函式庫
影像和元資料可以從TIFF、BigTIFF、OME-TIFF、GeoTIFF、Adobe DNG、ZIF（可縮放影像檔案格式）、MetaMorph STK、Zeiss LSM、ImageJ hyperstack、Micro-Manager MMStack 和NDTiff、SGI、NIHImageView、Olympus Fluo讀取SIS、ScanImage、Molecular Dynamics GEL、Aperio SVS、Leica SCN、Roche BIF、PerkinElmer QPTIFF（QPI、PKI）、Hamamatsu NDPI、Argos AVS 和 Philips DP 格式的文件。
影像資料可以從條帶、圖塊、頁面 (IFD)、SubIFD、高階系列和金字塔層級讀取為 NumPy 陣列或 Zarr 陣列/群組。
影像資料可以以多頁、體積、金字塔、記憶體可映射、平鋪、預測或壓縮形式寫入 TIFF、BigTIFF、OME-TIFF 和 ImageJ hyperstack 相容檔案。
imagecodecs 函式庫支援許多壓縮和預測方案，包括 LZW、PackBits、Deflate、PIXTIFF、LZMA、LERC、Zstd、JPEG（8 和 12 位元，無損）、JPEG 2000、JPEG XR、JPEG XL、WebP、PNG 、EER、Jet 、24 位浮點和水平差分。
Tifffile 也可用於檢查 TIFF 結構、從多維檔案序列讀取影像資料、為 TIFF 檔案和映像檔序列編寫 fsspec ReferenceFileSystem、修補 TIFF 標記值以及解析許多專有元資料格式。
| 作者： | 克里斯托夫·戈爾克 |
|---|---|
| 執照： | BSD 3 條款 |
| 版本： | 2024年9月20日 |
| 數字編號： | 10.5281/澤諾多.6795860 |
從 Python 套件索引安裝 tifffile 套件和所有依賴項：
python -m pip install -U tifffile[全部]
Tifffile 也可在其他軟體包儲存庫中使用，例如 Anaconda、Debian 和 MSYS2。
tifffile 庫透過文件字串進行類型註解和記錄：
python -c“導入 tifffile；幫助（tifffile）”
Tifffile 可以用作控制台腳本來檢查和預覽 TIFF 檔案：
python -m tifffile --幫助
請參閱使用程式設計介面的範例。
原始碼和支援可在 GitHub 上取得。
image.sc 論壇上也提供支援。
此版本已根據以下要求和依賴項進行了測試（其他版本也可能有效）：
2024年9月20日
2024年8月30日
2024年8月28日
2024年8月24日
2024年8月10日
2024年7月24日
2024年7月21日
2024年7月2日
2024年6月18日
2024年5月22日
2024年5月10日
2024年5月3日
2024年4月24日
2024年4月18日
2024年2月12日
2024年1月30日
2023年12月9日
2023年9月26日
2023年9月18日
2023年8月30日
2023年8月25日
2023年8月12日
2023年7月18日
請參閱 CHANGES 檔案以了解舊版本。
TIFF（標記影像檔案格式）由 Aldus Corporation 和 Adobe Systems Incorporated 創建。
Tifffile 支援 TIFF6 規範的子集，主要是 8、16、32 和 64 位元整數、16、32 和 64 位元浮點、灰階和多樣本影像。具體來說，未實現 CCITT 和 OJPEG 壓縮、無 JPEG 壓縮的色度子取樣、色彩空間轉換、不同類型的樣本或 IPTC、ICC 和 XMP 元資料。
除了經典 TIFF 之外，tifffile 還支援多種不嚴格遵守 TIFF6 規範的類別 TIFF 格式。某些格式允許檔案和資料大小超過經典 TIFF 的 4 GB 限制：
其他用於從Python 讀取、寫入、檢查或操作科學TIFF 檔案的其他函式庫包括aicsimageio、apeer-ometiff-library、bigtiff、fabio.TiffIO、GDAL、imread、large_image、openslide-python、opentile、pylibtiff、pylsm、 pymimage、python -bioformats、pytiff、scanimagetiffreader-python、SimpleITK、slideio、tiffslide、tifftools、tyf、xtiff 和 ndtiff。
將 NumPy 陣列寫入單頁 RGB TIFF 檔案：
>> > data = numpy . random . randint ( 0 , 255 , ( 256 , 256 , 3 ), 'uint8' )
>> > imwrite ( 'temp.tif' , data , photometric = 'rgb' )從 TIFF 檔案中讀取影像作為 NumPy 陣列：
>> > image = imread ( 'temp.tif' )
>> > image . shape
( 256 , 256 , 3 )使用 photometric 和 planarconfig 參數將 3x3x3 NumPy 陣列寫入交錯 RGB、平面 RGB 或 3 頁灰階 TIFF：
>> > data = numpy . random . randint ( 0 , 255 , ( 3 , 3 , 3 ), 'uint8' )
>> > imwrite ( 'temp.tif' , data , photometric = 'rgb' )
>> > imwrite ( 'temp.tif' , data , photometric = 'rgb' , planarconfig = 'separate' )
>> > imwrite ( 'temp.tif' , data , photometric = 'minisblack' )使用 extrasamples 參數指定如何解釋額外元件，例如，對於具有不關聯的 Alpha 通道的 RGBA 影像：
>> > data = numpy . random . randint ( 0 , 255 , ( 256 , 256 , 4 ), 'uint8' )
>> > imwrite ( 'temp.tif' , data , photometric = 'rgb' , extrasamples = [ 'unassalpha' ])將 3 維 NumPy 陣列寫入多頁、16 位元灰階 TIFF 檔案：
>> > data = numpy . random . randint ( 0 , 2 ** 12 , ( 64 , 301 , 219 ), 'uint16' )
>> > imwrite ( 'temp.tif' , data , photometric = 'minisblack' )從多頁 TIFF 檔案中將整個影像堆疊讀取為 NumPy 陣列：
>> > image_stack = imread ( 'temp.tif' )
>> > image_stack . shape
( 64 , 301 , 219 )
>> > image_stack . dtype
dtype ( 'uint16' )從 TIFF 檔案第一頁讀取影像作為 NumPy 陣列：
>> > image = imread ( 'temp.tif' , key = 0 )
>> > image . shape
( 301 , 219 )從選定的頁面範圍讀取影像：
>> > images = imread ( 'temp.tif' , key = range ( 4 , 40 , 2 ))
>> > images . shape
( 18 , 301 , 219 )迭代 TIFF 檔案中的所有頁面並連續讀取影像：
>> > with TiffFile ( 'temp.tif' ) as tif :
... for page in tif . pages :
... image = page . asarray ()
...獲取有關 TIFF 文件中圖像堆疊的信息，而無需讀取任何圖像數據：
>> > tif = TiffFile ( 'temp.tif' )
>> > len ( tif . pages ) # number of pages in the file
64
>> > page = tif . pages [ 0 ] # get shape and dtype of image in first page
>> > page . shape
( 301 , 219 )
>> > page . dtype
dtype ( 'uint16' )
>> > page . axes
'YX'
>> > series = tif . series [ 0 ] # get shape and dtype of first image series
>> > series . shape
( 64 , 301 , 219 )
>> > series . dtype
dtype ( 'uint16' )
>> > series . axes
'QYX'
>> > tif . close ()檢查 TIFF 檔案第一頁的「XResolution」標記：
>> > with TiffFile ( 'temp.tif' ) as tif :
... tag = tif . pages [ 0 ]. tags [ 'XResolution' ]
...
>> > tag . value
( 1 , 1 )
>> > tag . name
'XResolution'
>> > tag . code
282
>> > tag . count
1
>> > tag . dtype
< DATATYPE . RATIONAL : 5 >迭代 TIFF 檔案中的所有標籤：
>> > with TiffFile ( 'temp.tif' ) as tif :
... for page in tif . pages :
... for tag in page . tags :
... tag_name , tag_value = tag . name , tag . value
...覆寫現有標籤的值，例如 XResolution：
>> > with TiffFile ( 'temp.tif' , mode = 'r+' ) as tif :
... _ = tif . pages [ 0 ]. tags [ 'XResolution' ]. overwrite (( 96000 , 1000 ))
...使用 BigTIFF 格式、單獨的顏色分量、平鋪、Zlib 壓縮等級 8、水平差分預測器和其他元資料編寫 5 維浮點數組：
>> > data = numpy . random . rand ( 2 , 5 , 3 , 301 , 219 ). astype ( 'float32' )
>> > imwrite (
... 'temp.tif' ,
... data ,
... bigtiff = True ,
... photometric = 'rgb' ,
... planarconfig = 'separate' ,
... tile = ( 32 , 32 ),
... compression = 'zlib' ,
... compressionargs = { 'level' : 8 },
... predictor = True ,
... metadata = { 'axes' : 'TZCYX' },
... )將 xyz 體素大小為 2.6755x2.6755x3.9474 micron^3 的 10 fps 時間序列卷寫入 ImageJ hyperstack 格式的 TIFF 檔：
>> > volume = numpy . random . randn ( 6 , 57 , 256 , 256 ). astype ( 'float32' )
>> > image_labels = [ f' { i } ' for i in range ( volume . shape [ 0 ] * volume . shape [ 1 ])]
>> > imwrite (
... 'temp.tif' ,
... volume ,
... imagej = True ,
... resolution = ( 1.0 / 2.6755 , 1.0 / 2.6755 ),
... metadata = {
... 'spacing' : 3.947368 ,
... 'unit' : 'um' ,
... 'finterval' : 1 / 10 ,
... 'fps' : 10.0 ,
... 'axes' : 'TZYX' ,
... 'Labels' : image_labels ,
... },
... )從 ImageJ hyperstack 檔案中讀取磁碟區和元資料：
>> > with TiffFile ( 'temp.tif' ) as tif :
... volume = tif . asarray ()
... axes = tif . series [ 0 ]. axes
... imagej_metadata = tif . imagej_metadata
...
>> > volume . shape
( 6 , 57 , 256 , 256 )
>> > axes
'TZYX'
>> > imagej_metadata [ 'slices' ]
57
>> > imagej_metadata [ 'frames' ]
6對 ImageJ hyperstack 檔案中的連續影像資料進行記憶體映射：
>> > memmap_volume = memmap ( 'temp.tif' )
>> > memmap_volume . shape
( 6 , 57 , 256 , 256 )
>> > del memmap_volume建立一個包含空影像的 TIFF 檔案並寫入記憶體對映的 NumPy 陣列（注意：這不適用於壓縮或平鋪）：
>> > memmap_image = memmap (
... 'temp.tif' , shape = ( 256 , 256 , 3 ), dtype = 'float32' , photometric = 'rgb'
... )
>> > type ( memmap_image )
< class 'numpy.memmap' >
>> > memmap_image [ 255 , 255 , 1 ] = 1.0
>> > memmap_image . flush ()
>> > del memmap_image將兩個 NumPy 陣列寫入多系列 TIFF 檔案（注意：其他 TIFF 讀取器將無法識別這兩個系列；使用 OME-TIFF 格式以獲得更好的互通性）：
>> > series0 = numpy . random . randint ( 0 , 255 , ( 32 , 32 , 3 ), 'uint8' )
>> > series1 = numpy . random . randint ( 0 , 255 , ( 4 , 256 , 256 ), 'uint16' )
>> > with TiffWriter ( 'temp.tif' ) as tif :
... tif . write ( series0 , photometric = 'rgb' )
... tif . write ( series1 , photometric = 'minisblack' )
...從 TIFF 檔案中讀取第二個影像系列：
>> > series1 = imread ( 'temp.tif' , series = 1 )
>> > series1 . shape
( 4 , 256 , 256 )將一個連續系列的幀連續寫入 TIFF 檔案：
>> > data = numpy . random . randint ( 0 , 255 , ( 30 , 301 , 219 ), 'uint8' )
>> > with TiffWriter ( 'temp.tif' ) as tif :
... for frame in data :
... tif . write ( frame , contiguous = True )
...將影像系列附加到現有 TIFF 檔案（注意：這不適用於 ImageJ hyperstack 或 OME-TIFF 檔案）：
>> > data = numpy . random . randint ( 0 , 255 , ( 301 , 219 , 3 ), 'uint8' )
>> > imwrite ( 'temp.tif' , data , photometric = 'rgb' , append = True )從圖塊產生器建立 TIFF 檔案：
>> > data = numpy . random . randint ( 0 , 2 ** 12 , ( 31 , 33 , 3 ), 'uint16' )
>> > def tiles ( data , tileshape ):
... for y in range ( 0 , data . shape [ 0 ], tileshape [ 0 ]):
... for x in range ( 0 , data . shape [ 1 ], tileshape [ 1 ]):
... yield data [ y : y + tileshape [ 0 ], x : x + tileshape [ 1 ]]
...
>> > imwrite (
... 'temp.tif' ,
... tiles ( data , ( 16 , 16 )),
... tile = ( 16 , 16 ),
... shape = data . shape ,
... dtype = data . dtype ,
... photometric = 'rgb' ,
... )使用可選元資料編寫多維、多解析度（金字塔）、多系列 OME-TIFF 檔案。次解析度影像被寫入 SubIFD。將並行編碼限制為 2 個執行緒。將縮圖寫入為單獨的圖像系列：
>> > data = numpy . random . randint ( 0 , 255 , ( 8 , 2 , 512 , 512 , 3 ), 'uint8' )
>> > subresolutions = 2
>> > pixelsize = 0.29 # micrometer
>> > with TiffWriter ( 'temp.ome.tif' , bigtiff = True ) as tif :
... metadata = {
... 'axes' : 'TCYXS' ,
... 'SignificantBits' : 8 ,
... 'TimeIncrement' : 0.1 ,
... 'TimeIncrementUnit' : 's' ,
... 'PhysicalSizeX' : pixelsize ,
... 'PhysicalSizeXUnit' : 'µm' ,
... 'PhysicalSizeY' : pixelsize ,
... 'PhysicalSizeYUnit' : 'µm' ,
... 'Channel' : { 'Name' : [ 'Channel 1' , 'Channel 2' ]},
... 'Plane' : { 'PositionX' : [ 0.0 ] * 16 , 'PositionXUnit' : [ 'µm' ] * 16 },
... 'Description' : 'A multi-dimensional, multi-resolution image' ,
... 'MapAnnotation' : { # for OMERO
... 'Namespace' : 'openmicroscopy.org/PyramidResolution' ,
... '1' : '256 256' ,
... '2' : '128 128' ,
... },
... }
... options = dict (
... photometric = 'rgb' ,
... tile = ( 128 , 128 ),
... compression = 'jpeg' ,
... resolutionunit = 'CENTIMETER' ,
... maxworkers = 2 ,
... )
... tif . write (
... data ,
... subifds = subresolutions ,
... resolution = ( 1e4 / pixelsize , 1e4 / pixelsize ),
... metadata = metadata ,
... ** options ,
... )
... # write pyramid levels to the two subifds
... # in production use resampling to generate sub-resolution images
... for level in range ( subresolutions ):
... mag = 2 ** ( level + 1 )
... tif . write (
... data [..., :: mag , :: mag , :],
... subfiletype = 1 ,
... resolution = ( 1e4 / mag / pixelsize , 1e4 / mag / pixelsize ),
... ** options ,
... )
... # add a thumbnail image as a separate series
... # it is recognized by QuPath as an associated image
... thumbnail = ( data [ 0 , 0 , :: 8 , :: 8 ] >> 2 ). astype ( 'uint8' )
... tif . write ( thumbnail , metadata = { 'Name' : 'thumbnail' })
...存取金字塔 OME-TIFF 檔案中的影像層級：
>> > baseimage = imread ( 'temp.ome.tif' )
>> > second_level = imread ( 'temp.ome.tif' , series = 0 , level = 1 )
>> > with TiffFile ( 'temp.ome.tif' ) as tif :
... baseimage = tif . series [ 0 ]. asarray ()
... second_level = tif . series [ 0 ]. levels [ 1 ]. asarray ()
... number_levels = len ( tif . series [ 0 ]. levels ) # includes base level
...迭代並解碼 TIFF 檔案中的單一 JPEG 壓縮圖塊：
