sober-scan 0.0.5

A CLI tool that detects alcohol intoxication from facial images.

Sober Scan

A CLI tool that detects alcohol intoxication and drowsiness from facial images.

#Alcohol Intoxication   #Facial Recognition   #CLI

---

🚀 Getting Started

It is recommended to use uv to create a virtual environment and pip install the following package.

pip install sober-scan

To run the application, simply type:

sober-scan
# or
sober-scan --help

---

✨ New Features

🔄 Incremental Learning & Model Management

Sober-Scan now supports incremental learning, allowing you to update models with new data without full retraining:

• Incremental Learning: Update SVM, Naive Bayes, KNN, and RF models with new data
• CNN Fine-Tuning: Continue training CNN models from existing weights
• Data Augmentation: Automatic augmentation for improved CNN accuracy
• Model Versioning: Automatic backups and version control for all models
• Dataset Management: Register, merge, split, and organize datasets

Quick Examples:

# Fine-tune CNN with new data (recommended for adding data)
sober-scan train /path/to/new_data \
  --model cnn \
  --model-path models/intoxication_cnn.pt \
  --continue-training \
  --backup \
  --save-model

# Incremental learning with Naive Bayes
sober-scan train /path/to/new_data \
  --model nb \
  --incremental \
  --save-model

# Manage model versions
sober-scan manage version list intoxication_cnn
sober-scan manage version restore intoxication_cnn --version <timestamp>

# Manage datasets
sober-scan manage dataset register my_data /path/to/data
sober-scan manage dataset merge dataset1,dataset2 combined

📖 See QUICK_REFERENCE.md for complete command reference and examples.

---

👨‍💻 Development Setup

1. Clone the repository and navigate to project folder:

   git clone https://github.com/Sang-Buster/Sober-Scan
   cd Sober-Scan
   

2. Install uv first:

   # macOS/Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   # Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   

3. Create a virtual environment at Sober-Scan/.venv/:

   uv venv --python 3.10
   

4. Activate the virtual environment:

   # macOS/Linux
   source .venv/bin/activate
   

   # Windows
   .venv\Scripts\activate
   

5. Install the required packages:

   uv pip install -e .
   

6. Install ruff and pre-commit:

   uv pip install ruff pre-commit
   

   • ruff is a super fast Python linter and formatter.
   • pre-commit helps maintain code quality by running automated checks before commits are made.

7. Install git hooks:

   pre-commit install --hook-type commit-msg --hook-type pre-commit --hook-type pre-push
   

   These hooks perform different checks at various stages:

   • commit-msg: Ensures commit messages follow the conventional format
   • pre-commit: Runs Ruff linting and formatting checks before each commit
   • pre-push: Performs final validation before pushing to remote

8. Code Linting:

   ruff check
   ruff check --fix
   ruff check --select I
   ruff check --select I --fix
   ruff format
   

9. Run the application:

   uv run src/sober_scan/cli.py
   

---

📝 File Structure

📂Sober-Scan
 ┣ 📂src                         // Source Code
 ┃ ┗ 📦sober_scan                  // Python package
 ┃ ┃ ┣ 📂commands                      // Command line interface
 ┃ ┃ ┃ ┣ 📄detect.py
 ┃ ┃ ┃ ┣ 📄model.py
 ┃ ┃ ┃ ┗ 📄train.py
 ┃ ┃ ┣ 📂models                        // Model files
 ┃ ┃ ┃ ┣ 📄cnn.py
 ┃ ┃ ┃ ┣ 📄knn.py
 ┃ ┃ ┃ ┣ 📄nb.py
 ┃ ┃ ┃ ┣ 📄rf.py
 ┃ ┃ ┃ ┗ 📄svm.py
 ┃ ┃ ┣ 📂tests                         // Test files
 ┃ ┃ ┃ ┗ 📄test_cli.py
 ┃ ┃ ┣ 📄cli.py                        // CLI interface
 ┃ ┃ ┣ 📄config.py                     // Configuration
 ┃ ┃ ┣ 📄feature_extraction.py         // Feature extraction
 ┃ ┃ ┗ 📄utils.py                      // Utility functions
 ┣ 📄.gitignore                  // Git ignore patterns (env, cache, database)
 ┣ 📄.pre-commit-config.yaml     // Pre-commit hooks (ruff, commit message)
 ┣ 📄.pre-commit_msg_template.py // Commit message format validator
 ┣ 📄.python-version             // Python version
 ┣ 📄LICENSE                     // MIT License
 ┣ 📄README.md                   // Project documentation
 ┣ 📄pyproject.toml              // Project configuration
 ┗ 📄uv.lock                     // Lock file