tessl/pypi-keras-preprocessing
Easy data preprocessing and data augmentation for deep learning models
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
image-processing.mddocs/
Image Processing
Comprehensive image data augmentation, loading, and preprocessing utilities for computer vision models. These tools provide data generators, transformation functions, file utilities, and multiple data source iterators for efficient batch processing of image data.
Capabilities
Image Data Generator
The main class for image data augmentation and batch generation with real-time transformations.
class ImageDataGenerator:
"""
Generate batches of tensor image data with real-time data augmentation.
Provides comprehensive image augmentation pipeline with rotation, shifting,
scaling, flipping, and other transformations applied on-the-fly during training.
"""
def __init__(self, featurewise_center=False, samplewise_center=False,
featurewise_std_normalization=False, samplewise_std_normalization=False,
zca_whitening=False, rotation_range=0., width_shift_range=0.,
height_shift_range=0., brightness_range=None, shear_range=0.,
zoom_range=0., channel_shift_range=0., fill_mode='nearest',
cval=0., horizontal_flip=False, vertical_flip=False,
rescale=None, preprocessing_function=None, data_format='channels_last',
validation_split=0., **kwargs):
"""
Initialize ImageDataGenerator with augmentation parameters.
Parameters:
- featurewise_center (bool): Set input mean to 0 over dataset
- samplewise_center (bool): Set each sample mean to 0
- featurewise_std_normalization (bool): Divide inputs by std of dataset
- samplewise_std_normalization (bool): Divide each input by its std
- zca_whitening (bool): Apply ZCA whitening
- rotation_range (float): Degree range for random rotations
- width_shift_range (float): Range for random horizontal shifts
- height_shift_range (float): Range for random vertical shifts
- brightness_range (tuple, optional): Range for brightness adjustment
- shear_range (float): Shear intensity
- zoom_range (float or tuple): Range for random zoom
- channel_shift_range (float): Range for random channel shifts
- fill_mode (str): Points outside boundaries filled according to mode
- cval (float): Value used for points outside boundaries when fill_mode='constant'
- horizontal_flip (bool): Randomly flip inputs horizontally
- vertical_flip (bool): Randomly flip inputs vertically
- rescale (float, optional): Rescaling factor
- preprocessing_function (callable, optional): Function applied to each input
- data_format (str): 'channels_first' or 'channels_last'
- validation_split (float): Fraction of data reserved for validation
"""
def flow(self, x, y=None, batch_size=32, shuffle=True, sample_weight=None,
seed=None, save_to_dir=None, save_prefix='', save_format='png',
subset=None):
"""
Create NumpyArrayIterator from numpy arrays.
Parameters:
- x (numpy.ndarray): Input data array
- y (numpy.ndarray, optional): Target data array
- batch_size (int): Size of batches
- shuffle (bool): Whether to shuffle data
- sample_weight (numpy.ndarray, optional): Sample weights
- seed (int, optional): Random seed
- save_to_dir (str, optional): Directory to save augmented images
- save_prefix (str): Prefix for saved images
- save_format (str): Format for saved images
- subset (str, optional): 'training' or 'validation'
Returns:
- NumpyArrayIterator: Iterator yielding batches
"""
def flow_from_directory(self, directory, target_size=(256, 256),
color_mode='rgb', classes=None, class_mode='categorical',
batch_size=32, shuffle=True, seed=None, save_to_dir=None,
save_prefix='', save_format='png', follow_links=False,
subset=None, interpolation='nearest'):
"""
Create DirectoryIterator from directory structure.
Parameters:
- directory (str): Path to target directory
- target_size (tuple): Size to resize images
- color_mode (str): 'grayscale', 'rgb', or 'rgba'
- classes (list, optional): List of class subdirectories
- class_mode (str): 'categorical', 'binary', 'sparse', 'input', or None
- batch_size (int): Size of batches
- shuffle (bool): Whether to shuffle data
- seed (int, optional): Random seed
- save_to_dir (str, optional): Directory to save augmented images
- save_prefix (str): Prefix for saved images
- save_format (str): Format for saved images
- follow_links (bool): Whether to follow symlinks
- subset (str, optional): 'training' or 'validation'
- interpolation (str): Interpolation method for resizing
Returns:
- DirectoryIterator: Iterator yielding batches from directory
"""
def flow_from_dataframe(self, dataframe, directory=None, x_col="filename",
y_col="class", weight_col=None, target_size=(256, 256),
color_mode='rgb', classes=None, class_mode='categorical',
batch_size=32, shuffle=True, seed=None, save_to_dir=None,
save_prefix='', save_format='png', subset=None,
interpolation='nearest', validate_filenames=True):
"""
Create DataFrameIterator from pandas DataFrame.
Parameters:
- dataframe (pandas.DataFrame): DataFrame containing image paths and labels
- directory (str, optional): Directory containing images
- x_col (str): Column containing image filenames
- y_col (str): Column containing class labels
- weight_col (str, optional): Column containing sample weights
- target_size (tuple): Size to resize images
- color_mode (str): 'grayscale', 'rgb', or 'rgba'
- classes (list, optional): List of class names
- class_mode (str): 'categorical', 'binary', 'sparse', 'input', or None
- batch_size (int): Size of batches
- shuffle (bool): Whether to shuffle data
- seed (int, optional): Random seed
- save_to_dir (str, optional): Directory to save augmented images
- save_prefix (str): Prefix for saved images
- save_format (str): Format for saved images
- subset (str, optional): 'training' or 'validation'
- interpolation (str): Interpolation method for resizing
- validate_filenames (bool): Whether to validate image files exist
Returns:
- DataFrameIterator: Iterator yielding batches from DataFrame
"""
def standardize(self, x):
"""
Apply normalization configuration to batch of inputs.
Parameters:
- x (numpy.ndarray): Batch of inputs to standardize
Returns:
- numpy.ndarray: Standardized batch
"""
def get_random_transform(self, img_shape, seed=None):
"""
Generate random transform parameters for single image.
Parameters:
- img_shape (tuple): Shape of image
- seed (int, optional): Random seed
Returns:
- dict: Transform parameters
"""
def apply_transform(self, x, transform_parameters):
"""
Apply transformation to image with given parameters.
Parameters:
- x (numpy.ndarray): Image to transform
- transform_parameters (dict): Transform parameters
Returns:
- numpy.ndarray: Transformed image
"""
def random_transform(self, x, seed=None):
"""
Apply random transformation to single image.
Parameters:
- x (numpy.ndarray): Image to transform
- seed (int, optional): Random seed
Returns:
- numpy.ndarray: Randomly transformed image
"""
def fit(self, x, augment=False, rounds=1, seed=None):
"""
Fit data generator to sample data for normalization.
Parameters:
- x (numpy.ndarray): Sample data
- augment (bool): Whether to use augmentation for fitting
- rounds (int): Number of rounds for augmentation
- seed (int, optional): Random seed
"""Iterator Classes
Base and specialized iterator classes for different data sources.
class Iterator:
"""
Base class for image data iterators.
Provides common functionality for batch generation, shuffling, and indexing.
"""
def __init__(self, n, batch_size, shuffle, seed):
"""
Initialize iterator.
Parameters:
- n (int): Total number of samples
- batch_size (int): Size of batches
- shuffle (bool): Whether to shuffle data
- seed (int, optional): Random seed
"""
class DirectoryIterator(Iterator):
"""
Iterator capable of reading images from directory on disk.
Automatically infers class labels from subdirectory structure. Supports
various image formats and provides file path access.
"""
def __init__(self, directory, image_data_generator, target_size=(256, 256),
color_mode='rgb', classes=None, class_mode='categorical',
batch_size=32, shuffle=True, seed=None, data_format='channels_last',
save_to_dir=None, save_prefix='', save_format='png',
follow_links=False, subset=None, interpolation='nearest',
dtype='float32'):
"""Initialize DirectoryIterator with directory path and parameters."""
@property
def filepaths(self):
"""Get list of absolute file paths."""
@property
def labels(self):
"""Get array of class labels."""
@property
def sample_weight(self):
"""Get array of sample weights."""
class DataFrameIterator(Iterator):
"""
Iterator capable of reading images from directory through dataframe.
Uses pandas DataFrame to specify image paths and labels, providing
flexible data organization beyond directory structure.
"""
@property
def filepaths(self):
"""Get list of absolute file paths."""
@property
def labels(self):
"""Get array of class labels."""
@property
def sample_weight(self):
"""Get array of sample weights."""
class NumpyArrayIterator(Iterator):
"""
Iterator yielding data from numpy array.
Provides batching and augmentation for in-memory numpy arrays,
supporting both image data and labels.
"""
def __init__(self, x, y, image_data_generator, batch_size=32, shuffle=False,
sample_weight=None, seed=None, data_format='channels_last',
save_to_dir=None, save_prefix='', save_format='png',
subset=None, dtype='float32'):
"""Initialize NumpyArrayIterator with numpy arrays and parameters."""Image Utility Functions
Core utilities for image loading, saving, and format conversion.
def load_img(path, grayscale=False, color_mode='rgb', target_size=None,
interpolation='nearest'):
"""
Load image into PIL format.
Parameters:
- path (str): Path to image file
- grayscale (bool): Whether to load as grayscale (deprecated, use color_mode)
- color_mode (str): 'grayscale', 'rgb', or 'rgba'
- target_size (tuple, optional): Size to resize to (width, height)
- interpolation (str): Interpolation method ('nearest', 'bilinear', etc.)
Returns:
- PIL.Image: Loaded image
"""
def save_img(path, x, data_format='channels_last', file_format=None,
scale=True, **kwargs):
"""
Save numpy array as image to path or file object.
Parameters:
- path (str): Path to save image
- x (numpy.ndarray): Image array to save
- data_format (str): 'channels_first' or 'channels_last'
- file_format (str, optional): Format to save as
- scale (bool): Whether to scale values to 0-255 range
- **kwargs: Additional arguments passed to PIL.Image.save()
"""
def img_to_array(img, data_format='channels_last', dtype='float32'):
"""
Convert PIL Image instance to numpy array.
Parameters:
- img (PIL.Image): PIL Image to convert
- data_format (str): 'channels_first' or 'channels_last'
- dtype (str): Data type for output array
Returns:
- numpy.ndarray: Image as numpy array
"""
def array_to_img(x, data_format='channels_last', scale=True, dtype='float32'):
"""
Convert 3D numpy array to PIL Image instance.
Parameters:
- x (numpy.ndarray): Array to convert
- data_format (str): 'channels_first' or 'channels_last'
- scale (bool): Whether to scale from [0,1] to [0,255]
- dtype (str): Data type of input array
Returns:
- PIL.Image: Converted image
"""
def list_pictures(directory, ext=('jpg', 'jpeg', 'bmp', 'png', 'ppm', 'tif', 'tiff')):
"""
List all pictures in directory including subdirectories.
Parameters:
- directory (str): Directory path to search
- ext (tuple): Tuple of valid image extensions
Returns:
- list: List of image file paths
"""
def validate_filename(filename, white_list_formats):
"""
Check if filename refers to valid image file.
Parameters:
- filename (str): Filename to validate
- white_list_formats (set): Set of allowed file extensions
Returns:
- bool: True if filename is valid image file
"""Image Transformation Functions
Low-level transformation functions for image augmentation.
def flip_axis(x, axis):
"""
Flip array along specified axis.
Parameters:
- x (numpy.ndarray): Array to flip
- axis (int): Axis along which to flip
Returns:
- numpy.ndarray: Flipped array
"""
def random_rotation(x, rg, row_axis=1, col_axis=2, channel_axis=0,
fill_mode='nearest', cval=0., interpolation_order=1):
"""
Perform random rotation of numpy image tensor.
Parameters:
- x (numpy.ndarray): Image tensor
- rg (float): Rotation range in degrees
- row_axis (int): Index of axis for rows
- col_axis (int): Index of axis for columns
- channel_axis (int): Index of axis for channels
- fill_mode (str): Points outside boundaries filled according to mode
- cval (float): Value for points outside boundaries when fill_mode='constant'
- interpolation_order (int): Order of spline interpolation
Returns:
- numpy.ndarray: Rotated image tensor
"""
def random_shift(x, wrg, hrg, row_axis=1, col_axis=2, channel_axis=0,
fill_mode='nearest', cval=0., interpolation_order=1):
"""
Perform random spatial shift of numpy image tensor.
Parameters:
- x (numpy.ndarray): Image tensor
- wrg (float): Width shift range (fraction of total width)
- hrg (float): Height shift range (fraction of total height)
- row_axis (int): Index of axis for rows
- col_axis (int): Index of axis for columns
- channel_axis (int): Index of axis for channels
- fill_mode (str): Points outside boundaries filled according to mode
- cval (float): Value for points outside boundaries when fill_mode='constant'
- interpolation_order (int): Order of spline interpolation
Returns:
- numpy.ndarray: Shifted image tensor
"""
def random_shear(x, intensity, row_axis=1, col_axis=2, channel_axis=0,
fill_mode='nearest', cval=0., interpolation_order=1):
"""
Perform random spatial shear of numpy image tensor.
Parameters:
- x (numpy.ndarray): Image tensor
- intensity (float): Shear intensity
- row_axis (int): Index of axis for rows
- col_axis (int): Index of axis for columns
- channel_axis (int): Index of axis for channels
- fill_mode (str): Points outside boundaries filled according to mode
- cval (float): Value for points outside boundaries when fill_mode='constant'
- interpolation_order (int): Order of spline interpolation
Returns:
- numpy.ndarray: Sheared image tensor
"""
def random_zoom(x, zoom_range, row_axis=1, col_axis=2, channel_axis=0,
fill_mode='nearest', cval=0., interpolation_order=1):
"""
Perform random spatial zoom of numpy image tensor.
Parameters:
- x (numpy.ndarray): Image tensor
- zoom_range (tuple): Range for random zoom (zoom_min, zoom_max)
- row_axis (int): Index of axis for rows
- col_axis (int): Index of axis for columns
- channel_axis (int): Index of axis for channels
- fill_mode (str): Points outside boundaries filled according to mode
- cval (float): Value for points outside boundaries when fill_mode='constant'
- interpolation_order (int): Order of spline interpolation
Returns:
- numpy.ndarray: Zoomed image tensor
"""
def apply_channel_shift(x, intensity, channel_axis=0):
"""
Perform channel shift.
Parameters:
- x (numpy.ndarray): Image tensor
- intensity (float): Shift intensity
- channel_axis (int): Index of axis for channels
Returns:
- numpy.ndarray: Channel-shifted image tensor
"""
def random_channel_shift(x, intensity_range, channel_axis=0):
"""
Perform random channel shift.
Parameters:
- x (numpy.ndarray): Image tensor
- intensity_range (float): Range for random channel shift
- channel_axis (int): Index of axis for channels
Returns:
- numpy.ndarray: Channel-shifted image tensor
"""
def apply_brightness_shift(x, brightness):
"""
Perform brightness shift.
Parameters:
- x (numpy.ndarray): Image tensor
- brightness (float): Brightness shift value
Returns:
- numpy.ndarray: Brightness-adjusted image tensor
"""
def random_brightness(x, brightness_range):
"""
Perform random brightness shift.
Parameters:
- x (numpy.ndarray): Image tensor
- brightness_range (tuple): Range for brightness adjustment (min, max)
Returns:
- numpy.ndarray: Brightness-adjusted image tensor
"""
def apply_affine_transform(x, theta=0, tx=0, ty=0, shear=0, zx=1, zy=1,
row_axis=0, col_axis=1, channel_axis=2,
fill_mode='nearest', cval=0., order=1):
"""
Apply affine transformation specified by parameters.
Parameters:
- x (numpy.ndarray): Image tensor
- theta (float): Rotation angle in degrees
- tx (float): Translation in x direction
- ty (float): Translation in y direction
- shear (float): Shear angle in degrees
- zx (float): Zoom factor along x axis
- zy (float): Zoom factor along y axis
- row_axis (int): Index of axis for rows
- col_axis (int): Index of axis for columns
- channel_axis (int): Index of axis for channels
- fill_mode (str): Points outside boundaries filled according to mode
- cval (float): Value for points outside boundaries when fill_mode='constant'
- order (int): Order of spline interpolation
Returns:
- numpy.ndarray: Transformed image tensor
"""
def transform_matrix_offset_center(matrix, x, y):
"""
Offset transformation matrix to center.
Parameters:
- matrix (numpy.ndarray): Transformation matrix
- x (float): Center x coordinate
- y (float): Center y coordinate
Returns:
- numpy.ndarray: Offset transformation matrix
"""Usage Examples
Basic Image Data Generation
from keras_preprocessing.image import ImageDataGenerator
# Create generator with augmentation
datagen = ImageDataGenerator(
rotation_range=20,
width_shift_range=0.2,
height_shift_range=0.2,
shear_range=0.15,
zoom_range=0.15,
horizontal_flip=True,
brightness_range=[0.8, 1.2],
fill_mode='nearest'
)
# Load data from directory
train_generator = datagen.flow_from_directory(
'data/train/',
target_size=(224, 224),
batch_size=32,
class_mode='categorical',
shuffle=True
)
print(f"Found {train_generator.samples} images belonging to {train_generator.num_classes} classes")Working with Numpy Arrays
import numpy as np
from keras_preprocessing.image import ImageDataGenerator
# Sample image data (1000 images, 64x64 pixels, 3 channels)
x_train = np.random.randint(0, 256, (1000, 64, 64, 3))
y_train = np.random.randint(0, 10, (1000,))
# Create generator
datagen = ImageDataGenerator(
rescale=1./255,
rotation_range=10,
horizontal_flip=True
)
# Fit to data for normalization
datagen.fit(x_train)
# Create iterator
train_iterator = datagen.flow(
x_train, y_train,
batch_size=32,
shuffle=True
)
# Get batch
batch_x, batch_y = next(train_iterator)
print(f"Batch shape: {batch_x.shape}") # (32, 64, 64, 3)Using DataFrames
import pandas as pd
from keras_preprocessing.image import ImageDataGenerator
# Create DataFrame with image paths and labels
df = pd.DataFrame({
'filename': ['img1.jpg', 'img2.jpg', 'img3.jpg'],
'class': ['cat', 'dog', 'cat']
})
# Create generator
datagen = ImageDataGenerator(rescale=1./255)
# Flow from DataFrame
generator = datagen.flow_from_dataframe(
dataframe=df,
directory='images/',
x_col='filename',
y_col='class',
target_size=(150, 150),
batch_size=20,
class_mode='categorical'
)Manual Image Processing
from keras_preprocessing.image import load_img, img_to_array, array_to_img
import numpy as np
# Load and preprocess single image
img = load_img('path/to/image.jpg', target_size=(224, 224))
img_array = img_to_array(img)
img_array = np.expand_dims(img_array, axis=0) # Add batch dimension
print(f"Image shape: {img_array.shape}") # (1, 224, 224, 3)
# Apply transformations manually
from keras_preprocessing.image import random_rotation
augmented = random_rotation(img_array[0], 15)
# Convert back to PIL Image
result_img = array_to_img(augmented)
result_img.save('augmented_image.jpg')Validation Split
# Use validation split for train/val separation
datagen = ImageDataGenerator(
rescale=1./255,
validation_split=0.2 # 20% for validation
)
# Training generator
train_generator = datagen.flow_from_directory(
'data/',
target_size=(150, 150),
batch_size=32,
class_mode='categorical',
subset='training' # Use training subset
)
# Validation generator
validation_generator = datagen.flow_from_directory(
'data/',
target_size=(150, 150),
batch_size=32,
class_mode='categorical',
subset='validation' # Use validation subset
)Install with Tessl CLI
npx tessl i tessl/pypi-keras-preprocessing