This is an automated email from the ASF dual-hosted git repository. ggregory pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-imaging.git
commit 0b60d77312fb8f69874485f1f8819a5c42c36d4b Author: Gary Gregory <[email protected]> AuthorDate: Mon Jan 5 14:10:34 2026 -0500 Javadoc --- .../formats/tiff/AbstractTiffImageData.java | 1 + .../imaging/formats/tiff/TiffImageMetadata.java | 235 +++++++++++++++++++++ .../imaging/formats/tiff/TiffImageParser.java | 19 ++ .../formats/tiff/TiffImagingParameters.java | 67 ++++++ .../commons/imaging/formats/tiff/TiffReader.java | 79 +++++++ 5 files changed, 401 insertions(+) diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/AbstractTiffImageData.java b/src/main/java/org/apache/commons/imaging/formats/tiff/AbstractTiffImageData.java index c53889e1..beb0767c 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/AbstractTiffImageData.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/AbstractTiffImageData.java @@ -62,6 +62,7 @@ public abstract class AbstractTiffImageData { private final AbstractTiffElement.DataElement[] strips; // public final byte strips[][]; + /** The number of rows per strip. */ public final int rowsPerStrip; diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/TiffImageMetadata.java b/src/main/java/org/apache/commons/imaging/formats/tiff/TiffImageMetadata.java index dd68bc05..8778c42e 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/TiffImageMetadata.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/TiffImageMetadata.java @@ -78,22 +78,51 @@ public class TiffImageMetadata extends GenericImageMetadata { this.byteOrder = byteOrder; } + /** + * Adds a TIFF field as a metadata item. + * + * @param entry the TIFF field to add. + */ public void add(final TiffField entry) { add(new TiffMetadataItem(entry)); } + /** + * Finds a field by tag. + * + * @param tagInfo the tag information. + * @return the field, or null if not found. + * @throws ImagingException if an error occurs. + */ public TiffField findField(final TagInfo tagInfo) throws ImagingException { return directory.findField(tagInfo); } + /** + * Gets all fields in this directory. + * + * @return the list of fields. + */ public List<TiffField> getAllFields() { return directory.getDirectoryEntries(); } + /** + * Gets JPEG image data if present. + * + * @return the JPEG image data, or null. + */ public JpegImageData getJpegImageData() { return directory.getJpegImageData(); } + /** + * Gets the output directory for writing. + * + * @param byteOrder the byte order to use. + * @return the output directory. + * @throws ImagingException if an error occurs. + */ public TiffOutputDirectory getOutputDirectory(final ByteOrder byteOrder) throws ImagingException { try { final TiffOutputDirectory dstDir = new TiffOutputDirectory(type, byteOrder); @@ -175,17 +204,63 @@ public class TiffImageMetadata extends GenericImageMetadata { } + /** + * Contains GPS location information from TIFF metadata. + */ public static class GpsInfo { + + /** + * Latitude reference (N or S). + */ public final String latitudeRef; + + /** + * Longitude reference (E or W). + */ public final String longitudeRef; + /** + * Latitude degrees. + */ public final RationalNumber latitudeDegrees; + + /** + * Latitude minutes. + */ public final RationalNumber latitudeMinutes; + + /** + * Latitude seconds. + */ public final RationalNumber latitudeSeconds; + + /** + * Longitude degrees. + */ public final RationalNumber longitudeDegrees; + + /** + * Longitude minutes. + */ public final RationalNumber longitudeMinutes; + + /** + * Longitude seconds. + */ public final RationalNumber longitudeSeconds; + /** + * Constructs a new instance. + * + * @param latitudeRef the latitude reference. + * @param longitudeRef the longitude reference. + * @param latitudeDegrees the latitude degrees. + * @param latitudeMinutes the latitude minutes. + * @param latitudeSeconds the latitude seconds. + * @param longitudeDegrees the longitude degrees. + * @param longitudeMinutes the longitude minutes. + * @param longitudeSeconds the longitude seconds. + */ public GpsInfo(final String latitudeRef, final String longitudeRef, final RationalNumber latitudeDegrees, final RationalNumber latitudeMinutes, final RationalNumber latitudeSeconds, final RationalNumber longitudeDegrees, final RationalNumber longitudeMinutes, final RationalNumber longitudeSeconds) { @@ -199,6 +274,12 @@ public class TiffImageMetadata extends GenericImageMetadata { this.longitudeSeconds = longitudeSeconds; } + /** + * Gets the latitude as degrees north. + * + * @return the latitude in degrees north (negative for south). + * @throws ImagingException if the latitude reference is invalid. + */ public double getLatitudeAsDegreesNorth() throws ImagingException { final double result = latitudeDegrees.doubleValue() + latitudeMinutes.doubleValue() / 60.0 + latitudeSeconds.doubleValue() / 3600.0; @@ -260,18 +341,37 @@ public class TiffImageMetadata extends GenericImageMetadata { this.entry = entry; } + /** + * Gets the TIFF field. + * + * @return the TIFF field. + */ public TiffField getTiffField() { return entry; } } + /** + * The TIFF contents. + */ public final TiffContents contents; + /** + * Constructs a new instance. + * + * @param contents the TIFF contents. + */ public TiffImageMetadata(final TiffContents contents) { this.contents = contents; } + /** + * Finds a directory by type. + * + * @param directoryType the directory type. + * @return the directory, or null if not found. + */ public TiffDirectory findDirectory(final int directoryType) { final List<? extends ImageMetadataItem> directories = getDirectories(); for (final ImageMetadataItem directory1 : directories) { @@ -283,10 +383,25 @@ public class TiffImageMetadata extends GenericImageMetadata { return null; } + /** + * Finds a field by tag. + * + * @param tagInfo the tag information. + * @return the field, or null if not found. + * @throws ImagingException if an error occurs. + */ public TiffField findField(final TagInfo tagInfo) throws ImagingException { return findField(tagInfo, false); } + /** + * Finds a field by tag with directory matching option. + * + * @param tagInfo the tag information. + * @param exactDirectoryMatch whether to require exact directory match. + * @return the field, or null if not found. + * @throws ImagingException if an error occurs. + */ public TiffField findField(final TagInfo tagInfo, final boolean exactDirectoryMatch) throws ImagingException { // Please keep this method in sync with TiffField's getTag() final Integer tagCount = TiffTags.getTagCount(tagInfo.tag); @@ -328,6 +443,11 @@ public class TiffImageMetadata extends GenericImageMetadata { return null; } + /** + * Gets all fields from all directories. + * + * @return the list of all fields. + */ public List<TiffField> getAllFields() { final List<TiffField> result = new ArrayList<>(); final List<? extends ImageMetadataItem> directories = getDirectories(); @@ -338,10 +458,22 @@ public class TiffImageMetadata extends GenericImageMetadata { return result; } + /** + * Gets all directories. + * + * @return the list of directories. + */ public List<? extends ImageMetadataItem> getDirectories() { return super.getItems(); } + /** + * Gets the value of a field. + * + * @param tag the tag. + * @return the field value, or null if not found. + * @throws ImagingException if an error occurs. + */ public Object getFieldValue(final TagInfo tag) throws ImagingException { final TiffField field = findField(tag); if (field == null) { @@ -350,6 +482,13 @@ public class TiffImageMetadata extends GenericImageMetadata { return field.getValue(); } + /** + * Gets the value of an ASCII field. + * + * @param tag the tag. + * @return the field value, or null if not found. + * @throws ImagingException if an error occurs. + */ public String[] getFieldValue(final TagInfoAscii tag) throws ImagingException { final TiffField field = findField(tag); if (field == null) { @@ -362,6 +501,13 @@ public class TiffImageMetadata extends GenericImageMetadata { return tag.getValue(field.getByteOrder(), bytes); } + /** + * Gets the value of a byte field. + * + * @param tag the tag. + * @return the field value, or null if not found. + * @throws ImagingException if an error occurs. + */ public byte[] getFieldValue(final TagInfoByte tag) throws ImagingException { final TiffField field = findField(tag); if (field == null) { @@ -373,6 +519,13 @@ public class TiffImageMetadata extends GenericImageMetadata { return field.getByteArrayValue(); } + /** + * Gets the value of a doubles field. + * + * @param tag the tag. + * @return the field value, or null if not found. + * @throws ImagingException if an error occurs. + */ public double[] getFieldValue(final TagInfoDoubles tag) throws ImagingException { final TiffField field = findField(tag); if (field == null) { @@ -385,6 +538,13 @@ public class TiffImageMetadata extends GenericImageMetadata { return tag.getValue(field.getByteOrder(), bytes); } + /** + * Gets the value of a floats field. + * + * @param tag the tag. + * @return the field value, or null if not found. + * @throws ImagingException if an error occurs. + */ public float[] getFieldValue(final TagInfoFloats tag) throws ImagingException { final TiffField field = findField(tag); if (field == null) { @@ -397,6 +557,13 @@ public class TiffImageMetadata extends GenericImageMetadata { return tag.getValue(field.getByteOrder(), bytes); } + /** + * Gets the value of a GPS text field. + * + * @param tag the tag. + * @return the field value, or null if not found. + * @throws ImagingException if an error occurs. + */ public String getFieldValue(final TagInfoGpsText tag) throws ImagingException { final TiffField field = findField(tag); if (field == null) { @@ -405,6 +572,13 @@ public class TiffImageMetadata extends GenericImageMetadata { return tag.getValue(field); } + /** + * Gets the value of a longs field. + * + * @param tag the tag. + * @return the field value, or null if not found. + * @throws ImagingException if an error occurs. + */ public int[] getFieldValue(final TagInfoLongs tag) throws ImagingException { final TiffField field = findField(tag); if (field == null) { @@ -417,6 +591,13 @@ public class TiffImageMetadata extends GenericImageMetadata { return tag.getValue(field.getByteOrder(), bytes); } + /** + * Gets the value of a rationals field. + * + * @param tag the tag. + * @return the field value, or null if not found. + * @throws ImagingException if an error occurs. + */ public RationalNumber[] getFieldValue(final TagInfoRationals tag) throws ImagingException { final TiffField field = findField(tag); if (field == null) { @@ -429,6 +610,13 @@ public class TiffImageMetadata extends GenericImageMetadata { return tag.getValue(field.getByteOrder(), bytes); } + /** + * Gets the value of a signed bytes field. + * + * @param tag the tag. + * @return the field value, or null if not found. + * @throws ImagingException if an error occurs. + */ public byte[] getFieldValue(final TagInfoSBytes tag) throws ImagingException { final TiffField field = findField(tag); if (field == null) { @@ -440,6 +628,13 @@ public class TiffImageMetadata extends GenericImageMetadata { return field.getByteArrayValue(); } + /** + * Gets the value of a shorts field. + * + * @param tag the tag. + * @return the field value, or null if not found. + * @throws ImagingException if an error occurs. + */ public short[] getFieldValue(final TagInfoShorts tag) throws ImagingException { final TiffField field = findField(tag); if (field == null) { @@ -452,6 +647,13 @@ public class TiffImageMetadata extends GenericImageMetadata { return tag.getValue(field.getByteOrder(), bytes); } + /** + * Gets the value of a signed longs field. + * + * @param tag the tag. + * @return the field value, or null if not found. + * @throws ImagingException if an error occurs. + */ public int[] getFieldValue(final TagInfoSLongs tag) throws ImagingException { final TiffField field = findField(tag); if (field == null) { @@ -464,6 +666,13 @@ public class TiffImageMetadata extends GenericImageMetadata { return tag.getValue(field.getByteOrder(), bytes); } + /** + * Gets the value of a signed rationals field. + * + * @param tag the tag. + * @return the field value, or null if not found. + * @throws ImagingException if an error occurs. + */ public RationalNumber[] getFieldValue(final TagInfoSRationals tag) throws ImagingException { final TiffField field = findField(tag); if (field == null) { @@ -476,6 +685,13 @@ public class TiffImageMetadata extends GenericImageMetadata { return tag.getValue(field.getByteOrder(), bytes); } + /** + * Gets the value of a signed shorts field. + * + * @param tag the tag. + * @return the field value, or null if not found. + * @throws ImagingException if an error occurs. + */ public short[] getFieldValue(final TagInfoSShorts tag) throws ImagingException { final TiffField field = findField(tag); if (field == null) { @@ -488,6 +704,13 @@ public class TiffImageMetadata extends GenericImageMetadata { return tag.getValue(field.getByteOrder(), bytes); } + /** + * Gets the value of an XP string field. + * + * @param tag the tag. + * @return the field value, or null if not found. + * @throws ImagingException if an error occurs. + */ public String getFieldValue(final TagInfoXpString tag) throws ImagingException { final TiffField field = findField(tag); if (field == null) { @@ -496,6 +719,12 @@ public class TiffImageMetadata extends GenericImageMetadata { return tag.getValue(field); } + /** + * Gets GPS information from metadata. + * + * @return the GPS info, or null if not available. + * @throws ImagingException if an error occurs. + */ public GpsInfo getGpsInfo() throws ImagingException { final TiffDirectory gpsDirectory = findDirectory(TiffDirectoryConstants.DIRECTORY_TYPE_GPS); if (null == gpsDirectory) { @@ -546,6 +775,12 @@ public class TiffImageMetadata extends GenericImageMetadata { return result; } + /** + * Gets an output set for writing. + * + * @return the output set. + * @throws ImagingException if an error occurs. + */ public TiffOutputSet getOutputSet() throws ImagingException { final ByteOrder byteOrder = contents.header.byteOrder; final TiffOutputSet result = new TiffOutputSet(byteOrder); diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/TiffImageParser.java b/src/main/java/org/apache/commons/imaging/formats/tiff/TiffImageParser.java index 4c1740f3..aee69127 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/TiffImageParser.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/TiffImageParser.java @@ -87,6 +87,15 @@ public class TiffImageParser extends AbstractImageParser<TiffImagingParameters> return null; } + /** + * Collects raw image data from all directories. + * + * @param byteSource the byte source. + * @param params the imaging parameters. + * @return the list of raw image data. + * @throws ImagingException if an imaging error occurs. + * @throws IOException if an I/O error occurs. + */ public List<byte[]> collectRawImageData(final ByteSource byteSource, final TiffImagingParameters params) throws ImagingException, IOException { final FormatCompliance formatCompliance = FormatCompliance.getDefault(); final TiffContents contents = new TiffReader(params != null && params.isStrict()).readDirectories(byteSource, true, formatCompliance); @@ -235,6 +244,16 @@ public class TiffImageParser extends AbstractImageParser<TiffImagingParameters> return result; } + /** + * Gets a buffered image from a TIFF directory. + * + * @param directory the TIFF directory. + * @param byteOrder the byte order. + * @param params the imaging parameters. + * @return the buffered image. + * @throws ImagingException if an imaging error occurs. + * @throws IOException if an I/O error occurs. + */ protected BufferedImage getBufferedImage(final TiffDirectory directory, final ByteOrder byteOrder, final TiffImagingParameters params) throws ImagingException, IOException { final short compressionFieldValue; diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/TiffImagingParameters.java b/src/main/java/org/apache/commons/imaging/formats/tiff/TiffImagingParameters.java index c44ee48b..052e02e3 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/TiffImagingParameters.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/TiffImagingParameters.java @@ -108,14 +108,29 @@ public class TiffImagingParameters extends XmpImagingParameters<TiffImagingParam subImageHeight = 0; } + /** + * Gets the compression algorithm. + * + * @return the compression algorithm, or null if not set. + */ public Integer getCompression() { return compression; } + /** + * Gets the custom photometric interpreter. + * + * @return the custom photometric interpreter, or null if not set. + */ public AbstractPhotometricInterpreter getCustomPhotometricInterpreter() { return customPhotometricInterpreter; } + /** + * Gets the LZW compression block size. + * + * @return the LZW compression block size, or null if not set. + */ public Integer getLzwCompressionBlockSize() { return lzwCompressionBlockSize; } @@ -165,14 +180,29 @@ public class TiffImagingParameters extends XmpImagingParameters<TiffImagingParam return subImageY; } + /** + * Gets the T.4 options. + * + * @return the T.4 options, or null if not set. + */ public Integer getT4Options() { return t4Options; } + /** + * Gets the T.6 options. + * + * @return the T.6 options, or null if not set. + */ public Integer getT6Options() { return t6Options; } + /** + * Gets whether to read thumbnails. + * + * @return true if thumbnails should be read. + */ public boolean isReadThumbnails() { return readThumbnails; } @@ -186,16 +216,34 @@ public class TiffImagingParameters extends XmpImagingParameters<TiffImagingParam return subImageWidth > 0 && subImageHeight > 0; } + /** + * Sets the compression algorithm. + * + * @param compression the compression algorithm. + * @return this instance. + */ public TiffImagingParameters setCompression(final Integer compression) { this.compression = compression; return asThis(); } + /** + * Sets the custom photometric interpreter. + * + * @param customPhotometricInterpreter the custom photometric interpreter. + * @return this instance. + */ public TiffImagingParameters setCustomPhotometricInterpreter(final AbstractPhotometricInterpreter customPhotometricInterpreter) { this.customPhotometricInterpreter = customPhotometricInterpreter; return asThis(); } + /** + * Sets the LZW compression block size. + * + * @param lzwCompressionBlockSize the LZW compression block size. + * @return this instance. + */ public TiffImagingParameters setLzwCompressionBlockSize(final Integer lzwCompressionBlockSize) { this.lzwCompressionBlockSize = lzwCompressionBlockSize; return asThis(); @@ -213,6 +261,12 @@ public class TiffImagingParameters extends XmpImagingParameters<TiffImagingParam return asThis(); } + /** + * Sets whether to read thumbnails. + * + * @param readThumbnails true to read thumbnails. + * @return this instance. + */ public TiffImagingParameters setReadThumbnails(final boolean readThumbnails) { this.readThumbnails = readThumbnails; return asThis(); @@ -223,6 +277,7 @@ public class TiffImagingParameters extends XmpImagingParameters<TiffImagingParam * source images. * <p> * Note that the corner x and y coordinates must be positive integers (zero or greater). The width and height must be greater than zero. + * </p> * * @param x pixel coordinate of the upper-left corner of the source image, must be zero or greater. * @param y pixel coordinate of the upper-left corner of the source image, must be zero or greater. @@ -244,11 +299,23 @@ public class TiffImagingParameters extends XmpImagingParameters<TiffImagingParam return asThis(); } + /** + * Sets the T.4 options. + * + * @param t4Options the T.4 options. + * @return this instance. + */ public TiffImagingParameters setT4Options(final Integer t4Options) { this.t4Options = t4Options; return asThis(); } + /** + * Sets the T.6 options. + * + * @param t6Options the T.6 options. + * @return this instance. + */ public TiffImagingParameters setT6Options(final Integer t6Options) { this.t6Options = t6Options; return asThis(); diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/TiffReader.java b/src/main/java/org/apache/commons/imaging/formats/tiff/TiffReader.java index 562c1373..8cc8c574 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/TiffReader.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/TiffReader.java @@ -41,6 +41,9 @@ import org.apache.commons.imaging.formats.tiff.constants.TiffTagConstants; import org.apache.commons.imaging.formats.tiff.fieldtypes.AbstractFieldType; import org.apache.commons.imaging.formats.tiff.taginfos.TagInfoDirectory; +/** + * TIFF file reader. + */ public class TiffReader extends BinaryFileParser { private static class Collector implements Listener { @@ -110,15 +113,47 @@ public class TiffReader extends BinaryFileParser { } } + /** + * Listener interface for TIFF reading callbacks. + */ public interface Listener { + + /** + * Called when a directory is encountered. + * + * @param directory the directory. + * @return true to continue reading, false to stop. + */ boolean addDirectory(TiffDirectory directory); + /** + * Called when a field is encountered. + * + * @param field the field. + * @return true to continue reading, false to stop. + */ boolean addField(TiffField field); + /** + * Determines whether image data should be read. + * + * @return true to read image data, false otherwise. + */ boolean readImageData(); + /** + * Determines whether offset directories should be read. + * + * @return true to read offset directories, false otherwise. + */ boolean readOffsetDirectories(); + /** + * Called when the TIFF header is read. + * + * @param tiffHeader the TIFF header. + * @return true to continue reading, false to stop. + */ boolean setTiffHeader(TiffHeader tiffHeader); } @@ -127,6 +162,11 @@ public class TiffReader extends BinaryFileParser { private boolean standardTiff; private int entryMaxValueLength; + /** + * Constructs a new instance. + * + * @param strict true for strict parsing, false otherwise. + */ public TiffReader(final boolean strict) { this.strict = strict; } @@ -207,10 +247,29 @@ public class TiffReader extends BinaryFileParser { return new AbstractTiffImageData.Tiles(data, tileWidth, tileLength); } + /** + * Reads TIFF data from the byte source. + * + * @param byteSource the byte source. + * @param formatCompliance the format compliance. + * @param listener the listener for callbacks. + * @throws ImagingException if an imaging error occurs. + * @throws IOException if an I/O error occurs. + */ public void read(final ByteSource byteSource, final FormatCompliance formatCompliance, final Listener listener) throws ImagingException, IOException { readDirectories(byteSource, formatCompliance, listener); } + /** + * Reads the contents of a TIFF file. + * + * @param byteSource the byte source. + * @param params the imaging parameters. + * @param formatCompliance the format compliance. + * @return the TIFF contents. + * @throws ImagingException if an imaging error occurs. + * @throws IOException if an I/O error occurs. + */ public TiffContents readContents(final ByteSource byteSource, final TiffImagingParameters params, final FormatCompliance formatCompliance) throws ImagingException, IOException { @@ -219,6 +278,16 @@ public class TiffReader extends BinaryFileParser { return collector.getContents(); } + /** + * Reads all directories from a TIFF file. + * + * @param byteSource the byte source. + * @param readImageData true to read image data, false otherwise. + * @param formatCompliance the format compliance. + * @return the TIFF contents. + * @throws ImagingException if an imaging error occurs. + * @throws IOException if an I/O error occurs. + */ public TiffContents readDirectories(final ByteSource byteSource, final boolean readImageData, final FormatCompliance formatCompliance) throws ImagingException, IOException { final TiffImagingParameters params = new TiffImagingParameters(); @@ -418,6 +487,16 @@ public class TiffReader extends BinaryFileParser { return readDirectory(byteSource, offset, dirType, formatCompliance, listener, ignoreNextDirectory, visited); } + /** + * Reads only the first directory from a TIFF file. + * + * @param byteSource the byte source. + * @param readImageData true to read image data, false otherwise. + * @param formatCompliance the format compliance. + * @return the TIFF contents containing only the first directory. + * @throws ImagingException if an imaging error occurs. + * @throws IOException if an I/O error occurs. + */ public TiffContents readFirstDirectory(final ByteSource byteSource, final boolean readImageData, final FormatCompliance formatCompliance) throws ImagingException, IOException { final Collector collector = new FirstDirectoryCollector(readImageData);
