{"id":31762273,"url":"https://github.com/marcosotomac/ml-geometry","last_synced_at":"2026-05-08T14:02:48.016Z","repository":{"id":318438869,"uuid":"1071286740","full_name":"marcosotomac/ml-geometry","owner":"marcosotomac","description":"machine learning model for geometric images recognition","archived":false,"fork":false,"pushed_at":"2025-10-07T06:58:48.000Z","size":99,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-07T08:31:37.610Z","etag":null,"topics":["cnn-classification","computer-vision","deep-learning","keras","machine-learning","tensorflow","transfer-learning"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcosotomac.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-10-07T06:21:45.000Z","updated_at":"2025-10-07T06:58:52.000Z","dependencies_parsed_at":"2025-10-07T08:41:46.523Z","dependency_job_id":null,"html_url":"https://github.com/marcosotomac/ml-geometry","commit_stats":null,"previous_names":["marcosotomac/ml-geometry"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/marcosotomac/ml-geometry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcosotomac%2Fml-geometry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcosotomac%2Fml-geometry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcosotomac%2Fml-geometry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcosotomac%2Fml-geometry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcosotomac","download_url":"https://codeload.github.com/marcosotomac/ml-geometry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcosotomac%2Fml-geometry/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002122,"owners_count":26083307,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["cnn-classification","computer-vision","deep-learning","keras","machine-learning","tensorflow","transfer-learning"],"created_at":"2025-10-09T22:17:36.846Z","updated_at":"2025-10-09T22:17:38.224Z","avatar_url":"https://github.com/marcosotomac.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ML Geometry Detector - Production MLOps System\n\nAdvanced Machine Learning system with complete MLOps pipeline for detection and classification of geometric shapes using Deep Learning architectures.\n\n## Features\n\n### Core ML Capabilities\n- **Synthetic Dataset Generation**: Automated creation of training datasets with 10 geometric shapes\n- **Custom CNN Architecture**: Convolutional neural network with ResNet blocks and SE-Net attention\n- **Transfer Learning Support**: EfficientNet, ResNet, MobileNet pretrained models\n- **Advanced Data Augmentation**: Albumentations pipeline for robust generalization\n- **Multi-Object Detection**: Sliding window, region proposals, contour detection methods\n- **REST API**: FastAPI server for real-time predictions with batch support\n\n### MLOps Production Features\n- **Model Registry**: Version control and lifecycle management (development → staging → production)\n- **Experiment Tracking**: MLflow integration for tracking all training runs\n- **Model Monitoring**: Prometheus metrics, drift detection, performance tracking\n- **CI/CD Pipeline**: GitHub Actions for automated testing, building, and deployment\n- **Containerization**: Docker and Docker Compose for reproducible environments\n- **Orchestration**: Kubernetes deployment with horizontal pod autoscaling\n- **Observability**: Grafana dashboards for real-time monitoring\n\n## Quick Start\n\n### Basic Installation\n\n```bash\n# Clone repository\ngit clone https://github.com/marcosotomac/ml-geometry.git\ncd ml-geometry\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # Windows: venv\\Scripts\\activate\n\n# Install dependencies\npip install -r requirements.txt\n```\n\n### MLOps Setup\n\n```bash\n# Install MLOps dependencies\npip install -r requirements-mlops.txt\n\n# Start MLOps stack with Docker\ndocker-compose up -d\n\n# Access services:\n# - API: http://localhost:8000\n# - MLflow: http://localhost:5000\n# - Prometheus: http://localhost:9090\n# - Grafana: http://localhost:3000\n```\n\n## Documentation\n\n- **[MLOPS.md](MLOPS.md)**: Complete MLOps implementation guide\n- **[MLOPS_SUMMARY.md](MLOPS_SUMMARY.md)**: MLOps features summary\n- **[QUICKSTART_MLOPS.md](QUICKSTART_MLOPS.md)**: Quick start for MLOps\n- **[QUICKSTART.md](QUICKSTART.md)**: Getting started tutorial\n- **[API Documentation](http://localhost:8000/docs)**: Interactive API documentation\n\n## MLOps Workflow\n\n```mermaid\ngraph TB\n    subgraph Development\n        A[Train Model] --\u003e B[MLflow Tracking]\n        B --\u003e C[Model Registry]\n        C --\u003e D{Model Ready?}\n    end\n    \n    subgraph Staging\n        D --\u003e|Yes| E[Promote to Staging]\n        E --\u003e F[Integration Tests]\n        F --\u003e G{Tests Pass?}\n    end\n    \n    subgraph Production\n        G --\u003e|Yes| H[Promote to Production]\n        H --\u003e I[Deploy to K8s]\n        I --\u003e J[Monitor with Prometheus]\n        J --\u003e K[Grafana Dashboards]\n    end\n    \n    subgraph Monitoring\n        K --\u003e L{Drift Detected?}\n        L --\u003e|Yes| M[Alert \u0026 Retrain]\n        L --\u003e|No| N[Continue Monitoring]\n        M --\u003e A\n        N --\u003e K\n    end\n    \n    style A fill:#e1f5ff\n    style B fill:#e1f5ff\n    style C fill:#e1f5ff\n    style E fill:#fff4e1\n    style F fill:#fff4e1\n    style H fill:#e1ffe1\n    style I fill:#e1ffe1\n    style J fill:#ffe1e1\n    style K fill:#ffe1e1\n```\n\n## Quick Commands\n\n```bash\n# Development\nmake install          # Install all dependencies\nmake train           # Train model with MLOps\n\n# Docker\nmake docker-stack    # Start full MLOps stack\n\n# Deployment\npython deploy_model.py --model-name custom --version 1.0.0 --source-stage staging\n\n# Monitoring\nmake mlflow          # Open MLflow UI (http://localhost:5000)\nmake grafana         # Open Grafana (http://localhost:3000)\n\n# Testing\nmake test           # Run all tests\nmake lint           # Check code quality\n```\n\n## Supported Shapes\n\n- Circle\n- Square\n- Rectangle\n- Triangle\n- Pentagon\n- Hexagon\n- Octagon\n- Star\n- Rhombus\n- Ellipse\n\n## Usage\n\n### Training with MLOps\n\n```bash\n# Train with experiment tracking and model registry\npython train_mlops.py \\\n  --model-type custom \\\n  --experiment-name ml-geometry \\\n  --register-model \\\n  --model-version 1.0.0 \\\n  --stage development\n```\n\n### Model Deployment Pipeline\n\n```bash\n# 1. Promote to staging\npython deploy_model.py \\\n  --model-name custom \\\n  --version 1.0.0 \\\n  --source-stage development\n\n# 2. Deploy to production\npython deploy_model.py \\\n  --model-name custom \\\n  --version 1.0.0 \\\n  --source-stage staging\n\n# 3. Deploy to Kubernetes\nkubectl apply -f k8s/deployment.yaml\n```\n\n### Dataset Generation\n```python\nfrom src.data.dataset_generator import GeometricShapeGenerator\n\ngenerator = GeometricShapeGenerator(img_size=224, shapes_per_class=1000)\n### Dataset Generation\n\n```python\nfrom src.data.dataset_generator import GeometricShapeGenerator\n\ngenerator = GeometricShapeGenerator(img_size=224, shapes_per_class=1000)\ngenerator.generate_dataset('data/synthetic')\n```\n\n### Model Training\n\n```python\nfrom src.models.train import train_model\n\ntrain_model(\n    data_dir='data/synthetic',\n    model_type='custom_cnn',\n    epochs=50,\n    batch_size=32\n)\n```\n\n### Predictions\n\n```python\nfrom src.models.predictor import ShapePredictor\n\npredictor = ShapePredictor('models/best_model.h5')\nprediction = predictor.predict('path/to/image.jpg')\nprint(f\"Shape: {prediction['class']}, Confidence: {prediction['confidence']:.2%}\")\n```\n\n### API Server\n\n```bash\npython src/api/main.py\n```\n\nAccess interactive documentation at http://localhost:8000/docs\n\n## Workflow Diagram\n\n### Complete ML Pipeline\n\n```mermaid\ngraph TB\n    Start([Start]) --\u003e DataGen[Data Generation]\n    \n    subgraph \"1. Dataset Creation\"\n        DataGen --\u003e GenShapes[Generate 10 Shape Classes\u003cbr/\u003e1000 samples per class]\n        GenShapes --\u003e Augment[Apply Augmentation\u003cbr/\u003eRotation, Flip, Noise, etc.]\n        Augment --\u003e Split[Train/Val/Test Split\u003cbr/\u003e70% / 15% / 15%]\n        Split --\u003e SaveData[(data/synthetic/)]\n    end\n    \n    SaveData --\u003e DataLoad[Data Loading]\n    \n    subgraph \"2. Data Preprocessing\"\n        DataLoad --\u003e Normalize[Normalize Images\u003cbr/\u003e0-1 range]\n        Normalize --\u003e Batch[Create Batches\u003cbr/\u003eDefault: 32]\n        Batch --\u003e RuntimeAug[Runtime Augmentation\u003cbr/\u003eTrain only]\n    end\n    \n    RuntimeAug --\u003e ModelChoice{Choose Architecture}\n    \n    subgraph \"3. Model Creation\"\n        ModelChoice --\u003e|Option 1| CustomCNN[Custom CNN\u003cbr/\u003eResNet + Attention]\n        ModelChoice --\u003e|Option 2| LightCNN[Lightweight CNN\u003cbr/\u003eFast Training]\n        ModelChoice --\u003e|Option 3| Transfer[Transfer Learning\u003cbr/\u003eEfficientNet/ResNet]\n        \n        CustomCNN --\u003e ModelBuild[Build Model\u003cbr/\u003eInput: 224x224x3\u003cbr/\u003eOutput: 10 classes]\n        LightCNN --\u003e ModelBuild\n        Transfer --\u003e ModelBuild\n    end\n    \n    ModelBuild --\u003e Train[Training Pipeline]\n    \n    subgraph \"4. Training\"\n        Train --\u003e Compile[Compile Model\u003cbr/\u003eOptimizer: Adam/SGD\u003cbr/\u003eLoss: CrossEntropy]\n        Compile --\u003e Callbacks[Setup Callbacks\u003cbr/\u003eEarly Stop, Checkpoint\u003cbr/\u003eLR Scheduler, TensorBoard]\n        Callbacks --\u003e Epochs[Train Epochs\u003cbr/\u003e50-100 iterations]\n        Epochs --\u003e SaveModel[(Save Model\u003cbr/\u003emodels/saved_models/)]\n    end\n    \n    SaveModel --\u003e Eval[Evaluation]\n    \n    subgraph \"5. Evaluation\"\n        Eval --\u003e Predict[Generate Predictions\u003cbr/\u003eTest Set]\n        Predict --\u003e Metrics[Calculate Metrics\u003cbr/\u003eAccuracy, Precision\u003cbr/\u003eRecall, F1-Score]\n        Metrics --\u003e Viz[Create Visualizations\u003cbr/\u003eConfusion Matrix\u003cbr/\u003eROC Curves]\n        Viz --\u003e SaveResults[(results/)]\n    end\n    \n    SaveResults --\u003e Deploy{Deployment Option}\n    \n    subgraph \"6. Deployment\"\n        Deploy --\u003e|Option A| DirectPred[Direct Prediction\u003cbr/\u003eShapePredictor]\n        Deploy --\u003e|Option B| API[REST API\u003cbr/\u003eFastAPI Server]\n        Deploy --\u003e|Option C| MultiDet[Multi-Object Detection\u003cbr/\u003eSliding Window/Contours]\n        \n        DirectPred --\u003e Output[/Output: Class + Confidence/]\n        API --\u003e Output\n        MultiDet --\u003e Output\n    end\n    \n    Output --\u003e End([End])\n    \n    style Start fill:#4CAF50,stroke:#2E7D32,color:#fff\n    style End fill:#4CAF50,stroke:#2E7D32,color:#fff\n    style SaveData fill:#2196F3,stroke:#1565C0,color:#fff\n    style SaveModel fill:#2196F3,stroke:#1565C0,color:#fff\n    style SaveResults fill:#2196F3,stroke:#1565C0,color:#fff\n    style Output fill:#FF9800,stroke:#E65100,color:#fff\n```\n\n### Inference Flow\n\n```mermaid\ngraph LR\n    A[Input Image\u003cbr/\u003eAny Size] --\u003e B[Preprocessing]\n    \n    subgraph Preprocessing\n        B --\u003e B1[Resize to 224x224]\n        B1 --\u003e B2[Normalize 0-1]\n        B2 --\u003e B3[Convert to Tensor]\n    end\n    \n    B3 --\u003e C[Model Forward Pass]\n    \n    subgraph \"Model Inference\"\n        C --\u003e C1[Feature Extraction\u003cbr/\u003eConv Layers]\n        C1 --\u003e C2[Channel Attention\u003cbr/\u003eSE-Net]\n        C2 --\u003e C3[Classification Head\u003cbr/\u003eDense + Softmax]\n    end\n    \n    C3 --\u003e D[Post-processing]\n    \n    subgraph \"Output Processing\"\n        D --\u003e D1[Apply Softmax]\n        D1 --\u003e D2[Get ArgMax\u003cbr/\u003ePredicted Class]\n        D2 --\u003e D3[Extract Confidence]\n    end\n    \n    D3 --\u003e E[/Output\u003cbr/\u003eClass Name\u003cbr/\u003eConfidence Score\u003cbr/\u003eAll Probabilities/]\n    \n    style A fill:#4CAF50,stroke:#2E7D32,color:#fff\n    style E fill:#FF9800,stroke:#E65100,color:#fff\n```\n\n### Multi-Object Detection Pipeline\n\n```mermaid\ngraph TB\n    Input[Input Image] --\u003e Method{Detection Method}\n    \n    Method --\u003e|Method 1| SW[Sliding Window]\n    Method --\u003e|Method 2| RP[Region Proposals\u003cbr/\u003eSelective Search]\n    Method --\u003e|Method 3| CD[Contour Detection]\n    \n    subgraph \"Sliding Window\"\n        SW --\u003e SW1[Slide 224x224 window\u003cbr/\u003eStride: 56px]\n        SW1 --\u003e SW2[Classify each window]\n        SW2 --\u003e SW3[Filter by confidence]\n    end\n    \n    subgraph \"Region Proposals\"\n        RP --\u003e RP1[Generate proposals\u003cbr/\u003eSelective Search]\n        RP1 --\u003e RP2[Resize regions to 224x224]\n        RP2 --\u003e RP3[Classify each region]\n        RP3 --\u003e RP4[Filter by confidence]\n    end\n    \n    subgraph \"Contour Detection\"\n        CD --\u003e CD1[Convert to grayscale]\n        CD1 --\u003e CD2[Apply threshold]\n        CD2 --\u003e CD3[Find contours]\n        CD3 --\u003e CD4[Extract bounding boxes]\n        CD4 --\u003e CD5[Classify each region]\n        CD5 --\u003e CD6[Filter by confidence]\n    end\n    \n    SW3 --\u003e NMS[Non-Maximum Suppression\u003cbr/\u003eIoU threshold: 0.3]\n    RP4 --\u003e NMS\n    CD6 --\u003e NMS\n    \n    NMS --\u003e Visual[Visualize Detections\u003cbr/\u003eDraw bboxes + labels]\n    Visual --\u003e Output[/Output:\u003cbr/\u003eList of detections\u003cbr/\u003ebbox, class, confidence/]\n    \n    style Input fill:#4CAF50,stroke:#2E7D32,color:#fff\n    style Output fill:#FF9800,stroke:#E65100,color:#fff\n    style NMS fill:#9C27B0,stroke:#6A1B9A,color:#fff\n```\n\n## Model Architecture\n\n```\nml-geometry/\n├── data/\n│   ├── synthetic/       # Dataset generado\n│   └── real/            # Imágenes reales (opcional)\n├── models/\n│   ├── saved_models/    # Modelos entrenados\n│   └── checkpoints/     # Checkpoints de entrenamiento\n├── src/\n│   ├── data/            # Generación y procesamiento de datos\n│   ├── models/          # Arquitecturas y entrenamiento\n│   ├── evaluation/      # Métricas y visualizaciones\n│   └── api/             # API REST\n├── notebooks/           # Jupyter notebooks para experimentación\n├── tests/               # Tests unitarios\n└── configs/             # Archivos de configuración\n## Model Architecture\n\n### Custom CNN Architecture\n\nThe model follows a hierarchical structure with four main stages:\n\n**Input Layer**\n- Input shape: 224x224x3 (RGB images)\n\n**Initial Convolution**\n- Conv2D: 7x7 kernel, 64 filters, stride 2\n- Batch Normalization + ReLU activation\n- MaxPooling: 3x3, stride 2\n\n**Stage 1** (Output: 56x56x64)\n- 2x ResNet blocks with 64 filters\n- Channel Attention mechanism\n- Skip connections for residual learning\n\n**Stage 2** (Output: 28x28x128)\n- 3x ResNet blocks with 128 filters\n- Downsampling via stride 2\n- Channel Attention mechanism\n\n**Stage 3** (Output: 14x14x256)\n- 4x ResNet blocks with 256 filters\n- Downsampling via stride 2\n- Channel Attention mechanism\n\n**Stage 4** (Output: 7x7x512)\n- 3x ResNet blocks with 512 filters\n- Downsampling via stride 2\n- Channel Attention mechanism\n\n**Classification Head**\n- Global Average Pooling\n- Dense layer: 512 units + ReLU + Dropout (0.3)\n- Dense layer: 256 units + ReLU + Dropout (0.15)\n- Output layer: 10 units + Softmax\n\n### ResNet Block Structure\n\nEach ResNet block contains:\n- Conv2D (3x3) + BatchNorm + ReLU\n- Conv2D (3x3) + BatchNorm\n- Skip connection (identity or 1x1 conv for dimension matching)\n- Addition + ReLU + Dropout\n- L2 regularization (1e-4)\n\n### Channel Attention (SE-Net)\n\n- Global Average Pooling across spatial dimensions\n- Dense layer with reduction (filters / 16)\n- ReLU activation\n- Dense layer to original filter size\n- Sigmoid activation\n- Element-wise multiplication with input\n\n### Regularization Techniques\n\n- **Dropout**: 0.3 in residual blocks, 0.15 in classification head\n- **L2 Weight Decay**: 1e-4 on all convolutional and dense layers\n- **Batch Normalization**: After each convolution for training stability\n- **Data Augmentation**: Rotation, shifts, flips, zoom, brightness, contrast\n\n### Transfer Learning Models\n\nAvailable pretrained architectures:\n\n**EfficientNet B0/B3**\n- Compound scaling method (depth, width, resolution)\n- Mobile inverted bottleneck convolutions\n- Optimal efficiency-accuracy tradeoff\n\n**ResNet50/101**\n- Deep residual learning framework\n- 50/101 layers with skip connections\n- Proven performance on ImageNet\n\n**MobileNetV2/V3**\n- Depthwise separable convolutions\n- Inverted residuals with linear bottlenecks\n- Optimized for mobile and embedded devices\n\nAll transfer learning models include:\n- Pretrained ImageNet weights (1000 classes)\n- Custom classification head: 512 → 256 → num_classes\n- Batch Normalization in classification head\n- Optional fine-tuning of last N layers\n\n## Project Structure\n\n```\nml-geometry/\n├── data/\n│   ├── synthetic/       # Generated dataset\n│   └── real/            # Real images (optional)\n├── models/\n│   ├── saved_models/    # Trained models\n│   └── checkpoints/     # Training checkpoints\n├── src/\n│   ├── data/            # Data generation and processing\n│   ├── models/          # Model architectures and training\n│   ├── evaluation/      # Metrics and visualizations\n│   └── api/             # REST API\n├── notebooks/           # Jupyter notebooks\n├── tests/               # Unit tests\n└── configs/             # Configuration files\n```\n\n## Performance Metrics\n\nExpected performance with default configuration:\n- Training Accuracy: ~98-99%\n- Validation Accuracy: ~95-97%\n- Test Accuracy: ~95-97%\n\nTransfer learning models typically achieve 1-2% higher accuracy.\n\n## Advanced Features\n\n### Multi-Object Detection\n\n```python\nfrom src.evaluation.multi_detector import MultiShapeDetector\n\ndetector = MultiShapeDetector('models/best_model.h5')\ndetections = detector.detect_shapes_contours(image, confidence_threshold=0.7)\n```\n\n### Custom Training Parameters\n\n```bash\npython train_model.py \\\n    --model_type transfer \\\n    --base_model efficientnet_b0 \\\n    --epochs 100 \\\n    --batch_size 16 \\\n    --learning_rate 0.001 \\\n    --dropout_rate 0.3\n```\n\n## API Endpoints\n\n- `GET /health` - Health check\n- `POST /predict` - Single image prediction\n- `POST /predict/batch` - Batch prediction\n- `GET /classes` - List available classes\n- `GET /model/info` - Model information\n\n## Contributing\n\nContributions are welcome. Please open an issue or pull request.\n\n## License\n\nMIT License\n\n## Author\n\nMarcos Soto Maceda\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcosotomac%2Fml-geometry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcosotomac%2Fml-geometry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcosotomac%2Fml-geometry/lists"}