{"id":26454134,"url":"https://github.com/coolapso/aeye","last_synced_at":"2026-05-04T00:34:59.611Z","repository":{"id":279948940,"uuid":"940225172","full_name":"coolapso/aeye","owner":"coolapso","description":"A set of tools to train and run a **Convolutional Neural Network (CNN)** for object detection.  ","archived":false,"fork":false,"pushed_at":"2025-11-30T16:02:43.000Z","size":83682,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-02T23:24:23.213Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coolapso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"coolapso","buy_me_a_coffee":"coolapso"}},"created_at":"2025-02-27T20:18:39.000Z","updated_at":"2025-11-30T16:02:31.000Z","dependencies_parsed_at":"2025-03-26T20:40:52.649Z","dependency_job_id":null,"html_url":"https://github.com/coolapso/aeye","commit_stats":null,"previous_names":["coolapso/aeye"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/coolapso/aeye","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coolapso%2Faeye","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coolapso%2Faeye/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coolapso%2Faeye/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coolapso%2Faeye/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coolapso","download_url":"https://codeload.github.com/coolapso/aeye/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coolapso%2Faeye/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32590455,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"ssl_error","status_checked_at":"2026-05-03T22:09:10.534Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-18T19:44:33.384Z","updated_at":"2026-05-04T00:34:59.600Z","avatar_url":"https://github.com/coolapso.png","language":"Python","funding_links":["https://github.com/sponsors/coolapso","https://buymeacoffee.com/coolapso","https://www.buymeacoffee.com/coolapso"],"categories":[],"sub_categories":[],"readme":"# 🤖AEye 👀\n\nA set of tools to train and run a **Convolutional Neural Network (CNN)** for object detection.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/coolapso/aeye/refs/heads/main/images/demo.gif\"\u003e\n\u003c/p\u003e\n\n## Why This Project Exists\n\nHave you ever wanted to create a custom AI model that analyzes video feeds or images and generates alerts or notifications—without breaking the bank or handing your data over to big corporations? This repository is designed to make that possible, offering an **accessible** and **cost-effective** way to deploy AI-powered image analysis.\n\nWhen I moved to the **Arctic Circle**, where the **Northern Lights** are a common sight, I launched [The Arctic Skies](https://www.youtube.com/@TheArcticSkies) to **capture and share these breathtaking moments** with the world. While setting up my livestream, I had one thought:\n\n\u003e **\"How cool would it be to have an AI model watching the sky and notifying me when an aurora appears?\"**\n\nAfter some research, I realized two things:\n\n- I couldn't find any **pre-trained models** specifically for detecting the Northern Lights.\n- There weren’t many **accessible tools** or **clear documentation** on how to build one.\n\nSo, I rolled up my sleeves and built this repository—a **set of tools to train and run AI models using TensorFlow and Keras**. And since I was already doing the work, I made it **generic and reusable**—so anyone can use it for their own projects.\n\nWhether you're tracking auroras, wildlife, or any other visual phenomenon, this project is here to help you build your own **AI-powered image detection system**.\n\n## Features\n\n✅ **class detection** – the model can be trained to detect diferent classes of objects, ex: cat, dogs, birds, etc. In My case I am training it to detect northern lights in diferent scenarios: Clear skies, Aurora in clear sky, Cloudy skies, aurora in cloudy sky, and each is a class.\n\n✅ **Efficient Image Resizing** – High-resolution images are **resource-intensive** and often unnecessary for training the sorting tool will **downscale images** to an optimal resolution.\n\n✅ **Train Your Own AI Model** – Use `train.py` to **train a custom TensorFlow/Keras model** on your dataset. Currently, only **binary classification** (detected/not detected) is supported. If you need multi-class detection, feel free to open an issue—I’d be happy to add support for it!\n\n✅ **Real-Time Model Execution with Metrics** – The main application **runs your trained model** and generates **Prometheus-formatted metrics**, which can be scraped by **Prometheus** or other monitoring tools.\n\n✅ **Dockerized Deployment** – Easily deploy your model in a **Docker container** using the provided image, or build your own from the base image.\n\n## Requirements\n\n- **Python 3.12**\n- **OpenCV \u0026 TensorFlow**\n- Check your OS documentation on how to install them.\n\n---\n\n## How It Works\n\nEven though this repository simplifies the process significantly, there’s still some work to do! Hopefully, this documentation will guide you through it smoothly.\n\n### 1️⃣ Collect Training Dat\n\nTo train the AI model, you need an **initial dataset**. While smaller datasets work the more data you have the better. ideally you should have 60% of your dataset for training, 20% for validation and 20% for testing. this being said, having a dataset with at least:\n\n- *800* images per obect for training\n- *200* images per object for validation\n- *200* images per object for testing\n\nFor **best performance**, images should be resized to a smaller resolution. Training on full-resolution images provides **little benefit** but requires significantly more resources.\n\nSorting images can be tedious, but the `sort.py` script helps automate this process.\n\n---\n\n## 2️⃣ Set Up the Environment\n\nBefore using the tools, set up a **virtual environment** and install dependencies:\n\n```sh\npython -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\npip install -r tools/requirements.txt\n```\n\n---\n\n## 3️⃣ Prepare the Images\nUse [picsort](https://github.com/coolapso/picsort) to categorize images, this tool will provide you with a nice UI and ergonomic workflow to sort your images and will allow you to export a balanced dataset divided into training, validation and testing sets.\n\n---\n\n## 4️⃣ Train the Model\nUse `train.py` to train the AI model, the script expect you to have training, validation and testing datasets, you can use the ones you created with picsort.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/coolapso/aeye/refs/heads/main/images/train-demo.gif\"\u003e\n\u003c/p\u003e\n\n```sh\npython tools/train.py -t dataset/balanced_export_full/training -v dataset/balanced_export_full/validation -e dataset/balanced_export_full/test --output models/test_full_3.keras\n```\n\n---\n\n## 5️⃣ Run the Model\n\nThe application loads the trained model and generates **Prometheus metrics** for monitoring.\n\n### Configuration via Environment Variables:\n\n| Variable Name            | Description | Default Value |\n|--------------------------|-------------|--------------|\n| `VIDEO_SOURCE`           | Video file or RTSP stream for analysis | - |\n| `MODEL_NAME`             | Model filename (must be in `models/` directory) | - |\n| `BASE_MODEL_NAME`        | Base model used for transfer learning (`mobilenet` or `efficientnet`) | `efficientnet` |\n| `MODE`                   | Operation mode (`default`, `testing`) | `default` |\n| `READ_ALL_FRAMES`        | Analyze every frame instead of 1 FPS | `false` |\n\nMetrics are available at [`http://localhost:8000`](http://localhost:8000).\n\n### Running Locally\n\nActivate the virtual environment and run:\n\n```sh\nVIDEO_SOURCE=\"...\" MODEL_NAME=\"my_model.keras\" BASE_MODEL_NAME=\"mobilenet\" python src/aeye.py\n```\n\n---\n\n### Running with Docker\n\n```sh\ndocker run -tid -p 8000:8000 -v models/:models/ \\\n  -e VIDEO_SOURCE=\"...\" -e MODEL_NAME=\"my_model.keras\" -e BASE_MODEL_NAME=\"mobilenet\" my_docker_image\n```\n\n---\n\n#### 🛠️ Build Your Own Docker Image\n\nWhile the main Docker image **contains models trained for** [The Arctic Skies](https://youtube.com/@TheArcticSkies), a **base image** without any pre-bundled models is also provided. You can use it to build your own Docker image and bundle your custom model.\n\n**Example Dockerfile:**\n\n```dockerfile\nFROM ghcr.io/coolapso/AICoach:latest-base\nCOPY models/yourmodel.keras models/yourmodel.keras\n```\n\nYou can also set environment variables directly in the Dockerfile instead of passing them at runtime:\n\n```dockerfile\nFROM ghcr.io/coolapso/AICoach:latest-base\nCOPY models/yourmodel.keras models/yourmodel.keras\nENV MODEL_NAME=yourmodel.keras\nENV VIDEO_SOURCE=\"...\"\n```\n\n## Exposed metrics\n\n| Metric name               | Type  | Description                                                           |\n|---------------------------|-------|-----------------------------------------------------------------------|\n| aeye_detected_class_index | Gauge | The index of the detected class.                                      |\n| aeye_confidence           | Gauge | The confidence of the detection                                       |\n\n# 🤝 Contributions\n\nAll contributions are welcome!\n\nI’m still learning in this domain, and I’d love to make this project more **user-friendly and accessible** for a broader audience—not just makers and developers!\n\nIf you’d like to support the project:\n[:heart: Sponsor Me](https://github.com/sponsors/coolapso) or\n\n[![Buy Me a Coffee](https://cdn.buymeacoffee.com/buttons/default-yellow.png)](https://www.buymeacoffee.com/coolapso)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoolapso%2Faeye","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoolapso%2Faeye","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoolapso%2Faeye/lists"}