You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by gg...@apache.org on 2026/01/04 15:25:35 UTC
(commons-imaging) 04/43: Javadoc
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 <ga...@gmail.com>
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