Big Cat Classifier

🚀 Big Cat Classifier

An image classifier built using Vision Transformers to categorize big cat images into different classes.

🚀 Quick Start

This is an image classifier based on Vision Transformers, which can classify big cat images into several classes.

✨ Features

• Classify images of big cats into five classes: Cheetah, Jaguar, Leopard, Lion, and Tiger.
• Provide training and inference notebooks on Google Colab.
• Offer a hosted API and a library app for easy use.

📦 Installation

Library App Installation

• Clone this repository

git clone https://github.com/smaranjitghose/Big_Cat_Classifier.git

• Move inside the cloned repository

cd Big_Cat_Classifier

• Without using Docker:
  • Make sure you have installed the latest stable version Python 3 and added it to PATH
  • Install the python dependencies

pip install -r requirements.txt

- Start the streamlit app on local server

streamlit run app.py

• Using Docker:
  • Make sure you have installed Docker
  • Build the Docker Image

docker build -t smaranjitghose/big-cat-classifier:latest .

- Check if the image is available

docker images

- Create a Docker container from the image and Run it

docker run -t -i -p 8080:8080 --name "big-cat-classifier" smaranjitghose/big-cat-classifier

- Open your browser and visit `localhost:8080`

💻 Usage Examples

Basic Usage

from PIL import Image
import matplotlib.pyplot as plt
from transformers import ViTFeatureExtractor, ViTForImageClassification

def identify_big_cat(img_path:str)->str:
  """
  Function that reads an image of a big cat (belonging to Panthera family) and returns the corresponding species
  """
  img = Image.open(img_path)
  model_panthera = ViTForImageClassification.from_pretrained("smaranjitghose/big-cat-classifier")
  feature_extractor = ViTFeatureExtractor.from_pretrained('smaranjitghose/big-cat-classifier')
  inputs = feature_extractor(images=img, return_tensors="pt")
  outputs = model_panthera(**inputs)
  logits = outputs.logits
  predicted_class_idx = logits.argmax(-1).item()
  return model_panthera.config.id2label[predicted_class_idx]


 our_big_cat = identify_big_cat("path_of_the_image")
 print(f"Predicted species: {our_big_cat}" )

📚 Documentation

Model Information

Class Table

Class	Big Cat	Sample Image
0	Cheetah
1	Jaguar
2	Leopard
3	Lion
4	Tiger

Notes

⚠️ Important Note

• Since jaguars and leopards have similar appearances, the model might confuse the two. These [1] [2] two articles throw some light on the difference between the two species.
• Theoretically the model should be able to accurately identify geographical population variants of each species. However, in practical scenarios this may not be true as during the training phases this was not kept in mind while collecting the dataset.
  • For example: images of Bengal Tigers, Siberian Tigers, Indochinese Tigers, and Malayan Tigers should be identified as Tigers
• Lastly, the performance of the model in categorizing certain rare variants in the populations of big cats such as white tigers, snow leopards, or black panther has not been determined exclusively. Although some of the tests performed gave satisfactory results.

Training and Inference

• Training:
• Inference:

Hosted API

Check it out here

Hosting on Heroku

1. Remove the lines that exposed the particular port in the docker container
2. Make sure the startup command is exposed with a variable Port Number

ENTRYPOINT ["streamlit", "run", "app.py", "--server.port=$PORT"]

3. Login to Heroku

heroku login -i

4. Create a new Heroku app

heroku create

5. Login in to Container Registry

heroku container:login

6. Build the Docker image and push it to Container Registry

heroku container:push web

7. Release the app

heroku container:release web

8. Check the hosted version and dashboard

heroku open

📄 Reference and Acknowledgement

Hugging Pics