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 53fcb473ccaff8a52a7e1c6a9dee85ded845d615 Author: Gary Gregory <[email protected]> AuthorDate: Mon Jan 5 08:22:37 2026 -0500 Javadoc --- .../imaging/formats/tiff/TiffDirectory.java | 3 + .../commons/imaging/formats/tiff/TiffField.java | 140 +++++++++++++++++++-- .../commons/imaging/formats/tiff/TiffHeader.java | 27 ++++ .../imaging/formats/tiff/TiffImageMetadata.java | 42 +++++++ 4 files changed, 201 insertions(+), 11 deletions(-) diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/TiffDirectory.java b/src/main/java/org/apache/commons/imaging/formats/tiff/TiffDirectory.java index 0b7fa4df..d09c15ad 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/TiffDirectory.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/TiffDirectory.java @@ -64,6 +64,9 @@ import org.apache.commons.imaging.formats.tiff.taginfos.TagInfoXpString; */ public class TiffDirectory extends AbstractTiffElement implements Iterable<TiffField> { + /** + * An element containing image data within a TIFF directory. + */ public static final class ImageDataElement extends AbstractTiffElement { /** diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/TiffField.java b/src/main/java/org/apache/commons/imaging/formats/tiff/TiffField.java index a1a68100..6456b946 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/TiffField.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/TiffField.java @@ -41,7 +41,17 @@ import org.apache.commons.imaging.formats.tiff.taginfos.TagInfo; */ public class TiffField { + /** + * Represents an oversized field value that is stored outside the IFD entry. + */ public final class OversizeValueElement extends AbstractTiffElement { + + /** + * Constructs a new instance. + * + * @param offset the offset. + * @param length the length. + */ public OversizeValueElement(final int offset, final int length) { super(offset, length); } @@ -53,6 +63,7 @@ public class TiffField { } private static final Logger LOGGER = Logger.getLogger(TiffField.class.getName()); + private final TagInfo tagInfo; private final int tag; private final int directoryType; @@ -61,9 +72,20 @@ public class TiffField { private final long offset; private final byte[] value; private final ByteOrder byteOrder; - private final int sortHint; + /** + * Constructs a new instance. + * + * @param tag the tag number. + * @param directoryType the directory type. + * @param abstractFieldType the field type. + * @param count the count. + * @param offset the offset. + * @param value the value bytes. + * @param byteOrder the byte order. + * @param sortHint the sort hint. + */ public TiffField(final int tag, final int directoryType, final AbstractFieldType abstractFieldType, final long count, final long offset, final byte[] value, final ByteOrder byteOrder, final int sortHint) { @@ -79,6 +101,9 @@ public class TiffField { tagInfo = TiffTags.getTag(directoryType, tag); } + /** + * Dumps field information to the logger. + */ public void dump() { try (StringWriter sw = new StringWriter(); PrintWriter pw = new PrintWriter(sw)) { @@ -91,10 +116,21 @@ public class TiffField { } } + /** + * Dumps field information to a PrintWriter. + * + * @param pw the PrintWriter. + */ public void dump(final PrintWriter pw) { dump(pw, null); } + /** + * Dumps field information to a PrintWriter with an optional prefix. + * + * @param pw the PrintWriter. + * @param prefix the prefix string, or null. + */ public void dump(final PrintWriter pw, final String prefix) { if (prefix != null) { pw.print(prefix + ": "); @@ -105,7 +141,7 @@ public class TiffField { } /** - * Returns a copy of the raw value of the field. + * Gets a copy of the raw value of the field. * * @return the value of the field, in the byte order of the field. */ @@ -114,7 +150,7 @@ public class TiffField { } /** - * Returns the field's byte order. + * Gets the field's byte order. * * @return the byte order */ @@ -123,7 +159,7 @@ public class TiffField { } /** - * The length of the field's value. + * Gets the length of the field's value. * * @return the length, in bytes. */ @@ -132,7 +168,7 @@ public class TiffField { } /** - * Returns the field's count, derived from bytes 4-7. + * Gets the field's count, derived from bytes 4-7. * * @return the count */ @@ -140,14 +176,30 @@ public class TiffField { return count; } + /** + * Gets a description of this field without the value. + * + * @return the description. + */ public String getDescriptionWithoutValue() { return getTag() + " (0x" + Integer.toHexString(getTag()) + ": " + getTagInfo().name + "): "; } + /** + * Gets the directory type. + * + * @return the directory type. + */ public int getDirectoryType() { return directoryType; } + /** + * Gets the field value as a double array. + * + * @return the double array value. + * @throws ImagingException if the value cannot be converted. + */ public double[] getDoubleArrayValue() throws ImagingException { final Object o = getValue(); // if (o == null) @@ -189,6 +241,12 @@ public class TiffField { // return null; } + /** + * Gets the field value as a single double. + * + * @return the double value. + * @throws ImagingException if the value is missing or cannot be converted. + */ public double getDoubleValue() throws ImagingException { final Object o = getValue(); if (o == null) { @@ -199,7 +257,7 @@ public class TiffField { } /** - * Returns the field's type, derived from bytes 2-3. + * Gets the field's type, derived from bytes 2-3. * * @return the field's type, as a {@code FieldType} object. */ @@ -207,10 +265,21 @@ public class TiffField { return abstractFieldType; } + /** + * Gets the field type name. + * + * @return the field type name. + */ public String getFieldTypeName() { return getFieldType().getName(); } + /** + * Gets the field value as an int array. + * + * @return the int array value. + * @throws ImagingException if the value cannot be converted. + */ public int[] getIntArrayValue() throws ImagingException { final Object o = getValue(); // if (o == null) @@ -248,6 +317,12 @@ public class TiffField { // return null; } + /** + * Gets the field value as a single int. + * + * @return the int value. + * @throws ImagingException if the value is missing or cannot be converted. + */ public int getIntValue() throws ImagingException { final Object o = getValue(); if (o == null) { @@ -257,6 +332,12 @@ public class TiffField { return ((Number) o).intValue(); } + /** + * Gets the int value or sum of array values. + * + * @return the int value or sum. + * @throws ImagingException if an error occurs. + */ public int getIntValueOrArraySum() throws ImagingException { final Object o = getValue(); // if (o == null) @@ -346,26 +427,42 @@ public class TiffField { } /** - * Returns the TIFF field's offset/value field, derived from bytes 8-11. + * Gets the TIFF field's offset/value field, derived from bytes 8-11. * * @return the field's offset in a {@code long} of 4 packed bytes, or its inlined value <= 4 bytes long encoded in the field's byte order. */ - public int getOffset() { + public long getOffset() { return (int) offset; } + /** + * Gets the oversized value element if this field has one. + * + * @return the oversized value element, or null. + */ public AbstractTiffElement getOversizeValueElement() { if (isLocalValue()) { return null; } - return new OversizeValueElement(getOffset(), value.length); + return new OversizeValueElement((int) getOffset(), value.length); } + /** + * Gets the sort hint for ordering fields. + * + * @return the sort hint. + */ public int getSortHint() { return sortHint; } + /** + * Gets the field's string value. + * + * @return the string value. + * @throws ImagingException if an error occurs. + */ public String getStringValue() throws ImagingException { final Object o = getValue(); if (o == null) { @@ -378,18 +475,28 @@ public class TiffField { } /** - * Returns the field's tag, derived from bytes 0-1. + * Gets the field's tag, derived from bytes 0-1. * - * @return the tag, as an {@code int} in which only the lowest 2 bytes are set + * @return the tag, as an {@code int} in which only the lowest 2 bytes are set. */ public int getTag() { return tag; } + /** + * Gets tag information. + * + * @return the tag info. + */ public TagInfo getTagInfo() { return tagInfo; } + /** + * Gets the tag name. + * + * @return the tag name. + */ public String getTagName() { if (getTagInfo() == TiffTagConstants.TIFF_TAG_UNKNOWN) { return getTagInfo().name + " (0x" + Integer.toHexString(getTag()) + ")"; @@ -397,11 +504,22 @@ public class TiffField { return getTagInfo().name; } + /** + * Gets the value of the field. + * + * @return the value of the field. + * @throws ImagingException if an error occurs. + */ public Object getValue() throws ImagingException { // System.out.print("getValue"); return getTagInfo().getValue(this); } + /** + * Gets a description of the field's value. + * + * @return the value description. + */ public String getValueDescription() { try { return getValueDescription(getValue()); diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/TiffHeader.java b/src/main/java/org/apache/commons/imaging/formats/tiff/TiffHeader.java index c78954d3..3e6cc227 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/TiffHeader.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/TiffHeader.java @@ -20,12 +20,39 @@ import java.nio.ByteOrder; import org.apache.commons.imaging.formats.tiff.constants.TiffConstants; +/** + * The header of a TIFF file. + */ public class TiffHeader extends AbstractTiffElement { + + /** + * The byte order used in the TIFF file. + */ public final ByteOrder byteOrder; + + /** + * The TIFF version number. + */ public final int tiffVersion; + + /** + * The offset to the first Image File Directory (IFD). + */ public final long offsetToFirstIFD; + + /** + * Whether this is a BigTIFF file. + */ public final boolean bigTiff; + /** + * Constructs a new instance. + * + * @param byteOrder the byte order. + * @param tiffVersion the TIFF version. + * @param offsetToFirstIFD the offset to the first IFD. + * @param bigTiff whether this is a BigTIFF file. + */ public TiffHeader(final ByteOrder byteOrder, final int tiffVersion, final long offsetToFirstIFD, final boolean bigTiff) { super(0, TiffConstants.HEADER_SIZE); 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 95474a48..dd68bc05 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 @@ -47,15 +47,31 @@ import org.apache.commons.imaging.formats.tiff.write.TiffOutputDirectory; import org.apache.commons.imaging.formats.tiff.write.TiffOutputField; import org.apache.commons.imaging.formats.tiff.write.TiffOutputSet; +/** + * TIFF image metadata. + */ public class TiffImageMetadata extends GenericImageMetadata { + + /** + * Represents a TIFF directory as metadata. + */ public static class Directory extends GenericImageMetadata implements ImageMetadataItem { // private BufferedImage thumbnail; + /** + * The directory type. + */ public final int type; private final TiffDirectory directory; private final ByteOrder byteOrder; + /** + * Constructs a new instance. + * + * @param byteOrder the byte order. + * @param directory the TIFF directory. + */ public Directory(final ByteOrder byteOrder, final TiffDirectory directory) { this.type = directory.type; this.directory = directory; @@ -129,10 +145,22 @@ public class TiffImageMetadata extends GenericImageMetadata { } } + /** + * Gets the thumbnail image. + * + * @return the thumbnail image. + * @throws ImagingException if an imaging error occurs. + * @throws IOException if an I/O error occurs. + */ public BufferedImage getThumbnail() throws ImagingException, IOException { return directory.getTiffImage(byteOrder); } + /** + * Gets the TIFF image data. + * + * @return the TIFF image data. + */ public AbstractTiffImageData getTiffImageData() { return directory.getTiffImageData(); } @@ -183,6 +211,12 @@ public class TiffImageMetadata extends GenericImageMetadata { throw new ImagingException("Unknown latitude ref: \"" + latitudeRef + "\""); } + /** + * Gets the longitude as degrees east. + * + * @return the longitude in degrees east (negative for west). + * @throws ImagingException if the longitude reference is invalid. + */ public double getLongitudeAsDegreesEast() throws ImagingException { final double result = longitudeDegrees.doubleValue() + longitudeMinutes.doubleValue() / 60.0 + longitudeSeconds.doubleValue() / 3600.0; @@ -209,9 +243,17 @@ public class TiffImageMetadata extends GenericImageMetadata { } + /** + * Represents a single TIFF metadata item. + */ public static class TiffMetadataItem extends GenericImageMetadataItem { private final TiffField entry; + /** + * Constructs a new instance. + * + * @param entry the TIFF field. + */ public TiffMetadataItem(final TiffField entry) { // super(entry.getTagName() + " (" + entry.getFieldTypeName() + ")", super(entry.getTagName(), entry.getValueDescription());
