Package ca.corbett.extras.image

Class ImageTextUtil

java.lang.Object
ca.corbett.extras.image.ImageTextUtil
public class ImageTextUtil extends Object
Contains utility method for drawing stylized text onto a BufferedImage. Absorbed into sc-util as per UTIL-143.
Since:
2023-11-11
Author:
scorbo2

  • Field Details

    • DEFAULT_LINE_LENGTH

      public static final int DEFAULT_LINE_LENGTH
      See Also:

    • DEFAULT_FONT

      public static final Font DEFAULT_FONT

    • DEFAULT_FILL_COLOR

      public static final Color DEFAULT_FILL_COLOR

    • DEFAULT_OUTLINE_COLOR

      public static final Color DEFAULT_OUTLINE_COLOR

    • DEFAULT_OUTLINE_WIDTH_FACTOR

      public static final float DEFAULT_OUTLINE_WIDTH_FACTOR
      See Also:

    • DEFAULT_MAX_SIZE_TO_FIT_PERCENT

      public static final double DEFAULT_MAX_SIZE_TO_FIT_PERCENT
      See Also:

    • DEFAULT_MIN_FONT_SIZE

      public static final int DEFAULT_MIN_FONT_SIZE
      See Also:

  • Constructor Details

    • ImageTextUtil

      protected ImageTextUtil()
      Protected constructor to allow subclassing for application-specific utility methods while preventing direct instantiation of this utility class.

  • Method Details

    • drawText

      public static void drawText(BufferedImage image, String text)
      Shorthand for drawing text on an image with all default settings. The text will be centered in the image horizontally and vertically and will be line wrapped as needed.
      Parameters:
      image - The image on which to draw.
      text - The text to be rendered.

    • drawText

      public static void drawText(BufferedImage image, String text, Font font, Color outlineColor, Color fillColor)
      Shorthand for drawing text on an image with the given font styling properties. The text will be centered within the image vertically and horizontally and will be line wrapped as needed.
      Parameters:
      image - The BufferedImage on which the text will be drawn.
      text - The text to be drawn. Can be arbitrarily long; linewrapping will be applied.
      font - The font to use.
      outlineColor - The Color to use for outlining the text (if necessary).
      fillColor - The color to use to fill the text.

    • drawText

      public static void drawText(BufferedImage image, String text, Font font, Color outlineColor, Color fillColor, ImageTextUtil.TextAlign align)
      Shorthand for drawing text on an image with the given font styling properties and alignment. The text will be line wrapped as needed.
      Parameters:
      image - The BufferedImage on which the text will be drawn.
      text - The text to be drawn. Can be arbitrarily long; linewrapping will be applied.
      font - The font to use.
      outlineColor - The Color to use for outlining the text (if necessary).
      fillColor - The color to use to fill the text.
      align - The desired alignment for the text within the image.

    • drawText

      public static void drawText(BufferedImage image, String text, int lineLength, Font font, ImageTextUtil.TextAlign align, Color outlineColor, float outlineWidthFactor, Color fillColor)
      Outputs the given lines of text using the given styling parameters. Text will be line wrapped and scaled as needed to fit in the image.
      Parameters:
      image - The BufferedImage on which the text will be drawn.
      text - The text to be drawn. Can be arbitrarily long; linewrapping will be applied.
      lineLength - The desired length of each line. Will be adjusted based on image dimensions.
      font - The font to use.
      align - A TextAlign value for placing the text within our rectangle.
      outlineColor - The Color to use for outlining the text (if necessary).
      outlineWidthFactor - fontPointSize/outlineWidthFactor determines thickness of text border.
      fillColor - The color to use to fill the text.

    • drawText

      public static void drawText(BufferedImage image, String text, int lineLength, Font font, ImageTextUtil.TextAlign align, Color outlineColor, float outlineWidthFactor, Color fillColor, double maxSizeToFitPercent)
      Outputs the given lines of text using the given styling parameters. Text will be line wrapped and scaled as needed to fit in the image.
      Parameters:
      image - The BufferedImage on which the text will be drawn.
      text - The text to be drawn. Can be arbitrarily long; linewrapping will be applied.
      lineLength - The desired length of each line. Will be adjusted based on image dimensions.
      font - The font to use.
      align - A TextAlign value for placing the text within our rectangle.
      outlineColor - The Color to use for outlining the text (if necessary).
      outlineWidthFactor - fontPointSize/outlineWidthFactor determines thickness of text border.
      fillColor - The color to use to fill the text.
      maxSizeToFitPercent - The percentage of the boundary that the text should fit within (e.g., 0.9 for 90%).
      Throws:
      IllegalArgumentException - if maxSizeToFitPercent is not between 0.1 and 1.0 (inclusive).

    • drawText

      public static void drawText(BufferedImage image, String text, int lineLength, Font font, ImageTextUtil.TextAlign align, Color outlineColor, float outlineWidthFactor, Color fillColor, double maxSizeToFitPercent, int minFontSize)
      Outputs the given lines of text using the given styling parameters. Text will be line wrapped and scaled as needed to fit in the image.
      Parameters:
      image - The BufferedImage on which the text will be drawn.
      text - The text to be drawn. Can be arbitrarily long; linewrapping will be applied.
      lineLength - The desired length of each line. Will be adjusted based on image dimensions.
      font - The font to use.
      align - A TextAlign value for placing the text within our rectangle.
      outlineColor - The Color to use for outlining the text (if necessary).
      outlineWidthFactor - fontPointSize/outlineWidthFactor determines thickness of text border.
      fillColor - The color to use to fill the text.
      maxSizeToFitPercent - The percentage of the boundary that the text should fit within (e.g., 0.9 for 90%).
      minFontSize - The minimum font size to use, preventing text from becoming too small.
      Throws:
      IllegalArgumentException - if minFontSize is <= 0 or maxSizeToFitPercent is not between 0.1 and 1.0 (inclusive).

    • drawText

      public static void drawText(BufferedImage image, String text, int lineLength, Font font, ImageTextUtil.TextAlign align, Color outlineColor, float outlineWidthFactor, Color fillColor, BufferedImage fillTexture, Rectangle rect)
      Outputs the given lines of text using the given styling parameters and the given placement rectangle. Text will be line wrapped and scaled as needed to fit in the given Rectangle.
      Parameters:
      image - The BufferedImage on which the text will be drawn.
      text - The text to be drawn. Can be arbitrarily long; linewrapping will be applied.
      lineLength - The desired length of each line. Will be adjusted based on image dimensions.
      font - The font to use.
      align - A TextAlign value for placing the text within our rectangle.
      outlineColor - The Color to use for outlining the text (if necessary).
      outlineWidthFactor - fontPointSize/outlineWidthFactor determines thickness of text border.
      fillColor - The color to use to fill the text.
      fillTexture - An image to use to fill text (if fillColor is null, otherwise ignored).
      rect - The Rectangle in image coordinates in which the text will be drawn.

    • drawText

      public static void drawText(BufferedImage image, String text, int lineLength, Font font, ImageTextUtil.TextAlign align, Color outlineColor, float outlineWidthFactor, Color fillColor, BufferedImage fillTexture, Rectangle rect, double maxSizeToFitPercent, int minFontSize)
      Outputs the given lines of text using the given styling parameters and the given placement rectangle. Text will be line wrapped and scaled as needed to fit in the given Rectangle.
      Parameters:
      image - The BufferedImage on which the text will be drawn.
      text - The text to be drawn. Can be arbitrarily long; linewrapping will be applied.
      lineLength - The desired length of each line. Will be adjusted based on image dimensions.
      font - The font to use.
      align - A TextAlign value for placing the text within our rectangle.
      outlineColor - The Color to use for outlining the text (if necessary).
      outlineWidthFactor - fontPointSize/outlineWidthFactor determines thickness of text border.
      fillColor - The color to use to fill the text.
      fillTexture - An image to use to fill text (if fillColor is null, otherwise ignored).
      rect - The Rectangle in image coordinates in which the text will be drawn.
      maxSizeToFitPercent - The percentage of the boundary that the text should fit within (e.g., 0.9 for 90%).
      minFontSize - The minimum font size to use, preventing text from becoming too small.
      Throws:
      IllegalArgumentException - if minFontSize is <= 0 or maxSizeToFitPercent is not between 0.1 and 1.0 (inclusive).

    • adjustLineWrapLength

      protected static int adjustLineWrapLength(int initialLength, int imageWidth, int imageHeight)
      Adjusts the line wrap length based on the image aspect ratio. Wide images can have more characters per line, narrow images have less space for text.
      Parameters:
      initialLength - The initial line length to be adjusted.
      imageWidth - The width of the image.
      imageHeight - The height of the image.
      Returns:
      The adjusted line length based on the image aspect ratio.

    • handleLineWrap

      protected static List<String> handleLineWrap(String text, int lineLength)
      Invoked internally to break up a single long line into multiple short lines, if necessary. The given lineLength is used as a guide to determine how long a line must be before it is split, but the actual split point may vary, as we try to only split a line on a space character to avoid wrapping a line in the middle of a word. If the given text is shorter than the given lineLength, then the returned array will contain just that one string.
      Parameters:
      text - The text to be split up (if needed).
      lineLength - The length at which the given text will be split.
      Returns:
      A List containing one or more lines generated from the line wrapping.

    • handleLineWrap

      protected static List<String> handleLineWrap(List<String> lines, String text, int lineLength)
      Invoked internally to recurse and handle line wrapping as needed. See handleLineWrap(String,int)
      Parameters:
      lines - A List of Strings which will be added to as needed.
      text - The remaining text to be split.
      lineLength - The length at which the line will be line-wrapped.
      Returns:
      The modified input List.

    • computeFontSize

      protected static int computeFontSize(Font font, List<String> text, Graphics2D g, int left, int top, int right, int bottom)
      Invoked internally to determine the smallest font point size that will allow the given text to fit comfortably inside the given pixel boundary. Uses DEFAULT_MAX_SIZE_TO_FIT_PERCENT and DEFAULT_MIN_FONT_SIZE as defaults. Very very long lines will therefore overflow if line wrapping has not been performed.
      Parameters:
      font - The font to use for calculation purposes.
      text - The block of text in question.
      g - A Graphics object which will be used to retrieve font metrics.
      left - The left edge of the text zone.
      top - The top edge of the text zone.
      right - The right edge of the text zone.
      bottom - The bottom edge of the text zone.
      Returns:
      A font point size appropriate for the given text in the given boundary.

    • computeFontSize

      protected static int computeFontSize(Font font, List<String> text, Graphics2D g, int left, int top, int right, int bottom, double maxSizeToFitPercent, int minFontSize)
      Invoked internally to determine the smallest font point size that will allow the given text to fit comfortably inside the given pixel boundary. A minimum font point size is used to prevent text from getting too small to see. Very very long lines will therefore overflow if line wrapping has not been performed.
      Parameters:
      font - The font to use for calculation purposes.
      text - The block of text in question.
      g - A Graphics object which will be used to retrieve font metrics.
      left - The left edge of the text zone.
      top - The top edge of the text zone.
      right - The right edge of the text zone.
      bottom - The bottom edge of the text zone.
      maxSizeToFitPercent - The percentage of the boundary that the text should fit within (e.g., 0.9 for 90%).
      minFontSize - The minimum font size to use, preventing text from becoming too small.
      Returns:
      A font point size appropriate for the given text in the given boundary.

    • findLongestLine

      protected static String findLongestLine(List<String> lines)