{"id":22353469,"url":"https://github.com/xza85hrf/flag_prediction_project","last_synced_at":"2026-04-15T18:31:34.179Z","repository":{"id":266283071,"uuid":"868825002","full_name":"Xza85hrf/Flag_Prediction_Project","owner":"Xza85hrf","description":"This application predicts the name of a country (or countries) based on an input flag image. It uses advanced image processing techniques and deep learning models built with PyTorch to classify flags accurately.","archived":false,"fork":false,"pushed_at":"2024-12-03T13:09:09.000Z","size":25123,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-31T13:34:16.910Z","etag":null,"topics":["cross-validation","cuda","data-augmentation","docker","efficientnetb0","flag-recognition","image-classification","machine-learning","mixed-precision-training","mobilenetv2","python","pytorch","resnet","resnet-50","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Xza85hrf.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}},"created_at":"2024-10-07T08:50:44.000Z","updated_at":"2024-12-03T13:10:47.000Z","dependencies_parsed_at":"2024-12-03T14:31:58.745Z","dependency_job_id":null,"html_url":"https://github.com/Xza85hrf/Flag_Prediction_Project","commit_stats":null,"previous_names":["xza85hrf/flag_prediction_project"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xza85hrf%2FFlag_Prediction_Project","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xza85hrf%2FFlag_Prediction_Project/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xza85hrf%2FFlag_Prediction_Project/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Xza85hrf%2FFlag_Prediction_Project/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Xza85hrf","download_url":"https://codeload.github.com/Xza85hrf/Flag_Prediction_Project/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245652433,"owners_count":20650488,"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","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":["cross-validation","cuda","data-augmentation","docker","efficientnetb0","flag-recognition","image-classification","machine-learning","mixed-precision-training","mobilenetv2","python","pytorch","resnet","resnet-50","transfer-learning"],"created_at":"2024-12-04T13:08:37.627Z","updated_at":"2026-04-15T18:31:34.127Z","avatar_url":"https://github.com/Xza85hrf.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flag Prediction Application\r\n\r\n## Overview\r\n\r\nThis application predicts the name of a country (or countries) based on an input flag image. It uses advanced image processing techniques and deep learning models built with PyTorch to classify flags accurately.\r\n\r\n## Table of Contents\r\n\r\n- [Flag Prediction Application](#flag-prediction-application)\r\n  - [Overview](#overview)\r\n  - [Table of Contents](#table-of-contents)\r\n  - [Features](#features)\r\n  - [Project Structure](#project-structure)\r\n  - [Setup](#setup)\r\n    - [Prerequisites](#prerequisites)\r\n    - [Steps](#steps)\r\n  - [Usage](#usage)\r\n    - [Command Line Interface](#command-line-interface)\r\n  - [Running Tests](#running-tests)\r\n  - [Docker Deployment](#docker-deployment)\r\n  - [Conda Environment Setup](#conda-environment-setup)\r\n  - [Configuration](#configuration)\r\n  - [Logs and File Access](#logs-and-file-access)\r\n  - [Troubleshooting](#troubleshooting)\r\n  - [Contributing](#contributing)\r\n  - [License](#license)\r\n\r\n## Features\r\n\r\n- **Automated Flag Image Collection**: Downloads flag images from Wikipedia automatically.\r\n- **Advanced Image Processing**: Preprocesses images for optimal model input.\r\n- **Multiple Deep Learning Models**: Supports ResNet50, MobileNetV2, and EfficientNet-B0 models built with PyTorch for flag classification.\r\n- **Training Pipeline**: Trains the models using processed and augmented flag images.\r\n- **Inference Pipeline**: Predicts the country from a given flag image using the trained models.\r\n- **Command Line Interface (CLI)**: Provides an easy-to-use interface for all functionalities.\r\n- **Extensive Data Augmentation**: Implements flag-specific data augmentation techniques to generate multiple augmented images per flag.\r\n- **Detailed Logging**: Provides comprehensive logs of the training and prediction processes.\r\n- **Transfer Learning**: Utilizes transfer learning for improved performance.\r\n- **Cross-validation**: Implements k-fold cross-validation for more robust model evaluation.\r\n- **Mixed Precision Training**: Utilizes mixed precision training for faster computation on compatible GPUs.\r\n- **Batch Processing and Multiprocessing**: Improves efficiency in image processing and data augmentation.\r\n\r\n## Project Structure\r\n\r\n```sh\r\nflag_prediction_project/\r\n├── data/\r\n│   ├── flag_images/       # Downloaded flag images\r\n│   ├── processed/         # Processed images\r\n├── logs/                  # Log files\r\n├── models/                # Saved models and label encoders\r\n├── src/\r\n│   ├── __init__.py\r\n│   ├── cli.py\r\n│   ├── config.py\r\n│   ├── data_collection.py\r\n│   ├── data_utils.py\r\n│   ├── image_processing.py\r\n│   ├── main.py\r\n│   ├── model.py\r\n│   ├── predict.py\r\n│   ├── train.py\r\n├── tests/\r\n│   ├── __init__.py\r\n│   ├── conftest.py\r\n│   ├── test_cli.py\r\n│   ├── test_data_collection.py\r\n│   ├── test_data_utils.py\r\n│   ├── test_image_processing.py\r\n│   ├── test_model.py\r\n│   ├── test_predict.py\r\n│   ├── test_train.py\r\n├── .dockerignore\r\n├── Conda_Environment_Setup.md\r\n├── Dockerfile\r\n├── nginx.conf\r\n├── pyproject.toml\r\n├── README.md\r\n├── requirements-dev.txt\r\n├── requirements.txt\r\n├── run.py\r\n├── setup.cfg\r\n```\r\n\r\n## Setup\r\n\r\n### Prerequisites\r\n\r\n- Python 3.8 or higher\r\n- pip package manager\r\n- PyTorch 1.9.0 or higher with CUDA support (recommended for faster training)\r\n- NVIDIA GPU (optional but recommended for training and inference)\r\n- Docker (optional but recommended for reproducibility and ease of use)\r\n  \r\n### Steps\r\n\r\n1. **Clone the Repository**\r\n\r\n   ```sh\r\n   git clone https://github.com/Xza85hrf/flag_prediction_project.git\r\n   cd flag_prediction_project\r\n   ```\r\n\r\n2. **Create a Virtual Environment** (Optional but Recommended)\r\n\r\n   ```sh\r\n   python -m venv env\r\n   source env/bin/activate  # On Windows use `env\\Scripts\\activate`\r\n   ```\r\n\r\n3. **Install Dependencies**\r\n\r\n   ```sh\r\n   pip install -r requirements-dev.txt\r\n   ```\r\n\r\n   **Note:** Ensure that PyTorch is installed with CUDA support if you have a compatible GPU. You can install PyTorch with CUDA by following instructions on the [PyTorch website](https://pytorch.org/get-started/locally/).\r\n\r\n4. **Optional: Install the Package**\r\n\r\n   ```sh\r\n   pip install -e .\r\n   ```\r\n\r\n## Usage\r\n\r\n### Command Line Interface\r\n\r\nThe application provides several commands through its Command Line Interface (CLI). Below are detailed explanations of each command, including what they do, what they affect, and any potential side effects:\r\n\r\n1. **Download Flag Images**\r\n\r\n   Python:\r\n\r\n   ```sh\r\n   python run.py download\r\n   ```\r\n\r\n   Docker:\r\n\r\n   ```sh\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data --memory=24g --cpus=16 --shm-size=50g flag_prediction_app download\r\n   ```\r\n\r\n   Example:\r\n\r\n   ```sh\r\n   docker run --gpus all -it --rm -v /home/user/flag_project/data:/app/data --memory=24g --cpus=16 --shm-size=50g flag_prediction_app download\r\n   ```\r\n\r\n   This command downloads flag images from Wikipedia. It populates the `data/flag_images/` directory with the downloaded images. This step is necessary before processing or training.\r\n\r\n   **Effects**: Creates new files in the `data/flag_images/` directory.\r\n   **Side effects**: May overwrite existing files if run multiple times.\r\n\r\n2. **Process and Augment Images**\r\n\r\n   Python:\r\n\r\n   ```sh\r\n   python run.py process --duplicate-times \u003cnumber\u003e\r\n   ```\r\n\r\n   Docker:\r\n\r\n   ```sh\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data --memory=24g --cpus=16 --shm-size=50g flag_prediction_app process --duplicate-times \u003cnumber\u003e\r\n   ```\r\n\r\n   Example:\r\n\r\n   ```sh\r\n   python run.py process --duplicate-times 50\r\n   docker run --gpus all -it --rm -v /home/user/flag_project/data:/app/data --memory=24g --cpus=16 --shm-size=50g flag_prediction_app process --duplicate-times 50\r\n   ```\r\n\r\n   This command processes the downloaded flag images and creates augmented versions. The `--duplicate-times` parameter specifies how many augmented versions to create for each original image.\r\n\r\n   **Effects**: Creates processed and augmented images in the `data/processed/` directory.\r\n   **Side effects**: May overwrite existing processed images if run multiple times.\r\n\r\n3. **Train the Model**\r\n\r\n   Python:\r\n\r\n   ```sh\r\n   python run.py train [--cross-validate] [--models \u003cmodel1\u003e --models \u003cmodel2\u003e ...]\r\n   ```\r\n\r\n   Docker:\r\n\r\n   ```sh\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data -v ${PWD}/models:/app/models -v ${PWD}/logs:/app/logs --memory=24g --cpus=16 --shm-size=50g flag_prediction_app train [--cross-validate] [--models \u003cmodel1\u003e --models \u003cmodel2\u003e ...]\r\n   ```\r\n\r\n   Examples:\r\n\r\n   ```sh\r\n   python run.py train --cross-validate # trains all of the models\r\n   python run.py train --models resnet50 --models efficientnet_b0\r\n\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data -v ${PWD}/models:/app/models -v ${PWD}/logs:/app/logs --memory=24g --cpus=16 --shm-size=50g flag_prediction_app train --cross-validate # trains all of the models\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data -v ${PWD}/models:/app/models -v ${PWD}/logs:/app/logs --memory=24g --cpus=16 --shm-size=50g flag_prediction_app train --models resnet50 --models efficientnet_b0\r\n   ```\r\n\r\n   This command trains the specified model(s) on the processed flag images.\r\n\r\n   - Use `--cross-validate` to perform k-fold cross-validation for more robust model evaluation.\r\n   - Use `--models` to specify which models to train. You can specify multiple models.\r\n\r\n   **Effects**: Creates trained model files in the `models/` directory and generates training logs.\r\n   **Side effects**: Overwrites existing model files with the same names.\r\n   **Side effects**: May take a long time to run depending on the model(s) and dataset\r\n\r\n   **Important Note**: Do NOT use the `--multi-label` argument for this dataset. This argument is intended for datasets with multiple labels per image and does not apply to this flag prediction task.\r\n\r\n4. **Predict a Country from a Flag Image**\r\n\r\n   Python:\r\n\r\n   ```sh\r\n   python run.py predict \u003cpath_to_flag_image\u003e [--model \u003cmodel_name\u003e]\r\n   ```\r\n\r\n   Docker:\r\n\r\n   ```sh\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data -v ${PWD}/models:/app/models -v ${PWD}/images:/app/images --memory=24g --cpus=16 --shm-size=50g flag_prediction_app predict /app/images/\u003cimage_name\u003e [--model \u003cmodel_name\u003e]\r\n   ```\r\n\r\n   Examples:\r\n\r\n   ```sh\r\n   python run.py predict path/to/flag.jpg\r\n   python run.py predict path/to/flag.jpg --model mobilenet_v2\r\n\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data -v ${PWD}/models:/app/models -v /home/user/flag_images:/app/images --memory=24g --cpus=16 --shm-size=50g flag_prediction_app predict /app/images/flag.jpg\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data -v ${PWD}/models:/app/models -v /home/user/flag_images:/app/images --memory=24g --cpus=16 --shm-size=50g flag_prediction_app predict /app/images/flag.jpg --model mobilenet_v2\r\n   ```\r\n\r\n   This command uses a trained model to predict the country for a given flag image.\r\n\r\n   - Specify the path to the flag image you want to predict.\r\n   - Use `--model` to choose a specific model for prediction (optional).\r\n\r\n   **Effects**: Outputs the prediction result to the console and logs.\r\n   **Side effects**: None.\r\n\r\n5. **Full Pipeline**\r\n\r\n   Python:\r\n\r\n   ```sh\r\n   python run.py full-pipeline --duplicate-times \u003cnumber\u003e [--cross-validate] [--models \u003cmodel1\u003e --models \u003cmodel2\u003e ...]\r\n   ```\r\n\r\n   Docker:\r\n\r\n   ```sh\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data -v ${PWD}/models:/app/models -v ${PWD}/logs:/app/logs --memory=24g --cpus=16 --shm-size=50g flag_prediction_app full-pipeline --duplicate-times \u003cnumber\u003e [--cross-validate] [--models \u003cmodel1\u003e --models \u003cmodel2\u003e ...]\r\n   ```\r\n\r\n   Examples:\r\n\r\n   ```sh\r\n   python run.py full-pipeline --duplicate-times 100 --cross-validate # trains all of the models\r\n   python run.py full-pipeline --duplicate-times 100 --models resnet50 --models mobilenet_v2 --models efficientnet_b0\r\n\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data -v ${PWD}/models:/app/models -v ${PWD}/logs:/app/logs --memory=24g --cpus=16 --shm-size=50g flag_prediction_app full-pipeline --duplicate-times 100 --cross-validate   # trains all of the models\r\n\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data -v ${PWD}/models:/app/models -v ${PWD}/logs:/app/logs --memory=24g --cpus=16 --shm-size=50g flag_prediction_app full-pipeline --duplicate-times 100 --models resnet50 --models mobilenet_v2 --models efficientnet_b0\r\n   ```\r\n\r\n   This command runs the entire pipeline: downloading images, processing them, and training the model(s).\r\n\r\n   - `--duplicate-times` specifies the number of augmented images to create.\r\n   - Use `--cross-validate` for cross-validation during training.\r\n   - Specify models with `--models` as in the train command.\r\n\r\n   **Effects**: Downloads images, processes them, trains models, and generates all associated files and logs.\r\n   **Side effects**: May overwrite existing files in data, models, and logs directories.\r\n\r\n**Important Note** Do not use the `--multi-label` argument as it does not apply to this dataset.\r\n\r\n## Running Tests\r\n\r\nTo run all unit tests, execute:\r\n\r\n```sh\r\npytest\r\n```\r\n\r\nTo run a specific test file:\r\n\r\n```sh\r\npytest tests/test_file_name.py\r\n```\r\n\r\nTo run a specific test function:\r\n\r\n```sh\r\npytest tests/test_file_name.py::test_function_name\r\n```\r\n\r\nFor example, to run the `test_download_flag_images` test in the `test_data_collection.py` file:\r\n\r\n```sh\r\npytest tests/test_data_collection.py::test_download_flag_images\r\n```\r\n\r\n## Docker Deployment\r\n\r\n1. **Build the Docker Image**\r\n\r\n   ```sh\r\n   docker build -t flag_prediction_app .\r\n   ```\r\n\r\n2. **Run the Docker Container**\r\n\r\n   Basic command structure:\r\n\r\n   ```bash\r\n   docker run [options] flag_prediction_app [command] [arguments]\r\n   ```\r\n\r\n   Example for training with cross-validation:\r\n\r\n   ```bash\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data -v ${PWD}/models:/app/models -v ${PWD}/logs:/app/logs --memory=24g --cpus=16 --shm-size=50g flag_prediction_app train --cross-validate\r\n   ```\r\n\r\n   This command:\r\n   - Uses all available GPUs (`--gpus all`)\r\n   - Runs the container interactively (`-it`)\r\n   - Removes the container after it exits (`--rm`)\r\n   - Mounts the local `data`, `models`, and `logs` directories\r\n   - Limits memory usage to 24GB (`--memory=24g`)\r\n   - Limits CPU usage to 16 cores (`--cpus=16`)\r\n   - Sets shared memory size to 50GB (`--shm-size=50g`)\r\n   - Runs the training with cross-validation\r\n\r\n   After training, check the contents of the models directory:\r\n\r\n   ```bash\r\n   ls -l ./models\r\n   ```\r\n\r\n3. **Other Docker Examples**\r\n\r\n   Download flag images:\r\n\r\n   ```bash\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data --memory=24g --cpus=16 --shm-size=50g flag_prediction_app download\r\n   ```\r\n\r\n   Process images:\r\n\r\n   ```bash\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data --memory=24g --cpus=16 --shm-size=50g flag_prediction_app process --duplicate-times 50\r\n   ```\r\n\r\n   Predict using a specific model:\r\n\r\n   ```bash\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data -v ${PWD}/models:/app/models -v /path/to/image/directory:/app/images --memory=24g --cpus=16 --shm-size=50g flag_prediction_app predict /app/images/flag.jpg --model resnet50\r\n   ```\r\n\r\n   Run full pipeline:\r\n\r\n   ```bash\r\n   docker run --gpus all -it --rm -v ${PWD}/data:/app/data -v ${PWD}/models:/app/models -v ${PWD}/logs:/app/logs --memory=24g --cpus=16 --shm-size=50g flag_prediction_app full-pipeline --duplicate-times 100 --cross-validate --models resnet50 --models efficientnet_b0 --models mobilenet_v2\r\n   ```\r\n\r\n## Conda Environment Setup\r\n\r\nFor detailed instructions on setting up a Conda environment for this project, please refer to the [Conda_Environment_Setup.md](Conda_Environment_Setup.md) file.\r\n\r\n## Configuration\r\n\r\nYou can modify settings such as image size, model parameters, and data augmentation options in `src/config.py`. Key configurations include:\r\n\r\n- `MODELS_TO_TRAIN`: List of models to train (e.g., `[\"resnet50\", \"mobilenet_v2\", \"efficientnet_b0\"]`)\r\n- `AUGMENTATION_FACTOR`: Number of augmented images to create per original image\r\n- `IMAGE_SIZE`: Input image size for the models\r\n- `INITIAL_LEARNING_RATE`: Learning rate for training\r\n- `BATCH_SIZE`: Batch size for training\r\n- `EPOCHS`: Number of training epochs\r\n- Various data augmentation parameters\r\n\r\n## Logs and File Access\r\n\r\nLogs are saved in the `logs/` directory. To access and view files via Docker:\r\n\r\n1. List files in a directory:\r\n\r\n   ```sh\r\n   docker run -it --rm -v ${PWD}/logs:/app/logs alpine ls -l /app/logs\r\n   ```\r\n\r\n2. View content of a specific file:\r\n\r\n   ```sh\r\n   docker run -it --rm -v ${PWD}/logs:/app/logs alpine cat /app/logs/flag_prediction.log\r\n   ```\r\n\r\n3. Start an interactive shell:\r\n\r\n   ```sh\r\n   docker run -it --rm -v ${PWD}/models:/app/models -v ${PWD}/logs:/app/logs -v ${PWD}/data:/app/data alpine sh\r\n   ```\r\n\r\n4. View images using Nginx:\r\n\r\n   ```sh\r\n   docker run -d --rm -p 8080:80 -v ${PWD}/data:/usr/share/nginx/html -v ${PWD}/nginx.conf:/etc/nginx/conf.d/default.conf --name data_server nginx\r\n   ```\r\n\r\n   Then open a web browser and go to `http://localhost:8080`.\r\n\r\nTo stop the Nginx server:\r\n\r\n```sh\r\ndocker stop data_server\r\n```\r\n\r\nYou can also view files in the `models/` and `logs/` directories using similar commands, replacing `data` with `models` or `logs` as needed.\r\n\r\n## Troubleshooting\r\n\r\n- **PyTorch Installation Issues**: Refer to the [official installation guide](https://pytorch.org/get-started/locally/) for your system.\r\n- **GPU Memory Issues**: Try reducing the batch size in `config.py` or use a GPU with more memory.\r\n- **Long Training Times**: Consider using a GPU or adjusting the `AUGMENTATION_FACTOR` if needed.\r\n- **Cross-validation Issues**: If cross-validation takes too long, consider reducing the `N_SPLITS` in `config.py`.\r\n- **CUDA Compatibility**: Ensure that your PyTorch installation matches your CUDA version for GPU acceleration.\r\n\r\n## Contributing\r\n\r\n## License\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxza85hrf%2Fflag_prediction_project","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxza85hrf%2Fflag_prediction_project","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxza85hrf%2Fflag_prediction_project/lists"}