references/microscopy_imaging_formats.md
9.1 KB查看排版效果| 1 | # Microscopy and Scientific Imaging Formats |
| 2 | |
| 3 | **Reviewed:** 2026-09-30 |
| 4 | **Executable scope:** Metadata-only PNG/JPEG and TIFF/OME-TIFF inspection. |
| 5 | Pixels are never decoded by bundled tools. |
| 6 | |
| 7 | ## Exact capability matrix |
| 8 | |
| 9 | | Format | Bundled inspection | Depth | |
| 10 | |---|---|---| |
| 11 | | `.png`, `.jpg`, `.jpeg` | Optional, `pillow==12.3.0` | Width, height, mode, frame count, format, and metadata-entry count | |
| 12 | | `.tif`, `.tiff` | Optional, `tifffile==2026.9.20` | Bounded pages and generic series, shape/dtype, BigTIFF/OME flags | |
| 13 | | `.ome.tif`, `.ome.tiff` | Optional, `tifffile==2026.9.20` | Same structural metadata; OME-XML values are not emitted or semantically validated | |
| 14 | | ND2/CZI/LIF and other vendor microscopy | No | Reference-only vendor/Bio-Formats workflow | |
| 15 | | DICOM/NIfTI/MRC | No | Reference-only medical/neuro/EM workflow | |
| 16 | | SVS/NDPI and other whole-slide formats | No | Reference-only WSI workflow | |
| 17 | | OME-Zarr/Zarr | No | Directory/store formats are outside the regular-file boundary | |
| 18 | |
| 19 | No bundled script supports “all Pillow formats” or “all tifffile formats.” |
| 20 | Only the registered suffixes above are accepted. Unknown formats fail closed. |
| 21 | |
| 22 | ## Metadata-only safety model |
| 23 | |
| 24 | Images and metadata can contain protected health information, accession |
| 25 | numbers, specimen labels, GPS/EXIF fields, user comments, XML, external |
| 26 | references, or adversarial text. The inspectors: |
| 27 | |
| 28 | - accept only bounded local regular files inside `--root`; |
| 29 | - reject URLs, traversal, symlinks, special files, and suffix/signature |
| 30 | mismatches; |
| 31 | - reject declared element counts above 100,000,000 and excessive TIFF |
| 32 | pages/series; |
| 33 | - make Pillow decompression-bomb warnings fatal; |
| 34 | - never call `load()`, `asarray()`, `imread()`, image codecs, or thumbnail |
| 35 | generation; |
| 36 | - report metadata counts and structural facts, not EXIF/tag/OME-XML values; |
| 37 | - never follow metadata links or embedded instructions; and |
| 38 | - do not claim full corruption, codec, or semantic validation. |
| 39 | |
| 40 | Metadata-only access reduces decompression risk but is not a sandbox. Keep |
| 41 | libraries pinned and inspect untrusted images in an isolated, resource-limited |
| 42 | process when risk warrants it. |
| 43 | |
| 44 | ## PNG and JPEG |
| 45 | |
| 46 | Pillow's `Image.open()` is lazy: it identifies the container and reads enough |
| 47 | header information to construct an image object. The bundled inspector closes |
| 48 | the object without decoding pixels. |
| 49 | |
| 50 | ### Interpret carefully |
| 51 | |
| 52 | - PNG may be palette, grayscale, RGB/RGBA, 8/16-bit, multi-frame/APNG, or carry |
| 53 | textual/profile chunks. |
| 54 | - JPEG is lossy and normally unsuitable as a quantitative raw measurement |
| 55 | source. Repeated saves change pixels. |
| 56 | - Width/height/mode do not establish bit-depth fidelity, calibration, channel |
| 57 | identity, linearity, saturation, or acquisition settings. |
| 58 | - Metadata may be stale after image processing. |
| 59 | |
| 60 | For quantitative EDA, retain the acquisition-native image and compare |
| 61 | container metadata to instrument records. Do not compute intensity statistics |
| 62 | from display/export JPEGs. |
| 63 | |
| 64 | ## TIFF |
| 65 | |
| 66 | TIFF is a flexible container, not a single pixel organization. It can contain |
| 67 | multiple pages, tiles/strips, pyramids, SubIFDs, private/vendor tags, external |
| 68 | storage, and many compression schemes. A `.tif` suffix alone does not imply |
| 69 | microscopy or OME conformance. |
| 70 | |
| 71 | The bundled tifffile inspector reports: |
| 72 | |
| 73 | - main-page and generic-series counts, bounded to 1,000 and 128; |
| 74 | - per-series shape, axes, element count, and dtype kind/item size; |
| 75 | - classic TIFF versus BigTIFF; and |
| 76 | - whether tifffile identifies OME metadata. |
| 77 | |
| 78 | The current public `tiff.series(kind="generic")` API groups local pages without |
| 79 | reconstructing OME/vendor dimensions or discovering companion files. The pinned |
| 80 | `_multifile=False` argument adds an upstream internal safeguard; recheck it when |
| 81 | upgrading tifffile. Shape and axes describe generic page groups, not validated |
| 82 | OME XYZCT dimensions. Main pages plus declared immediate SubIFDs share the |
| 83 | 1,000-entry limit. Nested pyramids are not exhaustively validated. |
| 84 | |
| 85 | The reader necessarily parses structural tag values internally but never emits |
| 86 | raw tags or OME-XML. It does not decode compressed segments, validate every IFD, |
| 87 | open companion storage, or establish scientifically correct axis semantics. |
| 88 | |
| 89 | ## OME-TIFF |
| 90 | |
| 91 | OME-TIFF stores one or more image planes in TIFF and embeds an OME-XML metadata |
| 92 | block. Multi-file datasets can use UUID-based references. The OME specification |
| 93 | is richer than a filename convention. |
| 94 | |
| 95 | Before quantitative analysis, use OME-aware validation to confirm: |
| 96 | |
| 97 | - OME-XML schema/version and UUID/file references; |
| 98 | - dimension order and sizes for X/Y/Z/C/T; |
| 99 | - `TiffData` plane-to-IFD mapping; |
| 100 | - physical pixel sizes and units; |
| 101 | - channel names, wavelengths, detector/objective settings, and acquisition |
| 102 | times; and |
| 103 | - whether pyramids, labels, ROIs, or companion files are expected. |
| 104 | |
| 105 | The bundled inspector deliberately does not emit OME-XML because it may contain |
| 106 | identifiers or prompt-like text. `is_ome_tiff=true` is not a validation result. |
| 107 | |
| 108 | ## Reference-only vendor microscopy |
| 109 | |
| 110 | ND2, CZI, LIF, VSI, proprietary whole-slide files, and similar formats require |
| 111 | a version-aware vendor reader or Bio-Formats. Capabilities vary by library, |
| 112 | native dependency, file generation version, and series type. Do not choose a |
| 113 | reader only from a suffix. |
| 114 | |
| 115 | Workflow: |
| 116 | |
| 117 | 1. Preserve the original and capture instrument/software versions. |
| 118 | 2. Open a small approved file with a pinned reader in an isolated environment. |
| 119 | 3. Inventory scenes/series and XYZCT axes before loading pixels. |
| 120 | 4. Compare dimensions, calibration, channels, stage positions, and timestamps |
| 121 | to acquisition records. |
| 122 | 5. Bound tile/plane reads and never eagerly materialize a whole slide or 5-D |
| 123 | image. |
| 124 | 6. Convert a derived copy to OME-TIFF/OME-Zarr only with provenance and |
| 125 | round-trip checks. |
| 126 | |
| 127 | ## Reference-only medical and whole-slide imaging |
| 128 | |
| 129 | ### DICOM |
| 130 | |
| 131 | DICOM is a clinical standard with extensive metadata and possible PHI. A |
| 132 | single `.dcm` may be one instance in a study/series. Use institutional policy, |
| 133 | approved de-identification, and DICOM-aware tools. Do not print patient, study, |
| 134 | series, accession, date, burned-in annotation, or private-tag values. |
| 135 | |
| 136 | ### NIfTI |
| 137 | |
| 138 | Validate dimensions, voxel sizes, affine/qform/sform, units, orientation, |
| 139 | scaling, and time axis with neuroimaging tooling. `.nii.gz` is compressed and |
| 140 | is not decompressed by bundled scripts. |
| 141 | |
| 142 | ### Whole-slide imaging |
| 143 | |
| 144 | SVS, NDPI, and related formats are large tiled pyramids and may contain label or |
| 145 | macro images with identifiers. Use OpenSlide/tiffslide or a validated vendor |
| 146 | reader, inspect associated images, and sample bounded tiles. Split by patient |
| 147 | before tile generation to prevent leakage. |
| 148 | |
| 149 | ## Imaging EDA rigor |
| 150 | |
| 151 | 1. Define the independent unit: pixel, object, field, well, section, specimen, |
| 152 | subject, or acquisition session. |
| 153 | 2. Separate biological from technical replication and avoid treating tiles or |
| 154 | cells from one specimen as independent subjects. |
| 155 | 3. Record calibration, units, bit depth, detector response, exposure, gain, |
| 156 | illumination, objective, channel, Z/T spacing, and processing history. |
| 157 | 4. Audit missing/corrupt planes, saturation, clipping, background, focus, |
| 158 | illumination, registration, segmentation, and batch/site effects. |
| 159 | 5. Preserve raw pixels. Do not automatically rescale, denoise, background |
| 160 | subtract, discard fields, or remove objects. |
| 161 | 6. Fit normalization, segmentation thresholds, feature selection, and models |
| 162 | on training specimens only; split subjects/specimens before tiling. |
| 163 | 7. Report object/field/specimen-level sensitivity, not only pooled pixels. |
| 164 | 8. Do not infer biological mechanism, diagnosis, or treatment effect from |
| 165 | descriptive image patterns. |
| 166 | |
| 167 | ## Pinned optional snapshot |
| 168 | |
| 169 | ```bash |
| 170 | uv pip install \ |
| 171 | "pillow==12.3.0" \ |
| 172 | "tifffile==2026.9.20" \ |
| 173 | "numpy==2.5.3" |
| 174 | ``` |
| 175 | |
| 176 | Pillow 12.3.0 was released 2026-07-01 and requires Python 3.10+. |
| 177 | tifffile 2026.9.20 was released 2026-09-21 and requires Python 3.12+. |
| 178 | Imagecodecs is not installed or invoked by the metadata-only inspector. |
| 179 | |
| 180 | ## Authoritative sources |
| 181 | |
| 182 | Current parser APIs and format guidance reviewed 2026-09-30. Historical |
| 183 | methodology citations are retained as source context. |
| 184 | |
| 185 | - Pillow, [`Image` module and decompression-bomb protection](https://pillow.readthedocs.io/en/stable/reference/Image.html). |
| 186 | - [Pillow PyPI](https://pypi.org/project/pillow/), version 12.3.0, |
| 187 | released 2026-07-01. |
| 188 | - tifffile, [current API and generic-series examples](https://www.cgohlke.com/docs/tifffile/). |
| 189 | - [tifffile PyPI](https://pypi.org/project/tifffile/), version 2026.9.20, |
| 190 | released 2026-09-21; upstream notes that codecs are required for decoding |
| 191 | compressed segments. |
| 192 | - Library of Congress, [TIFF, Revision 6.0 format description](https://www.loc.gov/preservation/digital/formats/fdd/fdd000022.shtml) |
| 193 | and the ITU-hosted [TIFF 6.0 specification](https://www.itu.int/itudoc/itu-t/com16/tiff-fx/docs/tiff6.pdf). |
| 194 | - OME, [OME-TIFF specification](https://ome-model.readthedocs.io/en/stable/ome-tiff/specification.html). |
| 195 | - OME, [OME Data Model and File Formats](https://ome-model.readthedocs.io/en/stable/). |
| 196 | - DICOM Standards Committee, [current DICOM standard](https://www.dicomstandard.org/current). |
| 197 | - OpenSlide, [supported formats and Python API](https://openslide.org/api/python/). |
| 198 | - National Academies (2019), [reproducibility and provenance](https://doi.org/10.17226/25303). |
文件内容是平台检查时读出的文本，只供查看。平台不会运行包里的任何脚本或程序。
