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 7dcfe675a40bbfff1f02a741dd21f5a149183f7e Author: Gary Gregory <[email protected]> AuthorDate: Sat Jan 3 08:22:39 2026 -0500 Javadoc --- .../apache/commons/imaging/FormatCompliance.java | 74 ++++++++++++++++++++++ .../imaging/common/GenericImageMetadata.java | 40 ++++++++++++ .../tiff/constants/GeoTiffTagConstants.java | 8 +++ .../formats/tiff/fieldtypes/FieldTypeAscii.java | 9 +++ .../formats/tiff/fieldtypes/FieldTypeByte.java | 9 +++ .../formats/tiff/fieldtypes/FieldTypeDouble.java | 9 +++ .../formats/tiff/fieldtypes/FieldTypeFloat.java | 9 +++ .../formats/tiff/fieldtypes/FieldTypeLong.java | 9 +++ .../formats/tiff/fieldtypes/FieldTypeLong8.java | 6 ++ .../formats/tiff/fieldtypes/FieldTypeRational.java | 9 +++ .../formats/tiff/fieldtypes/FieldTypeShort.java | 9 +++ .../apache/commons/imaging/icc/IccProfileInfo.java | 69 ++++++++++++++++++++ 12 files changed, 260 insertions(+) diff --git a/src/main/java/org/apache/commons/imaging/FormatCompliance.java b/src/main/java/org/apache/commons/imaging/FormatCompliance.java index 4b0e469c..343d8fbf 100644 --- a/src/main/java/org/apache/commons/imaging/FormatCompliance.java +++ b/src/main/java/org/apache/commons/imaging/FormatCompliance.java @@ -31,6 +31,11 @@ public class FormatCompliance { private static final Logger LOGGER = Logger.getLogger(FormatCompliance.class.getName()); + /** + * Gets the default format compliance instance. + * + * @return a default FormatCompliance instance that ignores errors. + */ public static FormatCompliance getDefault() { return new FormatCompliance("ignore", false); } @@ -40,16 +45,33 @@ public class FormatCompliance { private final List<String> comments = new ArrayList<>(); + /** + * Constructs a new FormatCompliance with the specified description. + * + * @param description the description of the format compliance. + */ public FormatCompliance(final String description) { this.description = description; this.failOnError = false; } + /** + * Constructs a new FormatCompliance with the specified description and fail-on-error flag. + * + * @param description the description of the format compliance. + * @param failOnError true to throw exceptions on errors, false to only collect comments. + */ public FormatCompliance(final String description, final boolean failOnError) { this.description = description; this.failOnError = failOnError; } + /** + * Adds a comment about a compliance issue. + * + * @param comment the comment to add. + * @throws ImagingException if failOnError is true. + */ public void addComment(final String comment) throws ImagingException { comments.add(comment); if (failOnError) { @@ -57,10 +79,27 @@ public class FormatCompliance { } } + /** + * Adds a comment about a compliance issue with a value. + * + * @param comment the comment to add. + * @param value the value associated with the comment. + * @throws ImagingException if failOnError is true. + */ public void addComment(final String comment, final int value) throws ImagingException { addComment(comment + ": " + getValueDescription(value)); } + /** + * Checks if a value is within specified bounds. + * + * @param name the name of the value being checked. + * @param min the minimum allowed value. + * @param max the maximum allowed value. + * @param actual the actual value to check. + * @return true if the value is within bounds, false otherwise. + * @throws ImagingException if failOnError is true and the check fails. + */ public boolean checkBounds(final String name, final int min, final int max, final int actual) throws ImagingException { if (actual < min || actual > max) { addComment(name + ": bounds check: " + min + " <= " + actual + " <= " + max + ": false"); @@ -70,10 +109,28 @@ public class FormatCompliance { return true; } + /** + * Compares an actual value against a valid value. + * + * @param name the name of the value being compared. + * @param valid the valid value. + * @param actual the actual value to compare. + * @return true if the actual value matches the valid value, false otherwise. + * @throws ImagingException if failOnError is true and the comparison fails. + */ public boolean compare(final String name, final int valid, final int actual) throws ImagingException { return compare(name, new int[] { valid, }, actual); } + /** + * Compares an actual value against an array of valid values. + * + * @param name the name of the value being compared. + * @param valid the array of valid values. + * @param actual the actual value to compare. + * @return true if the actual value matches any valid value, false otherwise. + * @throws ImagingException if failOnError is true and the comparison fails. + */ public boolean compare(final String name, final int[] valid, final int actual) throws ImagingException { for (final int element : valid) { if (actual == element) { @@ -101,6 +158,15 @@ public class FormatCompliance { return false; } + /** + * Compares two byte arrays for equality. + * + * @param name the name of the byte arrays being compared. + * @param expected the expected byte array. + * @param actual the actual byte array to compare. + * @return true if the arrays are equal, false otherwise. + * @throws ImagingException if failOnError is true and the comparison fails. + */ public boolean compareBytes(final String name, final byte[] expected, final byte[] actual) throws ImagingException { if (expected.length != actual.length) { addComment(name + ": Unexpected length: (expected: " + expected.length + ", actual: " + actual.length + ")"); @@ -120,6 +186,9 @@ public class FormatCompliance { return true; } + /** + * Dumps the format compliance information to the logger. + */ public void dump() { try (StringWriter sw = new StringWriter(); PrintWriter pw = new PrintWriter(sw)) { @@ -132,6 +201,11 @@ public class FormatCompliance { } } + /** + * Dumps the format compliance information to the specified PrintWriter. + * + * @param pw the PrintWriter to write to. + */ public void dump(final PrintWriter pw) { pw.println("Format Compliance: " + description); diff --git a/src/main/java/org/apache/commons/imaging/common/GenericImageMetadata.java b/src/main/java/org/apache/commons/imaging/common/GenericImageMetadata.java index c03d36c7..215cceed 100644 --- a/src/main/java/org/apache/commons/imaging/common/GenericImageMetadata.java +++ b/src/main/java/org/apache/commons/imaging/common/GenericImageMetadata.java @@ -19,22 +19,44 @@ package org.apache.commons.imaging.common; import java.util.ArrayList; import java.util.List; +/** + * Generic implementation of image metadata. + */ public class GenericImageMetadata implements ImageMetadata { + /** + * A generic image metadata item consisting of a keyword-text pair. + */ public static class GenericImageMetadataItem implements ImageMetadataItem { private final String keyword; private final String text; + /** + * Constructs a new generic image metadata item. + * + * @param keyword the metadata keyword. + * @param text the metadata text value. + */ public GenericImageMetadataItem(final String keyword, final String text) { this.keyword = keyword; this.text = text; } + /** + * Gets the keyword. + * + * @return the keyword. + */ public String getKeyword() { return keyword; } + /** + * Gets the text value. + * + * @return the text value. + */ public String getText() { return text; } @@ -58,10 +80,28 @@ public class GenericImageMetadata implements ImageMetadata { private final List<ImageMetadataItem> items = new ArrayList<>(); + /** + * Constructs a new GenericImageMetadata instance. + */ + public GenericImageMetadata() { + // Default constructor + } + + /** + * Adds a metadata item. + * + * @param item the metadata item to add. + */ public void add(final ImageMetadataItem item) { items.add(item); } + /** + * Adds a metadata item with the specified keyword and text. + * + * @param keyword the metadata keyword. + * @param text the metadata text value. + */ public void add(final String keyword, final String text) { add(new GenericImageMetadataItem(keyword, text)); } diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/constants/GeoTiffTagConstants.java b/src/main/java/org/apache/commons/imaging/formats/tiff/constants/GeoTiffTagConstants.java index 60b1812f..91b09a6b 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/constants/GeoTiffTagConstants.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/constants/GeoTiffTagConstants.java @@ -33,27 +33,35 @@ import org.apache.commons.imaging.formats.tiff.taginfos.TagInfoShorts; */ public final class GeoTiffTagConstants { + /** Model pixel scale tag. */ public static final TagInfoDoubles EXIF_TAG_MODEL_PIXEL_SCALE_TAG = new TagInfoDoubles("ModelPixelScaleTag", 0x830e, 3, TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN); + /** Intergraph matrix tag. */ public static final TagInfoDoubles EXIF_TAG_INTERGRAPH_MATRIX_TAG = new TagInfoDoubles("IntergraphMatrixTag", 0x8480, -1, TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN); + /** Model tiepoint tag. */ public static final TagInfoDoubles EXIF_TAG_MODEL_TIEPOINT_TAG = new TagInfoDoubles("ModelTiepointTag", 0x8482, -1, TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN); + /** Model transformation tag. */ public static final TagInfoDoubles EXIF_TAG_MODEL_TRANSFORMATION_TAG = new TagInfoDoubles("ModelTransformationTag", 0x85d8, 16, TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN); + /** Geo key directory tag. */ public static final TagInfoShorts EXIF_TAG_GEO_KEY_DIRECTORY_TAG = new TagInfoShorts("GeoKeyDirectoryTag", 0x87af, -1, TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN); + /** Geo double params tag. */ public static final TagInfoDoubles EXIF_TAG_GEO_DOUBLE_PARAMS_TAG = new TagInfoDoubles("GeoDoubleParamsTag", 0x87b0, -1, TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN); + /** Geo ASCII params tag. */ public static final TagInfoAscii EXIF_TAG_GEO_ASCII_PARAMS_TAG = new TagInfoAscii("GeoAsciiParamsTag", 0x87b1, -1, TiffDirectoryType.EXIF_DIRECTORY_UNKNOWN); + /** List of all GeoTIFF tags. */ public static final List<TagInfo> ALL_GEO_TIFF_TAGS = Collections .unmodifiableList(Arrays.asList(EXIF_TAG_MODEL_PIXEL_SCALE_TAG, EXIF_TAG_INTERGRAPH_MATRIX_TAG, EXIF_TAG_MODEL_TIEPOINT_TAG, EXIF_TAG_MODEL_TRANSFORMATION_TAG, EXIF_TAG_GEO_KEY_DIRECTORY_TAG, EXIF_TAG_GEO_DOUBLE_PARAMS_TAG, EXIF_TAG_GEO_ASCII_PARAMS_TAG)); diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeAscii.java b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeAscii.java index f6d3649d..982e01a6 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeAscii.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeAscii.java @@ -24,7 +24,16 @@ import org.apache.commons.imaging.ImagingException; import org.apache.commons.imaging.common.Allocator; import org.apache.commons.imaging.formats.tiff.TiffField; +/** + * TIFF field type for ASCII strings. + */ public class FieldTypeAscii extends AbstractFieldType { + /** + * Constructs a new ASCII field type. + * + * @param type the type number. + * @param name the type name. + */ public FieldTypeAscii(final int type, final String name) { super(type, name, 1); } diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeByte.java b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeByte.java index d43614c6..765b1a07 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeByte.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeByte.java @@ -21,7 +21,16 @@ import java.nio.ByteOrder; import org.apache.commons.imaging.ImagingException; import org.apache.commons.imaging.formats.tiff.TiffField; +/** + * TIFF field type for byte values. + */ public class FieldTypeByte extends AbstractFieldType { + /** + * Constructs a new byte field type. + * + * @param type the type number. + * @param name the type name. + */ public FieldTypeByte(final int type, final String name) { super(type, name, 1); } diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeDouble.java b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeDouble.java index e7afbe80..363f398e 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeDouble.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeDouble.java @@ -24,7 +24,16 @@ import org.apache.commons.imaging.common.Allocator; import org.apache.commons.imaging.common.ByteConversions; import org.apache.commons.imaging.formats.tiff.TiffField; +/** + * TIFF field type for double-precision floating point values. + */ public class FieldTypeDouble extends AbstractFieldType { + /** + * Constructs a new double field type. + * + * @param type the type number. + * @param name the type name. + */ public FieldTypeDouble(final int type, final String name) { super(type, name, 8); } diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeFloat.java b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeFloat.java index 86a7788b..a2b62dc6 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeFloat.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeFloat.java @@ -23,7 +23,16 @@ import org.apache.commons.imaging.common.Allocator; import org.apache.commons.imaging.common.ByteConversions; import org.apache.commons.imaging.formats.tiff.TiffField; +/** + * TIFF field type for single-precision floating point values. + */ public class FieldTypeFloat extends AbstractFieldType { + /** + * Constructs a new float field type. + * + * @param type the type number. + * @param name the type name. + */ public FieldTypeFloat(final int type, final String name) { super(type, name, 4); } diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeLong.java b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeLong.java index d02d66e3..887f0c75 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeLong.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeLong.java @@ -23,7 +23,16 @@ import org.apache.commons.imaging.common.Allocator; import org.apache.commons.imaging.common.ByteConversions; import org.apache.commons.imaging.formats.tiff.TiffField; +/** + * TIFF field type for 32-bit unsigned long values. + */ public class FieldTypeLong extends AbstractFieldType { + /** + * Constructs a new long field type. + * + * @param type the type number. + * @param name the type name. + */ public FieldTypeLong(final int type, final String name) { super(type, name, 4); } diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeLong8.java b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeLong8.java index 00b01ac0..9f328495 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeLong8.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeLong8.java @@ -27,6 +27,12 @@ import org.apache.commons.imaging.formats.tiff.TiffField; * Provides an implementation of the 8-byte integer field type specified by the BigTIFF extensions to the TIFF format. */ public class FieldTypeLong8 extends AbstractFieldType { + /** + * Constructs a new 64-bit long field type. + * + * @param type the type number. + * @param name the type name. + */ public FieldTypeLong8(final int type, final String name) { super(type, name, 8); } diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeRational.java b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeRational.java index 9fdf0edd..78414f3b 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeRational.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeRational.java @@ -25,7 +25,16 @@ import org.apache.commons.imaging.common.ByteConversions; import org.apache.commons.imaging.common.RationalNumber; import org.apache.commons.imaging.formats.tiff.TiffField; +/** + * TIFF field type for rational number values. + */ public class FieldTypeRational extends AbstractFieldType { + /** + * Constructs a new rational field type. + * + * @param type the type number. + * @param name the type name. + */ public FieldTypeRational(final int type, final String name) { super(type, name, 8); } diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeShort.java b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeShort.java index 9eee259d..f8b972ca 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeShort.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/fieldtypes/FieldTypeShort.java @@ -23,7 +23,16 @@ import org.apache.commons.imaging.common.Allocator; import org.apache.commons.imaging.common.ByteConversions; import org.apache.commons.imaging.formats.tiff.TiffField; +/** + * TIFF field type for 16-bit unsigned short values. + */ public class FieldTypeShort extends AbstractFieldType { + /** + * Constructs a new short field type. + * + * @param type the type number. + * @param name the type name. + */ public FieldTypeShort(final int type, final String name) { super(type, name, 2); } diff --git a/src/main/java/org/apache/commons/imaging/icc/IccProfileInfo.java b/src/main/java/org/apache/commons/imaging/icc/IccProfileInfo.java index 7c009864..493931d1 100644 --- a/src/main/java/org/apache/commons/imaging/icc/IccProfileInfo.java +++ b/src/main/java/org/apache/commons/imaging/icc/IccProfileInfo.java @@ -23,27 +23,63 @@ import java.util.logging.Logger; import org.apache.commons.imaging.ImagingException; +/** + * Provides information about an ICC color profile. + */ public class IccProfileInfo { private static final Logger LOGGER = Logger.getLogger(IccProfileInfo.class.getName()); private final byte[] data; + /** The profile size in bytes. */ public final int profileSize; + /** The CMM type signature. */ public final int cmmTypeSignature; + /** The profile version. */ public final int profileVersion; + /** The profile/device class signature. */ public final int profileDeviceClassSignature; + /** The color space signature. */ public final int colorSpace; + /** The profile connection space signature. */ public final int profileConnectionSpace; + /** The profile file signature. */ public final int profileFileSignature; + /** The primary platform signature. */ public final int primaryPlatformSignature; + /** Various profile flags. */ public final int variousFlags; + /** The device manufacturer signature. */ public final int deviceManufacturer; + /** The device model signature. */ public final int deviceModel; + /** The rendering intent. */ public final int renderingIntent; + /** The profile creator signature. */ public final int profileCreatorSignature; private final byte[] profileId; private final IccTag[] tags; + /** + * Constructs a new ICC profile information object. + * + * @param data the raw profile data. + * @param profileSize the profile size in bytes. + * @param cmmTypeSignature the CMM type signature. + * @param profileVersion the profile version. + * @param profileDeviceClassSignature the profile/device class signature. + * @param colorSpace the color space signature. + * @param profileConnectionSpace the profile connection space signature. + * @param profileFileSignature the profile file signature. + * @param primaryPlatformSignature the primary platform signature. + * @param variousFlags various profile flags. + * @param deviceManufacturer the device manufacturer signature. + * @param deviceModel the device model signature. + * @param renderingIntent the rendering intent. + * @param profileCreatorSignature the profile creator signature. + * @param profileId the profile ID. + * @param tags the ICC tags. + */ public IccProfileInfo(final byte[] data, final int profileSize, final int cmmTypeSignature, final int profileVersion, final int profileDeviceClassSignature, final int colorSpace, final int profileConnectionSpace, final int profileFileSignature, final int primaryPlatformSignature, final int variousFlags, final int deviceManufacturer, final int deviceModel, final int renderingIntent, final int profileCreatorSignature, final byte[] profileId, @@ -68,22 +104,47 @@ public class IccProfileInfo { this.tags = tags; } + /** + * Dumps the profile information to the logger. + * + * @param prefix the prefix to use for output lines. + */ public void dump(final String prefix) { LOGGER.fine(toString()); } + /** + * Gets a copy of the raw profile data. + * + * @return a copy of the profile data bytes. + */ public byte[] getData() { return data.clone(); } + /** + * Gets a copy of the profile ID. + * + * @return a copy of the profile ID bytes. + */ public byte[] getProfileId() { return profileId.clone(); } + /** + * Gets the ICC tags. + * + * @return the array of ICC tags. + */ public IccTag[] getTags() { return tags; } + /** + * Checks if this profile is an sRGB profile. + * + * @return true if this is an sRGB profile, false otherwise. + */ public boolean isSrgb() { return deviceManufacturer == IccConstants.IEC && deviceModel == IccConstants.sRGB; } @@ -101,6 +162,14 @@ public class IccProfileInfo { } } + /** + * Gets a string representation of this ICC profile information with a prefix. + * + * @param prefix the prefix to use for output lines. + * @return a string representation of the profile information. + * @throws ImagingException if an imaging error occurs. + * @throws IOException if an I/O error occurs. + */ public String toString(final String prefix) throws ImagingException, IOException { final StringWriter sw = new StringWriter(); final PrintWriter pw = new PrintWriter(sw);
