imageatlas 0.1.0__tar.gz → 0.1.2__tar.gz

{imageatlas-0.1.0 → imageatlas-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imageatlas
-Version: 0.1.0
+Version: 0.1.2
 Summary: ImageAtlas: A toolkit for organizing, cleaning and analysing your image datasets.
 Author-email: Ahmad Javed <ahmadjaved97@gmail.com>
 Maintainer-email: Ahmad Javed <ahmadjaved97@gmail.com>
@@ -63,6 +63,7 @@ Requires-Dist: openpyxl; extra == "full"
 Dynamic: license-file
 
 # ImageAtlas
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/imageatlas?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=Downloads)](https://pepy.tech/projects/imageatlas)
 
 ## Overview
 
@@ -86,6 +87,12 @@ pip install imageatlas
 pip install imageatlas[full]
 ```
 
+**Note on CLIP**: If you wish to use the CLIP model, you must install it manually from GitHub using:
+
+```
+pip install git+https://github.com/openai/CLIP.git
+```
+
 **From Source**
 ```
 git clone https://github.com/ahmadjaved97/ImageAtlas.git

{imageatlas-0.1.0 → imageatlas-0.1.2}/README.md

@@ -1,4 +1,5 @@
 # ImageAtlas
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/imageatlas?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=Downloads)](https://pepy.tech/projects/imageatlas)
 
 ## Overview
 
@@ -22,6 +23,12 @@ pip install imageatlas
 pip install imageatlas[full]
 ```
 
+**Note on CLIP**: If you wish to use the CLIP model, you must install it manually from GitHub using:
+
+```
+pip install git+https://github.com/openai/CLIP.git
+```
+
 **From Source**
 ```
 git clone https://github.com/ahmadjaved97/ImageAtlas.git

{imageatlas-0.1.0 → imageatlas-0.1.2}/imageatlas/__init__.py

@@ -2,7 +2,7 @@
 ImageAtlas: A toolkit for organizing, cleaning and analysing your image datasets.
 """
 
-__version__ = '0.1.0'
+__version__ = '0.1.2'
 
 
 # 1. High level API (The everything tool)

{imageatlas-0.1.0 → imageatlas-0.1.2}/imageatlas/clustering/__init__.py

@@ -1,7 +1,15 @@
+"""
+Clustering Algorithms module.
+
+This module provides various clustering algorithms with a unified interface for clustering
+on image features.
+
+"""
 from .base import ClusteringResult, ClusteringAlgorithm
 from .kmeans import KMeansClustering
 from .hdbscan_clustering import HDBSCANClustering
 from .gmm import GMMClustering
+from .factory import create_clustering_algorithm, get_available_algorithms
 
 
 
@@ -11,4 +19,6 @@ __all__ = [
     'KMeansClustering',
     'HDBSCANClustering',
     'GMMClustering',
+    'create_clustering_algorithm',
+    'get_available_algorithms'
 ]

{imageatlas-0.1.0 → imageatlas-0.1.2}/imageatlas/clustering/base.py

@@ -8,7 +8,13 @@ import numpy as np
 class ClusteringResult:
     """
     Container for clustering Results.
+    Attributes:
+       cluster_labels: Array of cluster assignments for each sample.
+       cluster_dict: Dictionary mapping cluster IDs to list of sample indices.
+       n_clusters: Number of clusters found.
+       metadata: Additional algorithm-specific metadata.
     """
+
     cluster_labels: np.ndarray
     cluster_dict: Dict[int, List[int]]
     n_clusters: int
@@ -49,11 +55,18 @@ class ClusteringResult:
 class ClusteringAlgorithm(ABC):
     """
     Abstract base class for all clustering algorithms.
+
+    All the clustering algorithms must implement the fit_predict method and 
+    provide a consistent interface for clustering operations.
     """
 
     def __init__(self, random_state=42, **kwargs):
         """
         Initialize the clustering algorithm.
+
+        Args:
+            random_state: Random seed for reproducibility.
+            **kwargs: Additional algorithm related parameters.
         """
         self.random_state = random_state
         self.params = kwargs
@@ -64,6 +77,12 @@ class ClusteringAlgorithm(ABC):
     def fit_predict(self, features) -> ClusteringResult:
         """
         Fit the clustering algorithms and predict cluster labels.
+        
+        Args:
+            features: Feature matrix of shape (n_samples, n_features)
+        
+        Returns:
+            ClusteringResult object containing cluster assignments and metadata.
         """
         pass
     
@@ -77,7 +96,14 @@ class ClusteringAlgorithm(ABC):
     def _validate_features(self, features:np.ndarray) -> None:
         """
         Validate the input feature matrix.
+
+        Args:
+            features: Feature matrix of shape (n_samples, n_features) to validate.
+        
+        Raises:
+            ValueError: If features are invalid.
         """
+
         if not isinstance(features, np.ndarray):
             raise ValueError(f"Feature must be a numpy array, got {type(features)}")
         
@@ -93,6 +119,13 @@ class ClusteringAlgorithm(ABC):
     def _create_cluster_dict(self, cluster_labels, filenames=None):
         """
         Createa dictionary mapping cluster IDs to indices or filenames
+
+        Args:
+            cluster_labels: Array of cluster assignments.
+            filenames: Optional list of filenames corresponding to images.
+        
+        Returns:
+            Dictionary mapping cluster IDs to lists of indices or filenames
         """
 
         cluster_dict = {}

{imageatlas-0.1.0 → imageatlas-0.1.2}/imageatlas/clustering/factory.py

@@ -22,6 +22,27 @@ def create_clustering_algorithm(
 ) -> ClusteringAlgorithm:
     """
     Factory function to create clustering algorithms.
+
+    Args:
+        method: Name of the clustering algorithm ('kmeans', 'gmm', 'hdbscan')
+        **kwargs: Algorithm specific parameters
+    
+    Returns:
+        Instance of the requested clustering algorithm
+    
+    Raises:
+        Value Error: If clustering method is not supported.
+    
+
+    Examples:
+        >>> # Create KMeans with 5 clusters
+        >>> clusterer = create_clustering_algorithm('kmeans', n_clusters=5)
+
+        >>>  # Create GMM with full covariance
+        >>> clusterer = create_clustering_algorithm('gmm', n_components=8, covariance_type='full')
+
+        >>> # Create HDBSCAN with auto parameters
+        >>> clusterer = create_clustering_algorithm('hdbscan', auto_params=True)
     """
 
     method = method.lower()
@@ -39,5 +60,8 @@ def create_clustering_algorithm(
 def get_available_algorithms():
     """
     Get a list of available clustering algorithms.
+
+    Returns:
+        List of algorithm names.
     """
     return sorted(CLUSTERING_ALGORITHMS.keys())

{imageatlas-0.1.0 → imageatlas-0.1.2}/imageatlas/clustering/gmm.py

@@ -10,6 +10,14 @@ from .base import ClusteringAlgorithm, ClusteringResult
 class GMMClustering(ClusteringAlgorithm):
     """
     Gaussian Mixture Model clustering algorithm.
+
+    Args:
+        n_components: Number of mixture components (clusters)
+        covariance_type: Type of covarince parameters ('full', 'diag', 'tied', 'spherical')
+        max_iter: Maximum number of EM iterations
+        n_init: Number of initializations to perform
+        reg_covar: Regularization added to diagonal of covariance (prevents singular matrices)
+        random_state: Random seed for reproducibility
     """
 
     def __init__(
@@ -46,10 +54,16 @@ class GMMClustering(ClusteringAlgorithm):
 
         """
         Fit GMM and predict cluster labels.
+
+        Args:
+            features: Feature matrix of shape (n_samples, n_features)
+            filenames: Optional list of filenames for cluster mapping
+        
+        Returns:
+            ClusteringResult object with cluster assignments.
         """
 
         self._validate_features(features)
-        print('fshape: ', features.shape)
 
         n_samples = features.shape[0]
 
@@ -110,6 +124,15 @@ class GMMClustering(ClusteringAlgorithm):
     def predict(self, features):
         """
         Predict cluster label for new samples.
+
+        Args:
+            features: Feature matrix of shape (n_samples, n_features)
+        
+        Returns:
+            Array of cluster labels
+        
+        Raises:
+            RuntimeError: If model has not been fitted yet.
         """
 
         if not self.is_fitted or self._model is None:
@@ -121,6 +144,15 @@ class GMMClustering(ClusteringAlgorithm):
     def predict_proba(self, features):
         """
         Predict probability of each cluster for new samples.
+
+        Args:
+            features: Feature matrix of shape (n_samples, n_features)
+        
+        Returns:
+            Array of cluster labels
+        
+        Raises:
+            RuntimeError: If model has not been fitted yet.
         """
 
         if not self.is_fitted or self._model is None:
@@ -132,6 +164,9 @@ class GMMClustering(ClusteringAlgorithm):
     def get_cluster_means(self):
         """
         Get cluster means (centers) if model is fitted.
+
+        Returns:
+            Array of cluster centers or None if not fitted.
         """
 
         if self.is_fitted and self._model is not None:
@@ -142,6 +177,12 @@ class GMMClustering(ClusteringAlgorithm):
     def score(self, features):
         """
         Compute the log-likelihood of the data under the model.
+
+        Args:
+            features: Feature matrix of shape (n_samples, n_features)
+        
+        Returns:
+            Log-likelihood score
         """
 
         if not self.is_fitted or self._model is None:

{imageatlas-0.1.0 → imageatlas-0.1.2}/imageatlas/clustering/hdbscan_clustering.py

@@ -7,7 +7,16 @@ from .base import ClusteringAlgorithm, ClusteringResult
 
 class HDBSCANClustering(ClusteringAlgorithm):
     """
-    HDBSCAN algorithm.
+    HDBSCAN (Hierarchical Density-Based Spatial Clustering) Algorithm.
+
+    Args:
+        min_cluster_size: Minimum number of samples in a cluster
+        min_samples: Number of samples in a neighborhood for core points.
+        metric: Distance metric to use
+        cluster_selection_method: Method for selecting clusters ('eom' or 'leaf')
+        auto_params: Whether to automatically set parameters based on dataset size
+        random_state: Random seed (note: HDBSCAN is deterministic, this is for consistency)
+
     """
 
     def __init__(
@@ -37,6 +46,12 @@ class HDBSCANClustering(ClusteringAlgorithm):
     def _auto_select_params(self, n_samples):
         """
         Automatically select HDBSCAN parameters based on dataset size.
+
+        Args:
+            n_samples: Number of samples in the dataset.
+        
+        Returns:
+            Tuple of (min_cluster_size, min_samples)
         """
 
         if n_samples < 100:
@@ -62,6 +77,10 @@ class HDBSCANClustering(ClusteringAlgorithm):
 
         """
         Fit HDBSCAN and predict cluster labels.
+
+        Args:
+            features: Feature matrix of shape (n_samples, n_features)
+            filenames: Optional list of filenames for cluster mapping.
         """
 
         try:
@@ -137,6 +156,11 @@ class HDBSCANClustering(ClusteringAlgorithm):
     def get_outlier_score(self):
         """
         Get outlier score for each sample.
+
+        Higher scores indicate more likely outliers.
+
+        Returns:
+            Array of outlier scores or None if model is not fitted.
         """
 
         if self.is_fitted and self._model is not None:
@@ -147,6 +171,9 @@ class HDBSCANClustering(ClusteringAlgorithm):
     def get_condensed_tree(self):
         """
         Get condensed cluster hierarchy tree.
+
+        Returns:
+            Array of membership probabilities or None if model not fitted.
         """
 
         if self.is_fitted and self._model is not None:

{imageatlas-0.1.0 → imageatlas-0.1.2}/imageatlas/clustering/kmeans.py

@@ -10,6 +10,14 @@ from typing import Optional
 class KMeansClustering(ClusteringAlgorithm):
     """
     K-Means clustering algorithm.
+
+    Args:
+        n_clusters: Number of clusters to form
+        n_init: Number of times to run with different centroid seeds
+        max_iter: Maximum number of iterations
+        use_minibatch: Whether to use MiniBatchKMeans for large datasets
+        batch_size: Batch size for MiniBatchKMeans
+        random_state: Random seed for reproducibility
     """
 
     def __init__(
@@ -42,6 +50,13 @@ class KMeansClustering(ClusteringAlgorithm):
 
         """
         Fit K-Means and predict cluster labels.
+
+        Args:
+            features: Feature matrix of shape (n_samples, n_features)
+            filenames: Optional list of filenames for cluster mapping
+        
+        Returns:
+            ClusteringResult object with cluster assignments.
         """
 
         self._validate_features(features)
@@ -108,6 +123,15 @@ class KMeansClustering(ClusteringAlgorithm):
     def predict(self, features):
         """
         Predict cluster label for new samples.
+
+        Args:
+            features: Feature matrix of shape (n_samples, n_features)
+        
+        Returns:
+            Array of cluster labels
+        
+        Raises:
+            RuntimeError: If model has not yet been fitted.
         """
 
         if not self.is_fitted or self._model == None:
@@ -119,6 +143,9 @@ class KMeansClustering(ClusteringAlgorithm):
     def get_cluster_centers(self):
         """
         Get cluster centers if model is fitted.
+
+        Returns:
+            Array of cluster centers or None if not fitted.
         """
         if self.is_fitted and self._model is not None:
             return self._model.cluster_centers_

{imageatlas-0.1.0 → imageatlas-0.1.2}/imageatlas/features/batch.py

@@ -10,6 +10,8 @@ import warnings
 class BatchProcessor:
     """
     Handles batch processing of images through feature extractors.
+
+    Manages batching, device placement and memory cleanup.
     """
 
     def __init__(
@@ -20,6 +22,11 @@ class BatchProcessor:
     ):
         """
         Initialize batch processor.
+
+        Args:
+            batch_size: Number of images to process at once.
+            device: Device to use ('cpu', 'cuda', 'cuda:0', etc.)
+            clear_cache: Whether to clear GPU cache after each batch
         """
 
         self.batch_size = batch_size
@@ -50,8 +57,15 @@ class BatchProcessor:
     ):
         """
         Process a batch of extractors through the feature extractor.
-        TODO: use the correct batching method in the feature_extractors module.
+        Args:
+            images: List of PIL Images.
+            extractor: Feature extractor with extract_features method
+            return_numpy: Whether to return numpy array (vs torch tensor)
+        
+        Returns:
+            Array of feature vectors, shape (batch_size, feature_dim)
         """
+        # TODO: use the correct batching method in the feature_extractors module.
 
         if not images:
             return np.array([])
@@ -108,6 +122,14 @@ class BatchProcessor:
     ):
         """
         Estimate memory usage for a batch.
+
+        Args:
+            n_images: Number of images in a batch
+            feature_dim: Dimensions of feature vector
+            dtype: Data type of features
+
+        Returns:
+            Estimated memory in GB
         """
 
         bytes_per_element = np.dtype(dtype).itemsize

{imageatlas-0.1.0 → imageatlas-0.1.2}/imageatlas/features/cache.py

@@ -70,6 +70,12 @@ class HDF5Cache(FeatureCache):
     ):
         """
         Save features to HDF5 file.
+
+        Args:
+            features: Feature array, shape (n_samples, feature_dim)
+            filenames: List of filenames corresponding to features
+            metadata: Feature metadata
+            path: Path to save HDF5 file
         """
 
         # Make sure path has .h5 extension
@@ -115,13 +121,20 @@ class HDF5Cache(FeatureCache):
     ):
         """
         Load features from HDF5 file.
+
+        Args:
+            path: Path to HDF5 File
+            lazy: If True, return memory-mapped array instead of loading to RAM
+        
+        Returns:
+            Tuple of (features, filenames, metadata)
         """
 
         if not path.endswith(".h5"):
             path = path + ".h5"
         
         if not self.exists(path):
-            raise FileNotFoundError("fCache file not found: {path}")
+            raise FileNotFoundError(f"Cache file not found: {path}")
         
         with h5py.File(path, 'r') as f:
             # Load filenames
@@ -161,6 +174,14 @@ class HDF5Cache(FeatureCache):
     ):
         """
         Load a subset of features.
+
+        Args:
+            path: Path to HDF5 file
+            indices: Indices to load (if provided)
+            filenames: Filenames to load (if provided)
+        
+        Returns:
+            Tuple of (features, filenames)
         """
 
         if not path.endswith(".h5"):
@@ -193,6 +214,11 @@ class HDF5Cache(FeatureCache):
     ):
         """
         Append new features to existing cache.
+
+        Args:
+            path: Path to the HDF5 file
+            new_features: New features to append
+            new_filenames: Corresponding filenames
         """
 
         if not path.endswith(".h5"):
@@ -223,6 +249,12 @@ class HDF5Cache(FeatureCache):
     def get_feature_dict(self, path):
         """
         Load features as dictionary (for backward compatibility)
+
+        Args:
+            path: Path to HDF5 file
+        
+        Returns:
+            Dictionary mapping filenames to feature vectors
         """
         features, filenames, _ = self.load(path)
         return {fn: feat for fn, feat in zip(filenames, features)}
@@ -230,6 +262,12 @@ class HDF5Cache(FeatureCache):
     def get_info(self, path):
         """
         Get information about the cache without loading data.
+
+        Args:
+            path: Path to HDF5 file
+        
+        Returns:
+            Dictionary with cache information
         """
 
         if not path.endswith(".h5"):

{imageatlas-0.1.0 → imageatlas-0.1.2}/imageatlas/features/loaders.py

@@ -12,6 +12,8 @@ import warnings
 class ImageLoader:
     """
     Image loader with validation and error handling.
+
+    Handles corrupted images, format conversions, and EXIF orientations.
     """
     VALID_EXTENSIONS = {'.jpg', '.jpeg', '.png', '.bmp', '.tiff', '.tif', '.webp'}
 
@@ -23,6 +25,11 @@ class ImageLoader:
     ):
         """
         Initialize image loader.
+
+        Args:
+            max_size: Optional maximum size (width, height) for images
+            convert_mode: PIL odel to covert images to ('RGB', 'L', etc.)
+            handle_exif: Whether to handle EXIF orientation
         """
 
         self.max_size = max_size
@@ -33,6 +40,12 @@ class ImageLoader:
     def validate_path(self, path):
         """
         Check if path is valid
+
+        Args:
+            path: Path to image file
+        
+        Returns:
+            True if valid, False otherwise
         """
         if not os.path.exists(path):
             return False
@@ -43,6 +56,12 @@ class ImageLoader:
     def load_image(self, path):
         """
         Load a single image.
+
+        Args:
+            path: Path to image file
+        
+        Returns:
+            PIL Image or None if loadig failed
         """
 
         try:
@@ -78,6 +97,12 @@ class ImageLoader:
     def load_batch(self, paths):
         """
         Load a batch of images.
+
+        Args:
+            paths: List of image paths
+        
+        Returns:
+            Tuple of (loaded_images, successful_paths, failed_paths)
         """
 
         images = []
@@ -97,6 +122,12 @@ class ImageLoader:
     def _handle_orientation(self, image):
         """
         Handle EXIF orientation tag.
+
+        Args:
+            image: PIL Image
+        
+        Returns:
+            Oriented image
         """
 
         try:
@@ -129,6 +160,12 @@ class ImageLoader:
     def _resize_if_needed(self, image):
         """
         Resize image if it exceeds max size.
+
+        Args:
+            image: PIL Image
+        
+        Returns:
+            Resized image
         """
         if self.max_size is None:
             return image
@@ -149,6 +186,14 @@ class ImageLoader:
     ):
         """
         Find all images in a directory.
+
+        Args:
+            directory: Directory to search
+            pattern: Glob pattern for filenames
+            recursive: Whether to search recursively
+        
+        Returns:
+            List of image paths
         """
         path = Path(directory)
 
@@ -180,6 +225,13 @@ class ImageLoader:
 
         """
         Create batches from a list of items.
+
+        Args:
+            items: List of items to batch
+            batch_size: Size of each batch
+        
+        Yeilds:
+            Batches of items
         """
 
         for i in range(0, len(items), batch_size):

{imageatlas-0.1.0 → imageatlas-0.1.2}/imageatlas/features/metadata.py

@@ -12,6 +12,9 @@ import json
 class FeatureMetadata:
     """
     Metadata for extracted features.
+
+    Tracks information about the feature extractionn process including
+    model details, extraction parameters, and statistics.
     """
 
     # Model information

{imageatlas-0.1.0 → imageatlas-0.1.2}/imageatlas/features/pipeline.py

@@ -17,6 +17,18 @@ from .metadata import FeatureMetadata
 class FeaturePipeline:
     """
     Main pipeline for feature extraction.
+
+    Handles batch processing, caching, progress tracking, and error recovery.
+
+    Example:
+        >>> from features import FeaturePipeline
+        >>> from feature_extractors import create_feature_extractor
+        >>> 
+        >>> extractor = create_feature_extractor('dinov2', device='cuda')
+        >>> pipeline = FeaturePipeline(extractor, batch_size=32)
+        >>> 
+        >>> result = pipeline.extract_from_directory('./images')
+        >>> pipeline.save('./features/features.h5')
     """
 
     def __init__(
@@ -30,6 +42,14 @@ class FeaturePipeline:
     ):
         """
         Initialize feature extraction pipeline.
+
+        Args:
+            extractor: Feature extractor (from feature_extractors module)
+            batch_size: Number of images to process at once
+            device: Device for processing ('cpu', 'cuda')
+            cache_backend: Cache backend to use ('hdf5')
+            max_image_size: Optional max size for images (width, height)
+            verbose: Whether to show progress bars
         """
 
         self.extractor = extractor
@@ -79,6 +99,16 @@ class FeaturePipeline:
 
         """
         Extract features from all images in a directory.
+
+        Args:
+            directory: Directory containing images
+            pattern: Glob pattern for filenames
+            recursive: Whether to search recursively
+            save_every: Save checkpoint every N images (optional)
+            save_path: Path for checkpoint saves (required if save_every is set)
+        
+        Returns:
+            Self for method chaining
         """
 
         # Find all images
@@ -112,6 +142,14 @@ class FeaturePipeline:
 
         """
         Extract features from a list of filepaths.
+
+        Args:
+            file_paths: List of image file paths
+            save_every: Save checkpoint every N images (optional)
+            save_path: Path for checkpoint saves (required if save_every is set)
+
+        Returns:
+            Self for method chaining
         """
 
         if save_every is not None and save_path is None:
@@ -223,6 +261,10 @@ class FeaturePipeline:
     def save(self, path, format='hdf5'):
         """
         Save extracted features to disk.
+
+        Args:
+            path: Path to save features
+            format: Format to use ('hdf5')
         """
 
         if self.features is None or self.metadata is None:
@@ -244,6 +286,11 @@ class FeaturePipeline:
     def load(self, path):
         """
         Load features from disk.
+
+        Args:
+            path: Path to feature cache
+        
+        Returns: Self for method chaining
         """
 
         self.features, self.filenames, self.metadata = self.cache.load(path)
@@ -271,6 +318,9 @@ class FeaturePipeline:
     def get_feature_dict(self):
         """
         Get features as dictionary
+
+        Returns:
+            Dictionary mapping filenames to feature vectors
         """
 
         if self.features is None:

{imageatlas-0.1.0 → imageatlas-0.1.2}/imageatlas.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imageatlas
-Version: 0.1.0
+Version: 0.1.2
 Summary: ImageAtlas: A toolkit for organizing, cleaning and analysing your image datasets.
 Author-email: Ahmad Javed <ahmadjaved97@gmail.com>
 Maintainer-email: Ahmad Javed <ahmadjaved97@gmail.com>
@@ -63,6 +63,7 @@ Requires-Dist: openpyxl; extra == "full"
 Dynamic: license-file
 
 # ImageAtlas
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/imageatlas?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=Downloads)](https://pepy.tech/projects/imageatlas)
 
 ## Overview
 
@@ -86,6 +87,12 @@ pip install imageatlas
 pip install imageatlas[full]
 ```
 
+**Note on CLIP**: If you wish to use the CLIP model, you must install it manually from GitHub using:
+
+```
+pip install git+https://github.com/openai/CLIP.git
+```
+
 **From Source**
 ```
 git clone https://github.com/ahmadjaved97/ImageAtlas.git