easy-image-model 0.1.2

Easy PyTorch image classification library

Easy Image Model

by Harrison Hensarling

Easy Image Model is a lightweight Python library for quickly building, training, and evaluating image classification models using PyTorch. It is designed for simplicity and ease of use. Supports:

-small datasets

-non-normalized images

-batch training

---

Features

• Create a custom neural network with any number of hidden layers and nodes.
• Train models on folders of labeled images (each folder represents a category).
• Batch training for faster convergence.
• Automatically preprocesses images (resizing, normalization) — no manual preprocessing required except for labeling.
• Evaluate a single image and return category probabilities.
• Save and reload model weights as JSON for portability.
• Customizable image input size (default 224x224, can be adjusted for your dataset).
• Supported image types:
  • .jpg
  • .jpeg
  • .png
  • .bmp
  • .gif (only first frame is used)
  • .tif
  • .tiff
  • More supported but untested

---

Installation

pip install easy-image-model

Or for development:

git clone https://github.com/hhensar/easy-image-model.git
cd easy-image-model
pip install -e ".[dev]"

---

Example Usage

from easy_image_model import create_model, train_model_batch_folders, evaluate_model

# Define categories
categories = ['Eagles', 'Penguins', 'Owls', 'Others']

# Create model with hidden layers (3 layers with 512, 256, 128 nodes)
# img_size defaults to 224, but can be customized (e.g., 128, 256, 512)
model = create_model([512, 256, 128], categories, img_size=224)

# Train on folders (each folder contains images of one category)
folder_paths = {
    'Eagles': 'dataset/Eagles',
    'Penguins': 'dataset/Penguins',
    'Owls': 'dataset/Owls',
    'Others': 'dataset/Others'
}
model = train_model_batch_folders(model, folder_paths, batch_size=4, epochs=5)

# Evaluate a single image
result = evaluate_model(model, 'test_images/test1.jpg')
print(result)

Example Output:

{'Eagles': 0.87, 
 'Penguins': 0.05, 
 'Owls': 0.23, 
 'Others': 0.1}

Documentation

Functions

create_model(layers, categories, img_size=224, channels=3)

Creates a new image classification model.

Parameters

• layers (list[int])
  List of positive integers specifying the hidden layer sizes.

• categories (list[str])
  List of unique category names for classification.

• img_size (int, optional)
  Image size (default: 224). Images are resized to img_size × img_size.

• channels (int, optional)
  Number of image channels (default: 3).

Returns

• dict
  Model configuration object used for training and evaluation.

Raises

• ValueError if layers or categories are invalid.

---

train_model(model, img_path, labels, lr=1e-4)

Trains the model on a single image with the provided labels.

Parameters

• model (dict)
  Model configuration returned by create_model.

• img_path (str)
  Path to the image file.

• labels (list[str])
  List of category labels associated with the image.

• lr (float, optional)
  Learning rate (default: 1e-4).

Returns

• dict
  Updated model configuration after training.

Raises

• ValueError if the model is invalid.
• FileNotFoundError if img_path does not exist.

---

train_model_batch_folders(model, folder_paths, batch_size=4, epochs=5, lr=1e-4)

Trains the model using batches of images from folders, where each folder represents a category.

Parameters

• model (dict)
  Model configuration returned by create_model.

• folder_paths (dict[str, str])
  Mapping of category names to folder paths containing images.

• batch_size (int, optional)
  Number of images per batch (default: 4).

• epochs (int, optional)
  Number of training epochs (default: 5).

• lr (float, optional)
  Learning rate (default: 1e-4).

Returns

• dict
  Updated model configuration after training.

Raises

• ValueError if inputs are invalid.
• FileNotFoundError if any folder paths do not exist.

---

evaluate_model(model, img_path)

Evaluates the model on a single image and returns classification probabilities.

Parameters

• model (dict)
  Trained model configuration.

• img_path (str)
  Path to the image file.

Returns

• dict[str, float]
  Mapping of category names to probability scores.

Raises

• ValueError if the model is invalid.
• FileNotFoundError if img_path does not exist.

Example Usage

The following example shows how to create a model, train it using folders of labeled images, and evaluate a new image.

Folder Structure

Each category should have its own folder containing images:

dataset/
├── Eagles/
│   ├── img1.jpg
│   └── img2.jpg
├── Penguins/
├── Owls/
└── Others/

Training and Evaluation

from easy_image_model import (
    create_model,
    train_model_batch_folders,
    evaluate_model
)

# Define classification categories
categories = ['Eagles', 'Penguins', 'Owls', 'Others']

# Create a model with three hidden layers
model = create_model(
    layers=[512, 256, 128],
    categories=categories,
    img_size=224
)

# Map categories to their image folders
folder_paths = {
    'Eagles': 'dataset/Eagles',
    'Penguins': 'dataset/Penguins',
    'Owls': 'dataset/Owls',
    'Others': 'dataset/Others'
}

# Train the model
model = train_model_batch_folders(
    model,
    folder_paths,
    batch_size=4,
    epochs=5
)

# Evaluate a new image
result = evaluate_model(model, 'test_images/test1.jpg')

print(result)
# Example output:
# {
#   'Eagles': 0.87,
#   'Penguins': 0.05,
#   'Owls': 0.03,
#   'Others': 0.05
# }

The returned dictionary maps each category to its predicted probability for the input image.