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 5daa869334ea1a64c1a9ebc8a1fdceed11e97b11 Author: Gary Gregory <[email protected]> AuthorDate: Fri Jan 2 22:13:43 2026 -0500 Javadoc --- .../org/apache/commons/imaging/ColorTools.java | 118 ++++++++++++++++++++- .../commons/imaging/common/BasicCParser.java | 37 ++++++- .../imaging/formats/bmp/BmpImageParser.java | 12 +++ .../imaging/formats/jpeg/segments/DqtSegment.java | 40 ++++++- .../org/apache/commons/imaging/internal/Debug.java | 19 +++- 5 files changed, 222 insertions(+), 4 deletions(-) diff --git a/src/main/java/org/apache/commons/imaging/ColorTools.java b/src/main/java/org/apache/commons/imaging/ColorTools.java index 6c2c3b68..63ac1982 100644 --- a/src/main/java/org/apache/commons/imaging/ColorTools.java +++ b/src/main/java/org/apache/commons/imaging/ColorTools.java @@ -42,6 +42,20 @@ import java.io.IOException; */ public class ColorTools { + /** + * Constructs a new ColorTools instance. + */ + public ColorTools() { + } + + /** + * Converts an image between color spaces. + * + * @param bi the source image. + * @param from the source color space. + * @param to the target color space. + * @return the converted image. + */ public BufferedImage convertBetweenColorSpaces(BufferedImage bi, final ColorSpace from, final ColorSpace to) { final RenderingHints hints = new RenderingHints(RenderingHints.KEY_RENDERING, RenderingHints.VALUE_RENDER_QUALITY); hints.put(RenderingHints.KEY_COLOR_RENDERING, RenderingHints.VALUE_COLOR_RENDER_QUALITY); @@ -56,6 +70,14 @@ public class ColorTools { return relabelColorSpace(result, to); } + /** + * Converts an image between color spaces with double conversion. + * + * @param bi the source image. + * @param from the source color space. + * @param to the target color space. + * @return the converted image. + */ public BufferedImage convertBetweenColorSpacesX2(BufferedImage bi, final ColorSpace from, final ColorSpace to) { final RenderingHints hints = new RenderingHints(RenderingHints.KEY_RENDERING, RenderingHints.VALUE_RENDER_QUALITY); hints.put(RenderingHints.KEY_COLOR_RENDERING, RenderingHints.VALUE_COLOR_RENDER_QUALITY); @@ -78,6 +100,14 @@ public class ColorTools { } + /** + * Converts an image between ICC profiles. + * + * @param bi the source image. + * @param from the source ICC profile. + * @param to the target ICC profile. + * @return the converted image. + */ public BufferedImage convertBetweenIccProfiles(final BufferedImage bi, final ICC_Profile from, final ICC_Profile to) { final ICC_ColorSpace csFrom = new ICC_ColorSpace(from); final ICC_ColorSpace csTo = new ICC_ColorSpace(to); @@ -85,11 +115,25 @@ public class ColorTools { return convertBetweenColorSpaces(bi, csFrom, csTo); } + /** + * Converts an image from a specified color space to sRGB. + * + * @param bi the source image. + * @param from the source color space. + * @return the converted image. + */ protected BufferedImage convertFromColorSpace(final BufferedImage bi, final ColorSpace from) { final ColorModel srgbCM = ColorModel.getRGBdefault(); return convertBetweenColorSpaces(bi, from, srgbCM.getColorSpace()); } + /** + * Converts an image to a specified color space. + * + * @param bi the source image. + * @param to the target color space. + * @return the converted image. + */ public BufferedImage convertToColorSpace(final BufferedImage bi, final ColorSpace to) { final ColorSpace from = bi.getColorModel().getColorSpace(); @@ -104,16 +148,38 @@ public class ColorTools { return relabelColorSpace(result, to); } + /** + * Converts an image to a specified ICC profile. + * + * @param bi the source image. + * @param to the target ICC profile. + * @return the converted image. + */ public BufferedImage convertToIccProfile(final BufferedImage bi, final ICC_Profile to) { final ICC_ColorSpace csTo = new ICC_ColorSpace(to); return convertToColorSpace(bi, csTo); } + /** + * Converts an image to sRGB color space. + * + * @param bi the source image. + * @return the converted image. + */ public BufferedImage convertTosRgb(final BufferedImage bi) { final ColorModel srgbCM = ColorModel.getRGBdefault(); return convertToColorSpace(bi, srgbCM.getColorSpace()); } + /** + * Corrects an image using the ICC profile from a file. + * + * @param src the source image. + * @param file the file containing the ICC profile. + * @return the corrected image. + * @throws ImagingException if the image format is invalid. + * @throws IOException if an I/O error occurs. + */ public BufferedImage correctImage(final BufferedImage src, final File file) throws ImagingException, IOException { final ICC_Profile icc = Imaging.getIccProfile(file); if (icc == null) { @@ -136,15 +202,41 @@ public class ColorTools { return count; } + /** + * Derives a color model with a new color space. + * + * @param bi the source image. + * @param cs the target color space. + * @return the derived color model. + * @throws ImagingOpException if the color model cannot be derived. + */ public ColorModel deriveColorModel(final BufferedImage bi, final ColorSpace cs) throws ImagingOpException { // boolean hasAlpha = (bi.getAlphaRaster() != null); return deriveColorModel(bi, cs, false); } + /** + * Derives a color model with a new color space. + * + * @param bi the source image. + * @param cs the target color space. + * @param forceNoAlpha whether to force no alpha channel. + * @return the derived color model. + * @throws ImagingOpException if the color model cannot be derived. + */ public ColorModel deriveColorModel(final BufferedImage bi, final ColorSpace cs, final boolean forceNoAlpha) throws ImagingOpException { return deriveColorModel(bi.getColorModel(), cs, forceNoAlpha); } + /** + * Derives a color model with a new color space. + * + * @param colorModel the source color model. + * @param cs the target color space. + * @param forceNoAlpha whether to force no alpha channel. + * @return the derived color model. + * @throws ImagingOpException if the color model cannot be derived. + */ public ColorModel deriveColorModel(final ColorModel colorModel, final ColorSpace cs, final boolean forceNoAlpha) throws ImagingOpException { if (colorModel instanceof ComponentColorModel) { @@ -189,6 +281,14 @@ public class ColorTools { throw new ImagingOpException("Could not clone unknown ColorModel Type."); } + /** + * Relabels a BufferedImage with a new color model. + * + * @param bi the source image. + * @param cm the new color model. + * @return the relabeled image. + * @throws ImagingOpException if the relabeling fails. + */ public BufferedImage relabelColorSpace(final BufferedImage bi, final ColorModel cm) throws ImagingOpException { // This does not do the conversion. It tries to relabel the // BufferedImage @@ -199,6 +299,14 @@ public class ColorTools { return new BufferedImage(cm, bi.getRaster(), false, null); } + /** + * Relabels a BufferedImage with a new color space. + * + * @param bi the source image. + * @param cs the new color space. + * @return the relabeled image. + * @throws ImagingOpException if the relabeling fails. + */ public BufferedImage relabelColorSpace(final BufferedImage bi, final ColorSpace cs) throws ImagingOpException { // This does not do the conversion. It tries to relabel the // BufferedImage @@ -212,10 +320,18 @@ public class ColorTools { } + /** + * Relabels a BufferedImage with a new ICC profile. + * + * @param bi the source image. + * @param profile the new ICC profile. + * @return the relabeled image. + * @throws ImagingOpException if the relabeling fails. + */ public BufferedImage relabelColorSpace(final BufferedImage bi, final ICC_Profile profile) throws ImagingOpException { final ICC_ColorSpace cs = new ICC_ColorSpace(profile); return relabelColorSpace(bi, cs); } -} +} \ No newline at end of file diff --git a/src/main/java/org/apache/commons/imaging/common/BasicCParser.java b/src/main/java/org/apache/commons/imaging/common/BasicCParser.java index da362d97..413dac92 100644 --- a/src/main/java/org/apache/commons/imaging/common/BasicCParser.java +++ b/src/main/java/org/apache/commons/imaging/common/BasicCParser.java @@ -159,6 +159,16 @@ public class BasicCParser { } + /** + * Preprocesses a C-style input stream by handling comments, strings, and directives. + * + * @param is the input stream to preprocess. + * @param firstComment StringBuilder to capture the first comment, or null to ignore. + * @param defines map to store preprocessor definitions. + * @return the preprocessed output as a ByteArrayOutputStream. + * @throws IOException if an I/O error occurs. + * @throws ImagingException if parsing fails. + */ public static ByteArrayOutputStream preprocess(final InputStream is, final StringBuilder firstComment, final Map<String, String> defines) throws IOException, ImagingException { boolean inSingleQuotes = false; @@ -339,6 +349,12 @@ public class BasicCParser { return out; } + /** + * Tokenizes a row by splitting on whitespace. + * + * @param row the row to tokenize. + * @return the array of tokens. + */ public static String[] tokenizeRow(final String row) { final String[] tokens = row.split("[ \t]"); int numLiveTokens = 0; @@ -357,6 +373,13 @@ public class BasicCParser { return liveTokens; } + /** + * Unescapes a C-style string. + * + * @param stringBuilder the builder to append unescaped characters to. + * @param string the string to unescape. + * @throws ImagingException if parsing fails. + */ public static void unescapeString(final StringBuilder stringBuilder, final String string) throws ImagingException { if (string.length() < 2) { throw new ImagingException("Parsing XPM file failed, string is too short"); @@ -385,10 +408,22 @@ public class BasicCParser { private final PushbackInputStream is; + /** + * Constructs a new BasicCParser. + * + * @param is the input stream to parse. + */ public BasicCParser(final ByteArrayInputStream is) { this.is = new PushbackInputStream(is); } + /** + * Reads the next token from the input stream. + * + * @return the next token as a string, or null if end of stream. + * @throws IOException if an I/O error occurs. + * @throws ImagingException if parsing fails. + */ public String nextToken() throws IOException, ImagingException { // I don't know how complete the C parsing in an XPM file // is meant to be, this is just the very basics... @@ -450,4 +485,4 @@ public class BasicCParser { return null; } -} +} \ No newline at end of file diff --git a/src/main/java/org/apache/commons/imaging/formats/bmp/BmpImageParser.java b/src/main/java/org/apache/commons/imaging/formats/bmp/BmpImageParser.java index db6c9b9b..0d8e0127 100644 --- a/src/main/java/org/apache/commons/imaging/formats/bmp/BmpImageParser.java +++ b/src/main/java/org/apache/commons/imaging/formats/bmp/BmpImageParser.java @@ -48,6 +48,9 @@ import org.apache.commons.imaging.common.ImageMetadata; import org.apache.commons.imaging.palette.PaletteFactory; import org.apache.commons.imaging.palette.SimplePalette; +/** + * Parser for BMP (Windows Bitmap) image format. + */ public class BmpImageParser extends AbstractImageParser<BmpImagingParameters> { private static final Logger LOGGER = Logger.getLogger(BmpImageParser.class.getName()); @@ -122,6 +125,15 @@ public class BmpImageParser extends AbstractImageParser<BmpImagingParameters> { } } + /** + * Gets a BufferedImage from an input stream. + * + * @param inputStream the input stream to read from. + * @param params the imaging parameters. + * @return the BufferedImage. + * @throws ImagingException if the image format is invalid. + * @throws IOException if an I/O error occurs. + */ public BufferedImage getBufferedImage(final InputStream inputStream, final BmpImagingParameters params) throws ImagingException, IOException { final BmpImageContents ic = readImageContents(inputStream, FormatCompliance.getDefault()); diff --git a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/DqtSegment.java b/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/DqtSegment.java index 8253aa7f..fef2397b 100644 --- a/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/DqtSegment.java +++ b/src/main/java/org/apache/commons/imaging/formats/jpeg/segments/DqtSegment.java @@ -26,12 +26,30 @@ import java.util.List; import org.apache.commons.imaging.ImagingException; +/** + * A JPEG DQT (Define Quantization Table) segment. + */ public final class DqtSegment extends AbstractSegment { + + /** + * A quantization table for JPEG compression. + */ public static class QuantizationTable { + /** The precision of the quantization table (0=8-bit, 1=16-bit). */ public final int precision; + + /** The destination identifier. */ public final int destinationIdentifier; + private final int[] elements; + /** + * Constructs a new quantization table. + * + * @param precision the precision (0=8-bit, 1=16-bit). + * @param destinationIdentifier the destination identifier. + * @param elements the quantization table elements. + */ public QuantizationTable(final int precision, final int destinationIdentifier, final int[] elements) { this.precision = precision; this.destinationIdentifier = destinationIdentifier; @@ -39,19 +57,39 @@ public final class DqtSegment extends AbstractSegment { } /** - * @return the elements + * Gets the quantization table elements. + * + * @return the elements. */ public int[] getElements() { return elements; } } + /** The list of quantization tables in this segment. */ public final List<QuantizationTable> quantizationTables = new ArrayList<>(); + /** + * Constructs a DQT segment from segment data. + * + * @param marker the segment marker. + * @param segmentData the segment data. + * @throws ImagingException if the image format is invalid. + * @throws IOException if an I/O error occurs. + */ public DqtSegment(final int marker, final byte[] segmentData) throws ImagingException, IOException { this(marker, segmentData.length, new ByteArrayInputStream(segmentData)); } + /** + * Constructs a DQT segment by reading from an input stream. + * + * @param marker the segment marker. + * @param length the segment length. + * @param is the input stream to read from. + * @throws ImagingException if the image format is invalid. + * @throws IOException if an I/O error occurs. + */ public DqtSegment(final int marker, int length, final InputStream is) throws ImagingException, IOException { super(marker, length); diff --git a/src/main/java/org/apache/commons/imaging/internal/Debug.java b/src/main/java/org/apache/commons/imaging/internal/Debug.java index 7e9f8740..f9323132 100644 --- a/src/main/java/org/apache/commons/imaging/internal/Debug.java +++ b/src/main/java/org/apache/commons/imaging/internal/Debug.java @@ -138,6 +138,12 @@ public final class Debug { debug(getDebug(message, map)); } + /** + * Logs a debug message with an object value. + * + * @param message the message prefix. + * @param value the object value to log. + */ public static void debug(final String message, final Object value) { if (value == null) { debug(message, "null"); @@ -170,10 +176,21 @@ public final class Debug { debug(message + " " + value); } + /** + * Logs a debug message for a throwable. + * + * @param e the throwable to log. + */ public static void debug(final Throwable e) { debug(getDebug(e)); } + /** + * Logs a debug message for a throwable with an integer value. + * + * @param e the throwable to log. + * @param value the integer value. + */ public static void debug(final Throwable e, final int value) { debug(getDebug(e, value)); } @@ -316,4 +333,4 @@ public final class Debug { private Debug() { } -} +} \ No newline at end of file
