Initial commit

Author: lygitdata

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Li Yuan, Xinrui Zhai, and Fangzhou Ma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,44 @@
+[project]
+name = "garmentiq"
+version = "0.0.4.8"
+authors = [
+  { name="Li Yuan", email="lyuan@gd.edu.kg" },
+  { name="Xinrui Zhai", email="zxr86272731@gmail.com" },
+  { name="Fangzhou Ma", email="fangzhou.ma029@gmail.com" },
+]
+maintainers = [
+  { name="Li Yuan", email="lyuan@gd.edu.kg" },
+  { name="Xinrui Zhai", email="zxr86272731@gmail.com" },
+  { name="Fangzhou Ma", email="fangzhou.ma029@gmail.com" },
+]
+description = "Automated Garment Measurement for Fashion Retail"
+readme = "README.md"
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License"
+]
+dependencies = [
+    "tqdm==4.67.1",
+    "pandas==2.2.2",
+    "numpy==2.0.0",
+    "torch==2.7.0",
+    "torchvision==0.22.0",
+    "scikit-learn==1.6.1",
+    "scipy==1.15.2",
+    "Pillow==11.1.0",
+    "matplotlib==3.10.0",
+    "transformers==4.50.3",
+    "kornia==0.8.0",
+    "timm==1.0.15",
+    "einops==0.8.1",
+    "shapely==2.1.1",
+    "opencv-python==4.11.0.86"
+]
+
+[project.urls]
+Homepage = "https://garmentiq.ly.gd.edu.kg/"
+Issues = "https://github.com/lygitdata/GarmentIQ/issues"
+
+[tool.setuptools.package-data]
+"garmentiq.instruction" = ["*.json"]

pyproject.toml

@@ -0,0 +1,6 @@
+# garmentiq/__init__.py
+from .tailor import tailor
+from . import utils
+from . import classification
+from . import segmentation
+from . import landmark

src/garmentiq/__init__.py

@@ -0,0 +1,22 @@
+# garmentiq/classification/__init__.py
+from .train_test_split import train_test_split
+from .load_data import load_data
+from .load_model import load_model
+from .train_pytorch_nn import train_pytorch_nn
+from .fine_tune_pytorch_nn import fine_tune_pytorch_nn
+from .test_pytorch_nn import test_pytorch_nn
+from .predict import predict
+from .utils import (
+    CachedDataset,
+    seed_worker,
+    train_epoch,
+    validate_epoch,
+    save_best_model,
+    validate_train_param,
+    validate_test_param,
+)
+from .model_definition import (
+    CNN3, 
+    CNN4, 
+    tinyViT,
+)

src/garmentiq/classification/__init__.py

@@ -0,0 +1,155 @@
+import torch
+import torch.nn as nn
+from torch.utils.data import DataLoader
+from typing import Callable, Type
+from tqdm.notebook import tqdm
+import os
+from sklearn.model_selection import StratifiedKFold
+from garmentiq.classification.utils import (
+    CachedDataset,
+    seed_worker,
+    train_epoch,
+    validate_epoch,
+    save_best_model,
+    validate_train_param,
+    validate_test_param,
+)
+
+def fine_tune_pytorch_nn(
+    model_class: Type[torch.nn.Module],
+    model_args: dict,
+    dataset_class: Callable,
+    dataset_args: dict,
+    param: dict,
+):
+    """
+    Fine-tunes a pretrained PyTorch model using k-fold cross-validation, early stopping, and checkpointing.
+
+    This function loads pretrained weights, optionally freezes specified layers, and trains the model on a new dataset
+    while preserving original learned features. It performs stratified k-fold CV, monitors validation loss, and saves
+    the best performing model.
+
+    Args:
+        model_class (Type[torch.nn.Module]): Class of the PyTorch model (inherits from `torch.nn.Module`).
+        model_args (dict): Arguments for model initialization.
+        dataset_class (Callable): Callable that returns a Dataset given indices and cached tensors.
+        dataset_args (dict): Dict containing:
+            - 'metadata_df': DataFrame for stratification
+            - 'raw_labels': Labels array for KFold
+            - 'cached_images': Tensor of images
+            - 'cached_labels': Tensor of labels
+        param (dict): Training configuration dict. Must include:
+            - 'pretrained_path' (str): Path to pretrained weights (.pt)
+            - 'freeze_layers' (bool): Whether to freeze base layers
+            - 'optimizer_class', 'optimizer_args'
+            - optional: 'device', 'n_fold', 'n_epoch', 'patience',
+                        'batch_size', 'model_save_dir', 'seed',
+                        'seed_worker', 'max_workers', 'pin_memory',
+                        'persistent_workers', 'best_model_name'
+
+    Raises:
+        ValueError: If required keys are missing.
+        Returns: None
+    """
+    # Validate parameters
+    validate_train_param(param)
+    os.makedirs(param.get("model_save_dir", "./models"), exist_ok=True)
+    overall_best_loss = float("inf")
+    best_model_path = os.path.join(param["model_save_dir"], param["best_model_name"])
+
+    # Stratified KFold
+    kfold = StratifiedKFold(
+        n_splits=param.get("n_fold", 5), shuffle=True, random_state=param.get("seed", 88)
+    )
+
+    for fold, (train_idx, val_idx) in enumerate(
+        kfold.split(dataset_args["metadata_df"], dataset_args["raw_labels"])
+    ):
+        print(f"\nFold {fold+1}/{param.get('n_fold',5)}")
+
+        # Prepare data loaders
+        train_dataset = dataset_class(
+            train_idx, dataset_args["cached_images"], dataset_args["cached_labels"]
+        )
+        val_dataset = dataset_class(
+            val_idx, dataset_args["cached_images"], dataset_args["cached_labels"]
+        )
+
+        g = torch.Generator()
+        g.manual_seed(param.get("seed", 88))
+
+        train_loader = DataLoader(
+            train_dataset,
+            batch_size=param.get("batch_size", 64),
+            shuffle=True,
+            num_workers=param.get("max_workers", 1),
+            worker_init_fn=param.get("seed_worker", seed_worker),
+            generator=g,
+            pin_memory=param.get("pin_memory", True),
+            persistent_workers=param.get("persistent_workers", False),
+        )
+        val_loader = DataLoader(
+            val_dataset,
+            batch_size=param.get("batch_size", 64),
+            shuffle=False,
+            num_workers=param.get("max_workers", 1),
+            worker_init_fn=param.get("seed_worker", seed_worker),
+            generator=g,
+            pin_memory=param.get("pin_memory", True),
+            persistent_workers=param.get("persistent_workers", False),
+        )
+
+        # Initialize model and load pretrained weights
+        device = param.get("device", torch.device("cuda" if torch.cuda.is_available() else "cpu"))
+        model = model_class(**model_args).to(device)
+
+        # Load pretrained weights
+        state_dict = torch.load(param["pretrained_path"], map_location=device)
+        cleaned = {k.replace("module.", ""): v for k, v in state_dict.items()}
+        model.load_state_dict(cleaned, strict=False)
+
+        # Freeze base layers if requested
+        if param.get("freeze_layers", False):
+            for name, p in model.named_parameters():
+                if not any(x in name for x in param.get("unfreeze_patterns", [])):
+                    p.requires_grad = False
+
+        # DataParallel if multiple GPUs
+        if device.type == "cuda" and torch.cuda.device_count() > 1:
+            model = nn.DataParallel(model)
+
+        optimizer = param["optimizer_class"](
+            filter(lambda p: p.requires_grad, model.parameters()),
+            **param["optimizer_args"]
+        )
+        torch.cuda.empty_cache()
+
+        best_fold_loss = float("inf")
+        patience_counter = 0
+        epoch_pbar = tqdm(range(param.get("n_epoch", 100)), desc="Epoch", leave=False)
+
+        # Training loop
+        for epoch in epoch_pbar:
+            train_loss = train_epoch(model, train_loader, optimizer, param)
+            val_loss, val_f1, val_acc = validate_epoch(model, val_loader, param)
+
+            best_fold_loss, patience_counter, overall_best_loss = save_best_model(
+                model, val_loss, best_fold_loss, patience_counter,
+                overall_best_loss, param, fold, best_model_path
+            )
+
+            epoch_pbar.set_postfix({
+                'train_loss': f"{train_loss:.4f}",
+                'val_loss': f"{val_loss:.4f}",
+                'val_acc': f"{val_acc:.4f}",
+                'val_f1': f"{val_f1:.4f}",
+                'patience': patience_counter,
+            })
+
+            print(f"Fold {fold+1} | Epoch {epoch+1} | Val Loss: {val_loss:.4f} | Acc: {val_acc:.4f} | F1: {val_f1:.4f}")
+            if patience_counter >= param.get("patience", 5):
+                print(f"Early stopping at epoch {epoch+1}")
+                break
+
+    torch.cuda.empty_cache()
+    print(f"\nFine-tuning completed. Best model saved at: {best_model_path}")

src/garmentiq/classification/fine_tune_pytorch_nn.py

@@ -0,0 +1,76 @@
+from torchvision import transforms
+import os
+from PIL import Image
+import torch
+from garmentiq.classification.utils import (
+    CachedDataset,
+    seed_worker,
+    train_epoch,
+    validate_epoch,
+    save_best_model,
+    validate_train_param,
+    validate_test_param,
+)
+from tqdm.notebook import tqdm
+
+
+def load_data(
+    df,
+    img_dir,
+    label_column,
+    resize_dim=(120, 184),
+    normalize_mean=[0.8047, 0.7808, 0.7769],
+    normalize_std=[0.2957, 0.3077, 0.3081],
+):
+    """
+    Loads and preprocesses image data into memory from a DataFrame of filenames and labels.
+
+    This function reads images from the specified directory, applies resizing, normalization,
+    and tensor conversion, and encodes labels from a specified column. It returns tensors for
+    images and labels, along with the transform pipeline used.
+
+    Args:
+        df (pandas.DataFrame): A pandas DataFrame containing at least a 'filename' column and a label column.
+        img_dir (str): Path to the directory containing image files.
+        label_column (str): Name of the column in `df` containing class labels.
+        resize_dim (tuple[int, int]): Tuple indicating the dimensions (height, width) to resize each image to.
+                                     Defaults to (120, 184).
+        normalize_mean (list[float]): Mean values for normalization (per channel).
+                                      Defaults to `[0.8047, 0.7808, 0.7769]`.
+        normalize_std (list[float]): Standard deviation values for normalization (per channel).
+                                     Defaults to `[0.2957, 0.3077, 0.3081]`.
+
+    Returns:
+        tuple[torch.Tensor, torch.Tensor, torchvision.transforms.Compose]: A tuple containing:
+            - cached_images (torch.Tensor): Tensor containing all preprocessed images.
+            - cached_labels (torch.Tensor): Tensor containing all encoded labels.
+            - transform (torchvision.transforms.Compose): The transformation pipeline used.
+    """
+    transform = transforms.Compose(
+        [
+            transforms.Resize(resize_dim),
+            transforms.ToTensor(),
+            transforms.Normalize(mean=normalize_mean, std=normalize_std),
+        ]
+    )
+
+    classes = sorted(df[label_column].unique())
+    class_to_idx = {c: i for i, c in enumerate(classes)}
+
+    cached_images = []
+    cached_labels = []
+
+    for _, row in tqdm(df.iterrows(), total=len(df), desc="Loading data into memory"):
+        img_path = os.path.join(img_dir, row["filename"])
+        image = Image.open(img_path).convert("RGB")
+        image = transform(image)
+
+        label = class_to_idx[row[label_column]]
+
+        cached_images.append(image)
+        cached_labels.append(label)
+
+    cached_images = torch.stack(cached_images)
+    cached_labels = torch.tensor(cached_labels)
+
+    return cached_images, cached_labels, transform

src/garmentiq/classification/load_data.py

@@ -0,0 +1,32 @@
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from typing import Type, List
+
+
+def load_model(model_path: str, model_class: Type[nn.Module], model_args: dict):
+    """
+    Loads a PyTorch model from a checkpoint and prepares it for inference.
+
+    This function initializes a model from the provided `model_class`, loads its weights from
+    the given file path, moves it to the appropriate device (GPU if available, otherwise CPU),
+    and sets it to evaluation mode.
+
+    Args:
+        model_path (str): Path to the saved model checkpoint (.pth or .pt file).
+        model_class (Type[nn.Module]): The class definition of the model to be instantiated.
+                                       This must be a subclass of `torch.nn.Module`.
+        model_args (dict): A dictionary of arguments used to initialize the model class.
+
+    Returns:
+        torch.nn.Module: The loaded and ready-to-use model.
+    """
+    device = "cuda" if torch.cuda.is_available() else "cpu"
+
+    model = model_class(**model_args).to(device)
+    state_dict = torch.load(model_path, map_location=device, weights_only=True)
+    new_state_dict = {k.replace("module.", ""): v for k, v in state_dict.items()}
+    model.load_state_dict(new_state_dict, strict=False)
+    model.eval()
+
+    return model