[med-svn] r8094 - trunk/packages/openslide/trunk/debian
Mathieu Malaterre
malat-guest at alioth.debian.org
Thu Oct 6 11:55:25 UTC 2011
Author: malat-guest
Date: 2011-10-06 11:55:25 +0000 (Thu, 06 Oct 2011)
New Revision: 8094
Modified:
trunk/packages/openslide/trunk/debian/openslide-show-properties.1
Log:
final cleanup
Modified: trunk/packages/openslide/trunk/debian/openslide-show-properties.1
===================================================================
--- trunk/packages/openslide/trunk/debian/openslide-show-properties.1 2011-10-06 11:10:30 UTC (rev 8093)
+++ trunk/packages/openslide/trunk/debian/openslide-show-properties.1 2011-10-06 11:55:25 UTC (rev 8094)
@@ -9,16 +9,14 @@
.PP
.SS "Properties generated by OpenSlide"
.PP
-.nf
-openslide.vendor
- The name of the vendor backend.
-openslide.comment
- A free-form text comment, the same as returned from openslide_get_comment.
-openslide.quickhash-1
- A non-cryptographic hash of a subset of the slide data. It can be used to uniquely identify a particular virtual slide, but cannot be used to detect file corruption or modification.
-openslide.background-color
- The background color of the slide, given as an RGB hex triplet. This property is not always present.
-.fi
+.IP openslide.vendor
+The name of the vendor backend.
+.IP openslide.comment
+A free-form text comment, the same as returned from openslide_get_comment.
+.IP openslide.quickhash-1
+A non-cryptographic hash of a subset of the slide data. It can be used to uniquely identify a particular virtual slide, but cannot be used to detect file corruption or modification.
+.IP openslide.background-color
+The background color of the slide, given as an RGB hex triplet. This property is not always present.
.PP
.SS "Properties from the JPEG backend"
@@ -26,36 +24,34 @@
.SS "Properties from the TIFF backend"
.PP
-.nf
-tiff.ImageDescription
- The contents of the TIFF ImageDescripton tag.
-tiff.Make
- The contents of the TIFF Make tag.
-tiff.Model
- The contents of the TIFF Model tag.
-tiff.Software
- The contents of the TIFF Software tag.
-tiff.DateTime
- The contents of the TIFF DateTime tag.
-tiff.Artist
- The contents of the TIFF Artist tag.
-tiff.HostComputer
- The contents of the TIFF HostComputer tag.
-tiff.Copyright
- The contents of the TIFF Copyright tag.
-tiff.DocumentName
- The contents of the TIFF DocumentName tag.
-tiff.XResolution
- The contents of the TIFF XResolution tag.
-tiff.YResolution
- The contents of the TIFF yResolution tag.
-tiff.XPosition
- The contents of the TIFF XPosition tag.
-tiff.YPosition
- The contents of the TIFF YPosition tag.
-tiff.ResolutionUnit
- The contents of the TIFF ResolutionUnit tag.
-.fi
+.IP tiff.ImageDescription
+The contents of the TIFF ImageDescripton tag.
+.IP tiff.Make
+The contents of the TIFF Make tag.
+.IP tiff.Model
+The contents of the TIFF Model tag.
+.IP tiff.Software
+The contents of the TIFF Software tag.
+.IP tiff.DateTime
+The contents of the TIFF DateTime tag.
+.IP tiff.Artist
+The contents of the TIFF Artist tag.
+.IP tiff.HostComputer
+The contents of the TIFF HostComputer tag.
+.IP tiff.Copyright
+The contents of the TIFF Copyright tag.
+.IP tiff.DocumentName
+The contents of the TIFF DocumentName tag.
+.IP tiff.XResolution
+The contents of the TIFF XResolution tag.
+.IP tiff.YResolution
+The contents of the TIFF yResolution tag.
+.IP tiff.XPosition
+The contents of the TIFF XPosition tag.
+.IP tiff.YPosition
+The contents of the TIFF YPosition tag.
+.IP tiff.ResolutionUnit
+The contents of the TIFF ResolutionUnit tag.
.PP
.SH Vendor-specific properties
.SH Trestle format
@@ -86,7 +82,7 @@
allbox, tab(^); ll.
\fBTag\fR^\fBDescription\fR
ImageDescription^Stores some important key-value pairs, see below
- Software^Starts with "MedScan"
+ Software^Starts with \*(lqMedScan\*(rq
XResolution, YResolution^T{
Seems to store microns-per-pixel (MPP), which may or may not take into account
the correct objective power. Note that this is inverted from standard TIFF,
@@ -96,7 +92,10 @@
.SS Extra data stored in ImageDescription
-The ImageDescription tag contains semicolon-delimited key-value pairs. A key-value pair is equals-delimited. We use the OverlapsXY and Background Color keys from the ImageDescription, and ignore the rest. All of these values are stored as properties starting with \*(lqtrestle.\*(rq.
+The ImageDescription tag contains semicolon-delimited key-value pairs. A
+key-value pair is equals-delimited. We use the OverlapsXY and Background Color
+keys from the ImageDescription, and ignore the rest. All of these values are
+stored as properties starting with \*(lqtrestle.\*(rq.
.TS
allbox, tab(^); ll.
@@ -110,7 +109,8 @@
.SS TIFF Image Directory Organization
-The first image in the TIFF file is the full-resolution image. The subsequent images are assumed to be decreasingly sized reduced-resolution images.
+The first image in the TIFF file is the full-resolution image. The subsequent
+images are assumed to be decreasingly sized reduced-resolution images.
.SS Overlaps
@@ -118,7 +118,9 @@
Example: \*(lq 64 64 32 32 16 16\*(rq (note the initial space).
-These values are assumed to represent the amount of overlap between adjacent tiles in pixels, in both X and Y. This example encodes 3 levels worth of overlaps. Further overlaps are assumed to have the value 0.
+These values are assumed to represent the amount of overlap between adjacent
+tiles in pixels, in both X and Y. This example encodes 3 levels worth of
+overlaps. Further overlaps are assumed to have the value 0.
.SS Associated Images
@@ -126,7 +128,7 @@
.SS Known Properties
-All data encoded in the ImageDescription TIFF field is represented as properties prefixed with "trestle.".
+All data encoded in the ImageDescription TIFF field is represented as properties prefixed with \*(lqtrestle.\*(rq.
.SH Hamamatsu format
@@ -160,27 +162,47 @@
.IP \n+[step]
The restart interval in each JPEG file is zero, or evenly divides into the number of MCUs per row.
.IP \n+[step]
-The image files (except the map file) all have the same "tile" sizes (see below).
+The image files (except the map file) all have the same \*(lqtile\*(rq sizes (see below).
.SS Overview
-The Hamamatsu format consists of an index file (VMS or VMU), 2 or more image files, and (in the case of VMS) an "optimisation" file.
+The Hamamatsu format consists of an index file (VMS or VMU), 2 or more image
+files, and (in the case of VMS) an \*(lqoptimisation\*(rq file.
Multiple focal planes are ignored, only focal plane 0 is read.
-Because JPEG does not allow for large files, multiple JPEG files are needed to encode large images. To avoid having many files, the Hamamatsu format uses close to maximum size (65K by 65K) JPEG files.
+Because JPEG does not allow for large files, multiple JPEG files are needed to
+encode large images. To avoid having many files, the Hamamatsu format uses
+close to maximum size (65K by 65K) JPEG files.
-Unfortunately, (unlike TIFF) JPEG provides very poor support for random-access decoding of parts of a file. To get around this, JPEG restart markers are placed at regular intervals, and these offsets are specified in the optimisation file. With restart markers identified, OpenSlide can treat JPEG as a tiled format, where the height is the height of an MCU row, and the width is the number of MCUs per row divided by the restart marker interval times the width of an MCU. (This often leads to oddly-shaped and inefficient tiles of 8x2048, for example.)
+Unfortunately, (unlike TIFF) JPEG provides very poor support for random-access
+decoding of parts of a file. To get around this, JPEG restart markers are
+placed at regular intervals, and these offsets are specified in the
+optimisation file. With restart markers identified, OpenSlide can treat JPEG as
+a tiled format, where the height is the height of an MCU row, and the width is
+the number of MCUs per row divided by the restart marker interval times the
+width of an MCU. (This often leads to oddly-shaped and inefficient tiles of
+8x2048, for example.)
-Unfortunately, the optimisation file does not give the location of every restart marker, only the ones found at the beginning of an MCU row. It also seems that the file ends early, and does not give the location of the restart marker at the last MCU row of the last image file.
+Unfortunately, the optimisation file does not give the location of every
+restart marker, only the ones found at the beginning of an MCU row. It also
+seems that the file ends early, and does not give the location of the restart
+marker at the last MCU row of the last image file.
-Thus, the optimisation file can only be taken as a hint, and cannot be trusted. The entire set of JPEG files must be scanned for restart markers in order to facilitate random access. OpenSlide does this lazily as needed, and also in a background thread that runs only when OpenSlide is otherwise idle.
+Thus, the optimisation file can only be taken as a hint, and cannot be trusted.
+The entire set of JPEG files must be scanned for restart markers in order to
+facilitate random access. OpenSlide does this lazily as needed, and also in a
+background thread that runs only when OpenSlide is otherwise idle.
-The map file is a lower-resolution version of the other images, and can be used to make a 2-level JPEG pyramid. JPEG also allows for lower-resolution decoding, so further pyramid levels are synthesized from each JPEG file.
+The map file is a lower-resolution version of the other images, and can be used
+to make a 2-level JPEG pyramid. JPEG also allows for lower-resolution decoding,
+so further pyramid levels are synthesized from each JPEG file.
.SS VMS File
-The .vms file is the main index file for the VMS format. It is a Windows INI-style key-value pair file, with sections. Only keys in the Virtual Microscope Specimen group are read by OpenSlide.
+The .vms file is the main index file for the VMS format. It is a Windows
+INI-style key-value pair file, with sections. Only keys in the Virtual
+Microscope Specimen group are read by OpenSlide.
Here are known keys from the file:
@@ -211,7 +233,7 @@
PhysicalWidth^Width of the slide in some unit?
PhysicalHeight^Height of the slide in some unit?
LayerSpacing^Unknown
- MacroImage^Image file for the "macro" associated image
+ MacroImage^Image file for the \*(lqmacro\*(rq associated image
PhysicalMacroWidth^Unknown
PhysicalMacroHeight^Unknown
XOffsetFromSlideCentre^Unknown
@@ -220,7 +242,8 @@
.SS VMU File
-The .vmu file is the main index file for the VMU format. Only keys in the Uncompressed Virtual Microscope Specimen group are read by OpenSlide.
+The .vmu file is the main index file for the VMU format. Only keys in the
+Uncompressed Virtual Microscope Specimen group are read by OpenSlide.
Here are known keys from the file:
@@ -291,23 +314,38 @@
.SS Optimisation File (only for VMS)
-The optimisation file contains a list of 32- (or 64- or 320- ?) bit little endian values, giving the file offset into an MCU row, each offset starts at a 40-byte alignment, and the last row (of the entire file, not each image) seems to be missing. The offsets are all packed into 1 file, even with multiple images. The order of images is left-to-right, top-to-bottom.
+The optimisation file contains a list of 32- (or 64- or 320- ?) bit little
+endian values, giving the file offset into an MCU row, each offset starts at a
+40-byte alignment, and the last row (of the entire file, not each image) seems
+to be missing. The offsets are all packed into 1 file, even with multiple
+images. The order of images is left-to-right, top-to-bottom.
.SS Map File
-The VMS map file is a standard JPEG file. Its restart markers (if any) are not included in the optimisation file. The VMU map file is in NGR format. This file can be used to provide a lower-resolution view of the slide.
+The VMS map file is a standard JPEG file. Its restart markers (if any) are not
+included in the optimisation file. The VMU map file is in NGR format. This file
+can be used to provide a lower-resolution view of the slide.
.SS Image Files
-These files are given by the various ImageFile keys. They are assumed to have a height which is a multiple of the MCU height. They are assumed to have a width which is a multiple of MCUs per row divided by the restart interval.
+These files are given by the various ImageFile keys. They are assumed to have a
+height which is a multiple of the MCU height. They are assumed to have a width
+which is a multiple of MCUs per row divided by the restart interval.
For VMS, these files are in JPEG, for VMU they are in NGR format.
.SS NGR Format
-The NGR file contains uncompressed 16-bit RGB data, with a small header. The files we have encountered start with GN, two more bytes, and then width, height, and column width in little endian 32-bit format. The column width must divide evenly into the width. Column width is important, since NGR files are generated in columns, where the first column comes first in the file, followed by subsequent files. Columns are painted left-to-right.
+The NGR file contains uncompressed 16-bit RGB data, with a small header. The
+files we have encountered start with GN, two more bytes, and then width,
+height, and column width in little endian 32-bit format. The column width must
+divide evenly into the width. Column width is important, since NGR files are
+generated in columns, where the first column comes first in the file, followed
+by subsequent files. Columns are painted left-to-right.
-At offset 24 is another 32-bit integer which gives the offset in the file to the start of the image data. The image data we have encountered is in 16-bit little endian format.
+At offset 24 is another 32-bit integer which gives the offset in the file to
+the start of the image data. The image data we have encountered is in 16-bit
+little endian format.
.SS Associated Images
@@ -316,27 +354,33 @@
.SS Known Properties
-All key-value data stored in the VMS/VMU file are encoded as properties prefixed with "hamamatsu.".
+All key-value data stored in the VMS/VMU file are encoded as properties prefixed with \*(lqhamamatsu.\*(rq.
.SS Preliminary NDPI Notes
-NDPI is basically VMS stuffed into a broken TIFF file. libtiff cannot read the headers of a TIFF file, because NDPI specifies the RowsPerStrip as the height of the file, and after doing out the multiplication, this typically overflows libtiff and it refuses to open the file. Also, the TIFF tags are not stored in sorted order (sometimes, they may have fixed this in later versions).
+NDPI is basically VMS stuffed into a broken TIFF file. libtiff cannot read the
+headers of a TIFF file, because NDPI specifies the RowsPerStrip as the height
+of the file, and after doing out the multiplication, this typically overflows
+libtiff and it refuses to open the file. Also, the TIFF tags are not stored in
+sorted order (sometimes, they may have fixed this in later versions).
-Unlike the VMS format, the NDPI is stored in a pyramid format as TIFF directory entries. The macro image seems to come last.
+Unlike the VMS format, the NDPI is stored in a pyramid format as TIFF directory
+entries. The macro image seems to come last.
-If one just reads the TIFF tags directly, perhaps using tiffdump, one will find:
+If one just reads the TIFF tags directly, perhaps using tiffdump, one will
+find:
.TS
allbox, tab(^); ll.
\fBTag\fR^\fBDescription\fR
ImageWidth^Width of the image
ImageHeight^Height of the image
- Make^"Hamamatsu"
- Model^"NanoZoomer" or "C9600-12", etc
+ Make^\*(lqHamamatsu\*(rq
+ Model^\*(lqNanoZoomer\*(rq or \*(lqC9600-12\*(rq, etc
XResolution^Seemingly correct X resolution, when interpreted with ResolutionUnit
YResolution^Seemingly correct Y resolution, when interpreted with ResolutionUnit
ResolutionUnit^Seemingly correct resolution unit
- Software^"NDP.scan", sometimes with a version number
+ Software^\*(lqNDP.scan\*(rq, sometimes with a version number
StripOffsets^The offset of the JPEG file for this layer
StripByteCounts^The length of the JPEG file for this layer
65420^Unknown, always 1?
@@ -364,19 +408,38 @@
65446^Unknown, always 0?
.TE
-Unlike in VMS, JPEG files in NDPI are not necessarily valid. If ImageWidth or ImageHeight exceeds the JPEG limit of 65535, then the width or height as stored in the JPEG file is 0. JPEG files are not split into validly-sized files like in VMS. libjpeg will refuse to read the header of such a file, so the JPEG data stream must be altered when fed into libjpeg. Since a random access source manager is already required to read VMS JPEG files, this change is not too bad.
+Unlike in VMS, JPEG files in NDPI are not necessarily valid. If ImageWidth or
+ImageHeight exceeds the JPEG limit of 65535, then the width or height as stored
+in the JPEG file is 0. JPEG files are not split into validly-sized files like
+in VMS. libjpeg will refuse to read the header of such a file, so the JPEG data
+stream must be altered when fed into libjpeg. Since a random access source
+manager is already required to read VMS JPEG files, this change is not too bad.
.SH Aperio format
-.nf
-Format
- single-file pyramidal tiled TIFF, with non-standard metadata and compression
-File extensions
- .svs, .tif
-OpenSlide vendor backend
- aperio
-OpenSlide ops backend
- tiff
-.fi
+.PP
+.IP Format
+single-file pyramidal tiled TIFF, with non-standard metadata and compression
+.IP "File extensions"
+\&.svs, .tif
+.IP "OpenSlide vendor backend"
+aperio
+.IP "OpenSlide ops backend"
+tiff
+.PP
+
+.SS Vendor Documentation
+
+http://www.aperio.com/documents/api/Aperio_Digital_Slides_and_Third-party_data_interchange.pdf
+
+.SS Detection
+
+.nr step 1 1
+Aperio slides are stored in single-file TIFF format. OpenSlide will detect a file as Aperio if:
+.IP \n[step] 3
+The file is TIFF.
+.IP \n+[step]
+The ImageDescription tag starts with Aperio.
+
.SS Relevant TIFF tags
One can also use tiffinfo or tiffdump to dump information on those TIFF files.
@@ -397,7 +460,7 @@
information as well as what look like offsets. Additionally, vertical
line-delimited key-value pairs are stored, in at least the full-resolution
image. A key-value pair is equals-delimited. These key-values are stored as
-properties starting with "aperio.". Currently, OpenSlide does not use any of
+properties starting with \*(lqaperio.\*(rq. Currently, OpenSlide does not use any of
the information present in these key-value fields.
For stripped images, the ImageDescription tag may contain a name, followed by a
@@ -408,18 +471,18 @@
http://www.aperio.com/documents/api/Aperio_Digital_Slides_and_Third-party_data_interchange.pdf page 14:
-The first image in an SVS file is always the baseline image (full resolution).
-This image is always tiled, usually with a tile size of 240x240 pixels. The
-second image is always a thumbnail, typically with dimensions of about 1024x768
-pixels. Unlike the other slide images, the thumbnail image is always stripped.
-Following the thumbnail there may be one or more intermediate "pyramid" images.
-These are always compressed with the same type of compression as the baseline
-image, and have a tiled organization with the same tile size.
+ The first image in an SVS file is always the baseline image (full resolution).
+ This image is always tiled, usually with a tile size of 240x240 pixels. The
+ second image is always a thumbnail, typically with dimensions of about 1024x768
+ pixels. Unlike the other slide images, the thumbnail image is always stripped.
+ Following the thumbnail there may be one or more intermediate \*(lqpyramid\*(rq images.
+ These are always compressed with the same type of compression as the baseline
+ image, and have a tiled organization with the same tile size.
-Optionally at the end of an SVS file there may be a slide label image, which is
-a low resolution picture taken of the slide's label, and/or a macro camera
-image, which is a low resolution picture taken of the entire slide. The label
-and macro images are always stripped.
+ Optionally at the end of an SVS file there may be a slide label image, which is
+ a low resolution picture taken of the slide's label, and/or a macro camera
+ image, which is a low resolution picture taken of the entire slide. The label
+ and macro images are always stripped.
.SS JPEG 2000 (compression types 33003 or 33005)
@@ -432,18 +495,17 @@
found in the JPEG 2000 codestream.
.SS Associated Images
-
-.nf
-thumbnail
- the second image in the file
-label
- optional, the name "label" is given in ImageDescription
-macro
- optional, the name "macro" is given in ImageDescription
-.fi
+.PP
+.IP thumbnail
+the second image in the file
+.IP label
+optional, the name \*(lqlabel\*(rq is given in ImageDescription
+.IP macro
+optional, the name \*(lqmacro\*(rq is given in ImageDescription
+.PP
.SS Known Properties
-All key-value data encoded in the ImageDescription TIFF field is represented as properties prefixed with "aperio.".
+All key-value data encoded in the ImageDescription TIFF field is represented as properties prefixed with \*(lqaperio.\*(rq.
.SH "SEE ALSO"
More information about the debian-med-commit
mailing list