Image Processing Utilities

Application Scenarios

Preprocessing: Binarization and cropping before fractal analysis
Block Operations: Splitting images into boxes for multifractal computation
Mask Generation: Create spatial masks based on block positions
ROI Extraction: Extract regions of interest based on multifractal measure
Data Augmentation: Random patch sampling for deep learning workflows

Usage Examples

Otsu Binarization

import cv2
from FreeAeonFractal.FAImage import CFAImage

gray = cv2.imread('./images/face.png', cv2.IMREAD_GRAYSCALE)
bin_image, threshold = CFAImage.otsu_binarize(gray)
print(f"Threshold: {threshold}")

Image Blocking and Merging

import numpy as np
from FreeAeonFractal.FAImage import CFAImage

image = np.zeros((256, 256), dtype=np.uint8)

blocks, raw_blocks = CFAImage.get_boxes_from_image(image, block_size=(64, 64), corp_type=-1)
print("Blocks:", blocks.shape[0])   # 16 blocks (4x4 grid)

merged = CFAImage.get_image_from_boxes(raw_blocks)

# Zero out specific blocks
mask_pos = [(0,0), (1,1), (2,2)]
mask_image = CFAImage.get_mask_from_boxes(raw_blocks, mask_pos)
masked = (merged * mask_image).astype(np.uint8)

ROI Extraction by Multifractal q

image = cv2.imread('./images/face.png')

mask_union, masked_image = CFAImage.get_roi_by_q(
    image=image,
    q_range=(-5, 5),
    step=1.0,
    box_size=16,
    target_mass=0.90,
    combine_mode="or",
    use_grayscale_measure=True
)

Class Description

CFAImage (all static methods)

crop_data(data, block_size)

Crop H,W to multiples of block_size. Supports 2D (H,W) and 3D (H,W,C).

pad_data(data, block_size, mode="constant", constant_values=0)

Pad H,W to multiples of block_size.

otsu_binarize(img)

Automatic Otsu thresholding. Converts color to grayscale first; scales float images to [0,255]. Returns (bin_img, threshold).

get_boxes_from_image(image, block_size, corp_type=-1)

Split image into (bh,bw) blocks over spatial dims. corp_type: -1 crop, 1 pad, 0 strict. Returns (blocks_reshaped, raw_blocks):

Grayscale: (N, bh, bw) and (nY, nX, bh, bw)
Color: (N, bh, bw, C) and (nY, nX, bh, bw, C)

get_image_from_boxes(raw_blocks)

Merge raw_blocks back to image. Supports (nY,nX,bh,bw) → (H,W) and (nY,nX,bh,bw,C) → (H,W,C).

get_mask_from_boxes(raw_blocks, mask_block_pos)

Build float32 mask with 0 at block positions in mask_block_pos (list of (y,x) grid coords), 1 elsewhere.

get_random_patches(image, num_patches=100, ratio=0.25)

Sample num_patches unique-position patches of size (H*ratio, W*ratio). Raises ValueError if too many requested.

get_roi_by_q(image, q_range=(-5,5), step=1.0, box_size=16, target_mass=0.95, combine_mode="and", use_grayscale_measure=True, measure_mode="intensity_sum")

ROI via multifractal reweighting. For each q: weights wᵢ ∝ μᵢ^q, select top boxes until cumulative weight ≥ target_mass. Returns (mask_union, masked_image).

Important Notes

corp_type=-1 (crop) is most commonly used; corp_type=1 preserves all pixels but adds zeros
ROI: large positive q selects high-intensity/dense regions; large negative q selects sparse regions
Block grid: raw_blocks[y, x, ...] maps to pixels [y*bh:(y+1)*bh, x*bw:(x+1)*bw]