EPC Floorplan Image Detection

A Python package for classifying images as EPCs, floorplans, property photos, or exterior shots using SAM-CLIP, a state-of-the-art vision model that combines Segment Anything Model (SAM) with Contrastive Language-Image Pre-Training (CLIP).

What's New in Version 2.0.0

Major update replacing the YOLO-based classifier with SAM-CLIP for improved accuracy and robustness:

• SAM-CLIP Integration: Leverages both semantic segmentation and visual-language understanding
• Improved Accuracy: Better handling of complex layouts and variations in image styles
• More Robust: Enhanced performance on edge cases and unusual image formats
• Zero-shot Capabilities: Potential for recognizing new image types without retraining

Quick Start Guide

Get started with image classification in just a few steps:

1. Install the package:

   pip install floorplan-epc-detector==2.0.0
   

2. Basic Usage:

   from floorplan_epc_detector import FloorplanPredictor
   
   # Initialize the predictor (models will be downloaded automatically)
   predictor = FloorplanPredictor()
   
   # Classify a single image
   prediction, confidence = predictor.predict_with_confidence(
       "path/to/your/image.jpg",
       confidence_threshold=0.7
   )
   print(f"Image Type: {prediction}")
   print(f"Confidence: {confidence:.2%}")
   

3. Batch Processing Example:

   # Process multiple images
   images = [
       "image1.jpg",
       "image2.png",
       "floor_plan.jpeg"
   ]
   
   for image_path in images:
       # Get detailed probabilities
       probs = predictor.get_raw_probabilities(image_path)
       print(f"\nAnalyzing: {image_path}")
       print(f"Probabilities: {probs}")
       
       # Get final prediction
       prediction, confidence = predictor.predict_with_confidence(
           image_path,
           confidence_threshold=0.7
       )
       print(f"Predicted Type: {prediction}")
       print(f"Confidence: {confidence:.2%}")
   

4. Understanding Results:

   • The predictor classifies images into 4 categories:
     • epc: Energy Performance Certificate
     • floorplan: Floor Plans
     • interior: Interior Property Photos
     • exterior: Exterior Property Photos
   • Confidence scores range from 0 to 1 (shown as percentages)
   • The default confidence threshold is 0.7 (70%)

5. Best Practices:

   • Use clear, well-lit images
   • Ensure images are readable and not corrupted
   • Higher resolution images generally work better
   • Supported formats: JPG, JPEG, PNG
   • For batch processing, handle each image's results individually

Prerequisites

• Python 3.7 or higher

Installation

pip install floorplan-epc-detector==2.0.0

Real-World Example

Here's a complete example showing how to process multiple images and handle results:

import os
from floorplan_epc_detector import FloorplanPredictor

# Initialize predictor
predictor = FloorplanPredictor()

# List of images to process
test_images = [
    "property_photo.jpeg",
    "epc_certificate.png",
    "house_floorplan.jpg"
]

# Process each image
for image_name in test_images:
    if not os.path.exists(image_name):
        print(f"Image not found: {image_name}")
        continue
        
    print(f"\nAnalyzing image: {image_name}")
    
    try:
        # Get detailed classification probabilities
        raw_probabilities = predictor.get_raw_probabilities(image_name)
        print(f"Detailed probabilities:")
        for class_name, prob in raw_probabilities.items():
            print(f"  {class_name}: {prob:.2%}")
        
        # Get final prediction with confidence
        prediction, confidence = predictor.predict_with_confidence(
            image_name, 
            confidence_threshold=0.7
        )
        print(f"Final Result:")
        print(f"  Type: {prediction}")
        print(f"  Confidence: {confidence:.2%}")
        
    except Exception as e:
        print(f"Error processing {image_name}: {e}")

This example shows:

• How to handle multiple images
• Error handling for missing files
• Getting detailed classification probabilities
• Making final predictions with confidence scores
• Proper formatting of results

Features

• Image Classification into 4 categories:
  • EPC (Energy Performance Certificate)
  • Floorplans
  • Property Interior Images
  • Property Exterior Images
• Confidence Scoring
• Automatic model download from private/public repositories
• Progress bar for model downloads
• Configurable confidence thresholds
• Raw probability access for advanced use cases

Usage

import os
from floorplan_epc_detector import FloorplanPredictor, FloorplanPredictorError

# --- Configuration for Private Repositories --- 
# If the model is hosted in a private GitHub repository, 
# you MUST provide a GitHub Personal Access Token (PAT).
# Set it as an environment variable:
# export GITHUB_TOKEN="your_github_pat_here"
# Ensure the token has the 'repo' scope to access private repository content.

github_token = os.environ.get("GITHUB_TOKEN")

try:
    # Initialize the predictor with options
    predictor = FloorplanPredictor(
        github_token=github_token,  # Optional: For private repos
        model_path="custom/path/model.onnx",  # Optional: Custom model path
        skip_download=False  # Optional: Skip auto-download
    )

    # Basic prediction (returns just the class)
    predicted_class = predictor.predict("path/to/your/image.jpg")
    print(f"Predicted Class: {predicted_class}")

    # Prediction with confidence score
    predicted_class, confidence = predictor.predict_with_confidence(
        "path/to/your/image.jpg",
        confidence_threshold=0.7  # Optional: Default is 0.7
    )
    print(f"Predicted Class: {predicted_class}")
    print(f"Confidence: {confidence:.2%}")

    # Get raw probabilities for all classes
    probabilities = predictor.get_raw_probabilities("path/to/your/image.jpg")
    print("Raw probabilities:", probabilities)

except FloorplanPredictorError as e:
    print(f"An error occurred: {e}")
    # Handle specific errors:
    # - ModelDownloadError
    # - ImageLoadError
    # - InferenceError

Model Downloading

The package supports two ways to use the model:

1. Automatic Download: The model will be automatically downloaded from the configured repository on first use
2. Local Model: Provide a local path to an existing model file

• The package automatically attempts to download the model.onnx file using the GitHub API if it's not found locally
• Progress bar shows download progress for large model files
• Supports Git LFS for efficient model file handling
• Private Repositories: Downloading from private GitHub repositories requires a GITHUB_TOKEN environment variable or direct token provision

Error Handling

The package provides specific error types for better error handling:

• ModelDownloadError: Issues with model downloading
• ImageLoadError: Problems with image loading or preprocessing
• InferenceError: Issues during model inference
• FloorplanPredictorError: Base class for all package errors

Common Errors & Troubleshooting

• ModelDownloadError: ... 404 Not Found ...:

  • Check if the GITHUB_TOKEN environment variable is set correctly (if accessing a private repo)
  • Verify the token is valid, not expired, and has the repo scope enabled
  • Confirm the repository and model path settings are correct

• ModelDownloadError: ... 403 Forbidden ...:

  • Usually indicates the provided GITHUB_TOKEN lacks necessary permissions

• FloorplanPredictorError: GITHUB_TOKEN is required...:

  • Set the GITHUB_TOKEN environment variable for private repository access

• FileNotFoundError or ImageLoadError:

  • Ensure the image path is correct and the file exists
  • Verify the image format is supported (JPEG, PNG, etc.)

• ONNX Runtime Issues:

  • Ensure onnxruntime is installed correctly for your OS
  • Check Python version compatibility

Running Tests (Development)

1. Clone the repository
2. Install development dependencies: pip install -r requirements.txt
3. Set the GITHUB_TOKEN environment variable if testing with private repo
4. Place test images in the root directory
5. Run the test script: python test.py

Requirements

• Python >= 3.7
• onnxruntime >= 1.12.0
• onnxruntime-extensions
• numpy >= 1.19.0
• torch >= 2.0.0
• torchvision >= 0.15.0
• huggingface-hub
• sentencepiece
• opencv-python-headless
• ftfy
• regex
• scipy
• gdown
• Pillow >= 10.0.0
• tqdm >= 4.65.0

License

MIT License

Author

Oliver Brown