imgshape 4.0.0

imgshape v4.0.0 (Atlas) — Dataset intelligence layer: deterministic fingerprinting and decision-making for ML pipelines.

📊 imgshape

Dataset Intelligence Layer for Computer Vision

v4.0.0 Atlas Edition

Deterministic Dataset Fingerprinting & Intelligent Decision Making
Fingerprinting • Rule-Based Decisions • Explainable AI • Deployable Artifacts • Production Ready

🌐 Live Demo • Documentation • v4 Guide • Report Bug • Request Feature

---

🚀 imgshape v4.0.0 (Atlas)

Atlas is a complete architectural redesign of imgshape, shifting from heuristic recommendations to deterministic dataset intelligence.

Core Capabilities

Feature	Description
🔬 Deterministic Fingerprinting	Stable, canonical dataset identities across runs and deployments
🎯 Rule-Based Decisions	Explainable, traceable decisions with full reasoning
📐 Five-Profile System	Spatial, Signal, Distribution, Quality, Semantic analysis
📦 Deployable Artifacts	CI-safe, version-controlled outputs for production
🔓 No Hidden Logic	Every decision includes complete rationale and confidence
⚙️ Framework Agnostic	Works with PyTorch, TensorFlow, JAX, or plain NumPy

Why Atlas?

Before (v3): "This dataset looks good for ResNet50."
Now (v4 Atlas): "This dataset's fingerprint is imgshape://vision/photographic/high-entropy. For task=classification with priority=speed, we recommend MobileNetV3 because: [8 explicit reasons with metrics]."

---

⚡ Quick Start

Installation

# Core package
pip install imgshape

# With web UI and full features
pip install "imgshape[full]"

Python API (v4)

from imgshape import Atlas

# Initialize the analyzer
atlas = Atlas()

# Analyze a dataset
result = atlas.analyze(
    dataset_path="path/to/images",
    task="classification",
    deployment="edge",
    priority="speed"
)

# Inspect results
print(f"Fingerprint: {result.fingerprint.dataset_uri}")
# Fingerprint: imgshape://vision/photographic/high-entropy

print(f"Recommended Model: {result.decisions['model_family'].selected}")
# Recommended Model: MobileNetV3

print(f"Reasoning: {result.decisions['model_family'].why}")
# Reasoning: [8 evidence points with metrics]

# Export for CI/CD
artifact = result.to_artifact()
artifact.save("dataset_analysis.json")

Command Line (v4)

# Generate fingerprint
imgshape --fingerprint path/to/images --format json

# Run full analysis
imgshape --atlas path/to/images --task classification --output analysis.json

# View decisions
imgshape --decisions path/to/images --priority speed --deployment edge

# Interactive web UI
imgshape --web
# Opens http://localhost:8080 with modern React interface

Web Interface

The imgshape web UI provides an interactive, modern interface for dataset analysis:

Live Demo: 🌐 imgshape.vercel.app

imgshape --web

Features:

• 📊 Real-time fingerprint generation and visualization
• 🎯 Interactive decision explorer with full reasoning
• 📈 Dataset statistics dashboard
• 💾 Export analysis results (JSON, YAML, PDF)
• 🚀 Deploy artifacts directly from the UI

---

🏗️ Architecture

Core Components

┌─────────────────────────────────────────────────┐
│         Atlas Orchestrator                       │
│  (Main coordination & result aggregation)        │
└────────────┬────────────────────────────────────┘
             │
    ┌────────┼────────┐
    │        │        │
    ▼        ▼        ▼
┌────────┐ ┌──────┐ ┌─────────┐
│Finger- │ │Rules │ │Artifact │
│print   │ │Based │ │Generator│
│Engine  │ │Decis-│ │         │
│        │ │ion   │ │         │
└────────┘ └──────┘ └─────────┘
    │        │         │
    └────────┼─────────┘
             │
             ▼
    ┌────────────────┐
    │Result Bundle   │
    │ - Fingerprint  │
    │ - Decisions    │
    │ - Artifacts    │
    │ - Confidence   │
    └────────────────┘

Fingerprint Profiles

Every dataset receives a 5-dimensional fingerprint:

1. Spatial Profile - Image dimensions, aspect ratios, scale distribution
2. Signal Profile - Channel count, bit depth, dynamic range
3. Distribution Profile - Entropy, skewness, color uniformity
4. Quality Profile - Corruption rate, blur detection, noise estimation
5. Semantic Profile - Inferred content type (faces, objects, aerial, medical, etc.)

---

🎯 Decision Domains

Atlas makes deterministic decisions across 8 domains:

Domain	Examples
Model Family	ResNet, MobileNet, ViT, EfficientNet, etc.
Input Dimensions	224x224, 512x512, or custom based on content
Preprocessing	Normalization parameters, augmentation strategy
Batch Size	Based on memory constraints and convergence
Optimizer	Adam, SGD, AdamW based on dataset characteristics
Augmentation	RandAugment, MixUp, Cutmix, intensity levels
Deployment Target	CPU, GPU, Edge (TensorRT, ONNX), Mobile
Training Duration	Early stopping patience, epoch count, callbacks

---

📊 Example Analysis Output

{
  "fingerprint": {
    "dataset_uri": "imgshape://vision/photographic/high-entropy",
    "dataset_id": "sha256:abc123...",
    "sample_count": 50000,
    "spatial": {
      "resolution_class": "high",
      "aspect_ratio_variance": 0.23,
      "mean_dimensions": [1920, 1080]
    },
    "signal": {
      "channel_count": 3,
      "bit_depth": 8
    },
    "distribution": {
      "entropy": 7.84,
      "color_uniformity": 0.42
    },
    "quality": {
      "corruption_rate": 0.0,
      "blur_percentage": 3.2,
      "noise_estimate": "gaussian"
    },
    "semantic": {
      "inferred_type": "photographic",
      "confidence": 0.92
    }
  },
  "decisions": {
    "model_family": {
      "selected": "MobileNetV3",
      "confidence": 0.87,
      "why": [
        "Dataset has 50k images (suitable for efficient models)",
        "Spatial resolution is high (1920x1080 average)",
        "Photographic content with 0.23 aspect ratio variance",
        "Edge deployment prioritizes inference speed over accuracy",
        "MobileNetV3 offers 2.8x faster inference than ResNet50",
        "Maintains 91% of ResNet50 accuracy on ImageNet",
        "Works on CPU and mobile devices",
        "Recent architecture (2019) with good operator support"
      ],
      "alternatives": ["EfficientNetB1", "ResNet34"]
    },
    "input_dimensions": {
      "selected": [224, 224],
      "confidence": 0.95,
      "why": ["MobileNetV3 default", "High entropy favors standard sizes"]
    }
  },
  "artifacts": {
    "fingerprint_stable": true,
    "fingerprint_format": "v4",
    "export_formats": ["json", "yaml", "protobuf"]
  }
}

---

💻 Usage Patterns

1. CI/CD Integration

#!/bin/bash
# ci_check.sh - Ensure dataset integrity in your pipeline

imgshape --fingerprint data/train \
  --output fingerprint.json \
  --format json

# Compare with expected fingerprint
CURRENT=$(cat fingerprint.json | jq -r .dataset_id)
EXPECTED=$(cat .fingerprint_lock)

if [ "$CURRENT" != "$EXPECTED" ]; then
  echo "❌ Dataset changed! Update .fingerprint_lock"
  exit 1
fi

echo "✅ Dataset verified"

2. Training Script Integration

from imgshape import Atlas

# In your training pipeline
atlas = Atlas()
analysis = atlas.analyze("data/train", task="classification")

# Use recommendations
model = create_model(
    architecture=analysis.decisions['model_family'].selected,
    input_size=analysis.decisions['input_dimensions'].selected
)

augmentation = get_augmentation_pipeline(
    analysis.decisions['augmentation'].selected
)

print(f"Fingerprint: {analysis.fingerprint.dataset_uri}")
print(f"Model: {model.__class__.__name__}")

3. Manual Inspection

# Generate comprehensive report
imgshape --atlas data/train \
  --task detection \
  --deployment gpu \
  --priority accuracy \
  --report analysis_report.md

# View decisions
imgshape --decisions data/train \
  --output decisions.json \
  --verbose

---

🔌 Plugin System

Extend imgshape with custom fingerprint extractors and decision rules.

# plugins/medical_profiler.py
from imgshape.plugins import FingerprintPlugin

class MedicalProfiler(FingerprintPlugin):
    """Extract DICOM-specific attributes"""
    
    NAME = "medical_profiler_v1"
    
    def extract(self, dataset_path):
        # Custom logic for medical imaging
        return {
            "modality": "CT",
            "bit_depth": 16,
            "is_3d": True
        }

Register and use:

imgshape --plugin-add plugins/medical_profiler.py
imgshape --fingerprint medical_data/ --plugin medical_profiler_v1

---

📦 Installation Options

# Core (minimal dependencies)
pip install imgshape

# With PyTorch support
pip install "imgshape[torch]"

# With web UI (FastAPI + React)
pip install "imgshape[web]"

# With all features
pip install "imgshape[full]"

# Development (with testing tools)
pip install "imgshape[dev]"

---

🧪 Testing

Run the comprehensive test suite:

# Install dev dependencies
pip install "imgshape[dev]"

# Run all tests
pytest tests/ -v

# Run v4 specific tests
pytest tests/test_fingerprint.py tests/test_decision_engine.py -v

# Coverage
pytest --cov=imgshape tests/

Expected output: 26/33 passing (7 optional artifact tests)

---

🌐 Web Service

Deploy imgshape as a REST API:

# Start the service
imgshape --web

# API Endpoints (v4)
# POST /v4/fingerprint    - Get dataset fingerprint
# POST /v4/decisions      - Get decisions for a dataset
# POST /v4/analyze        - Full analysis
# GET  /health            - Service health

# Legacy Endpoints (v3)
# POST /analyze           - v3 analyze
# POST /recommend         - v3 recommendations

Docker Deployment

# Build
docker build -t imgshape:4.0.0 .

# Run
docker run -p 8080:8080 imgshape:4.0.0

# Cloud Run
gcloud run deploy imgshape --image gcr.io/your-project/imgshape:4.0.0

---

🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run pytest tests/ to verify
5. Commit: git commit -m 'Add amazing feature'
6. Push: git push origin feature/amazing-feature
7. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

---

📚 Additional Resources

• Full Documentation
• v4 Atlas Design Document
• API Reference
• Contributing Guide
• Issues & Feature Requests

---

📄 License

imgshape is released under the MIT License. See LICENSE file for details.

---

Built with 💜 by Stifler

Making dataset intelligence accessible to everyone.

If you find imgshape useful, please consider:

• ⭐ Starring this repository
• 📢 Sharing with your colleagues
• 🐛 Reporting issues and suggesting features
• 🤝 Contributing code or documentation