Stay updated

News & Insights
functionaltransforms
utils

albumentations.augmentations.text.functional

View Source on GitHub

Functional implementations for text manipulation and rendering. This module provides utility functions for manipulating text in strings and rendering text onto images. Includes functions for word manipulation, text drawing, and handling text regions in images.

Members

delete_random_wordsfunction

delete_random_words(
    words: list[str],
    num_words: int,
    py_random: random.Random
)

Delete num_words random words from list. py_random for reproducibility. Returns joined string. Used by TextImage (deletion). Empty if num_words >= len(words). This function randomly removes words from the input list and joins the remaining words with spaces to form a new string. Args: words (list[str]): List of words to process. num_words (int): Number of words to delete. py_random (random.Random): Random number generator for reproducibility. Returns: str: New string with specified words removed. Returns empty string if num_words is greater than or equal to the length of words.

Parameters

NameTypeDefaultDescription
wordslist[str]--
num_wordsint--
py_randomrandom.Random--

swap_random_wordsfunction

swap_random_words(
    words: list[str],
    num_words: int,
    py_random: random.Random
)

Swap random pairs of words. num_words swaps; py_random. Used by TextImage (swap). Returns original if num_words 0 or list has fewer than 2 words. This function randomly selects pairs of words and swaps their positions a specified number of times. Args: words (list[str]): List of words to process. num_words (int): Number of swaps to perform. py_random (random.Random): Random number generator for reproducibility. Returns: str: New string with words swapped. If num_words is 0 or the list has fewer than 2 words, returns the original string.

Parameters

NameTypeDefaultDescription
wordslist[str]--
num_wordsint--
py_randomrandom.Random--

insert_random_stopwordsfunction

insert_random_stopwords(
    words: list[str],
    num_insertions: int,
    stopwords: tuple[str, ...] | None,
    py_random: random.Random
)

Insert random stopwords into word list. num_insertions, stopwords, py_random. Used by TextImage (insertion). Returns string with stopwords at random positions. This function randomly inserts stopwords at random positions in the list of words a specified number of times. Args: words (list[str]): List of words to process. num_insertions (int): Number of stopwords to insert. stopwords (tuple[str, ...] | None): Tuple of stopwords to choose from. If None, default stopwords will be used. py_random (random.Random): Random number generator for reproducibility. Returns: str: New string with stopwords inserted.

Parameters

NameTypeDefaultDescription
wordslist[str]--
num_insertionsint--
stopwords
One of:
  • tuple[str, ...]
  • None
--
py_randomrandom.Random--

convert_image_to_pilfunction

convert_image_to_pil(
    image: ImageType
)

Convert a NumPy array image (H,W,C) to a PIL Image. Grayscale (C=1) or RGB (C=3). Used by render_text for text drawing. Requires Pillow.

Parameters

NameTypeDefaultDescription
imageImageType--

draw_text_on_pil_imagefunction

draw_text_on_pil_image(
    pil_image: 'Image',
    metadata_list: list[dict[str, Any]]
)

Draw text on PIL image from metadata_list (bbox_coords, text, font, font_color). Mutates image. Used by render_text for grayscale and RGB. Requires Pillow.

Parameters

NameTypeDefaultDescription
pil_image'Image'--
metadata_listlist[dict[str, Any]]--

draw_text_on_multi_channel_imagefunction

draw_text_on_multi_channel_image(
    image: ImageType,
    metadata_list: list[dict[str, Any]]
)

Draw text on multi-channel image (C>3). Per-channel font_color; returns numpy array. Used by render_text when C>3. Requires Pillow.

Parameters

NameTypeDefaultDescription
imageImageType--
metadata_listlist[dict[str, Any]]--

render_textfunction

render_text(
    image: ImageType,
    metadata_list: list[dict[str, Any]],
    clear_bg: bool
)

Render text onto image from metadata_list (bbox_coords, text, font, font_color). clear_bg: inpaint first. Grayscale, RGB, multi-channel. uint8 I/O. This function draws text on an image using metadata that specifies text content, position, font, and color. It can optionally clear the background before rendering. The function handles different image types (grayscale, RGB, multi-channel). Args: image (ImageType): Image to draw text on. metadata_list (list[dict[str, Any]]): List of metadata dictionaries containing: - bbox_coords: Bounding box coordinates (x_min, y_min, x_max, y_max) - text: Text string to render - font: PIL ImageFont object - font_color: Color for the text clear_bg (bool): Whether to clear (inpaint) the background under the text. Returns: ImageType: Image with text rendered on it.

Parameters

NameTypeDefaultDescription
imageImageType--
metadata_listlist[dict[str, Any]]--
clear_bgbool--

inpaint_text_backgroundfunction

inpaint_text_background(
    image: np.ndarray,
    metadata_list: list[dict[str, Any]],
    method: int = cv2.INPAINT_TELEA
)

Inpaint (clear) regions where text will be rendered. metadata_list bbox regions; method INPAINT_TELEA or INPAINT_NS. Before render_text when clear_bg True. This function creates a clean background for text by inpainting rectangular regions specified in the metadata. It removes any existing content in those regions to provide a clean slate for rendering text. Args: image (np.ndarray): Image to inpaint. metadata_list (list[dict[str, Any]]): List of metadata dictionaries containing: - bbox_coords: Bounding box coordinates (x_min, y_min, x_max, y_max) method (int, optional): Inpainting method to use. Defaults to cv2.INPAINT_TELEA. Options include: - cv2.INPAINT_TELEA: Fast Marching Method - cv2.INPAINT_NS: Navier-Stokes method Returns: np.ndarray: Image with specified regions inpainted.

Parameters

NameTypeDefaultDescription
imagenp.ndarray--
metadata_listlist[dict[str, Any]]--
methodintcv2.INPAINT_TELEA-