{"id":31299204,"url":"https://github.com/mi-parkes/geo-coord-classifier","last_synced_at":"2026-04-29T22:38:21.554Z","repository":{"id":312535214,"uuid":"1043708921","full_name":"mi-parkes/geo-coord-classifier","owner":"mi-parkes","description":" End-to-End Deep Learning Model Deployment on macOSX and iOS","archived":false,"fork":false,"pushed_at":"2025-09-24T14:32:38.000Z","size":148,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-24T16:34:01.659Z","etag":null,"topics":["classifier-model","coreml","cpp","ios","machine-learning","macosx","onnx","onnxruntime","pytorch","swift","xcode"],"latest_commit_sha":null,"homepage":"","language":"Swift","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/mi-parkes.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}},"created_at":"2025-08-24T13:03:42.000Z","updated_at":"2025-09-24T14:32:42.000Z","dependencies_parsed_at":"2025-08-31T11:38:24.558Z","dependency_job_id":"7012b511-9613-427e-9785-d890d4026e9b","html_url":"https://github.com/mi-parkes/geo-coord-classifier","commit_stats":null,"previous_names":["mi-parkes/geo-coord-classifier-osx"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/mi-parkes/geo-coord-classifier","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mi-parkes%2Fgeo-coord-classifier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mi-parkes%2Fgeo-coord-classifier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mi-parkes%2Fgeo-coord-classifier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mi-parkes%2Fgeo-coord-classifier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mi-parkes","download_url":"https://codeload.github.com/mi-parkes/geo-coord-classifier/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mi-parkes%2Fgeo-coord-classifier/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276837251,"owners_count":25713351,"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-09-24T02:00:09.776Z","response_time":97,"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":["classifier-model","coreml","cpp","ios","machine-learning","macosx","onnx","onnxruntime","pytorch","swift","xcode"],"created_at":"2025-09-25T00:06:58.720Z","updated_at":"2026-04-29T22:38:21.540Z","avatar_url":"https://github.com/mi-parkes.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Geo Coordinate Classifier\n\nThis project is a **[Swift](https://www.swift.org/documentation/)-based** application that demonstrates a **complete, end-to-end Machine Learning Operations (MLOps) pipeline** for deploying neural networks to Apple platforms. It showcases running both an [**ONNX**](https://onnx.ai/onnx/intro/) model (using a C++ backend) and a [**Core ML**](https://developer.apple.com/documentation/coreml) model in a native Swift environment.\n\nThe classifier's actual function—determining a region from coordinates—is a **minimal, illustrative task** used to rigorously test the complex deployment workflow, not to solve a challenging geographic problem.\n\n![](data/classify-city-gc8.svg)\n\n-----\n\n### Model Details\n\nThe core purpose of this project lies in the deployment process, not the complexity of the model itself.\n\n* **Illustrative Simplicity**: The model is a **simple neural network** trained on limited data, capable of classifying the geo-coordinates of only a few specific European capitals. This controlled, trivial scenario provides a clear test case for the deployment pipeline.\n* **Model Origin**: The model was initially created with [**PyTorch**](https://docs.pytorch.org/docs/stable/index.html), **quantized** to 8-bits for efficiency, and then converted to the platform-agnostic **ONNX** (Open Neural Network Exchange) format. The project also includes a native **Core ML** version.\n* **Self-Contained**: Both models now have the necessary normalization data included directly within them. This process allows the models to be deployed and run on a variety of platforms and frameworks, including [**ONNX Runtime**](https://onnxruntime.ai/docs/) and **Core ML**.\n\n\u003cp align=\"center\"\u003e\n\u003cb\u003eGeoCoordClassifier Decision Boundaries (Training Visualization)\u003c/b\u003e\n\u003cimg src=\"data/classify-city-gc.svg\" alt=\"something went wrong\" style=\"width: 90%; max-width: 800px;\"\u003e\n\u003c/p\u003e\n\n-----\n\n### Features\n\n* **Offline inference:** Runs the ONNX and Core ML models without needing a network connection.\n* **High performance:** Utilizes the ONNX Runtime C++ API and native Core ML frameworks for efficient model execution.\n* **Portable deployment:** Validates the model's functionality in a native environment, a crucial step for target deployment scenarios.\n* **Decoupled Architecture:** Introduces **`ClassifierProtocol`** to separate the application logic from the specific classifier implementation (ONNX or Core ML). This allows for a flexible and extensible design.\n* **Automated Evaluation:** The application now evaluates both the ONNX and Core ML models on the same data, running them one after another for direct comparison.\n* **Platform Support:** Supports building as a Swift-based App for **macOS**, **iOS**, and **iOS Simulator**, and as a command-line interface (CLI) for **macOS**.\n\n-----\n\n### Project Technical Roadmap\n\nThis project covers a wide array of specialized topics, demonstrating a complete journey through modern **MLOps, Cross-Platform Deployment, and Native Application Engineering.** The mindmap below visualizes the key technical areas and skills mastered, from PyTorch model optimization to terminal-driven CI/CD processes.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"data/GeoClassifier_MLOps_Topics.svg\" alt=\"Mindmap showing the end-to-end topics and technologies covered in the Geo Coordinate Classifier project, including MLOps, Core ML, ONNX, Swift/C++ Interoperability, and CI/CD.\" style=\"width: 100%; max-width: 900px;\"\u003e\n\u003c/p\u003e\n\n-----\n\n### Dependencies\n\n* **ONNX Runtime:** The core library required for loading and running the ONNX model.\n    * This project requires the **`onnxruntime.xcframework`** directory to be manually created and populated with header files and shared libraries (e.g., `libonnxruntime.1.23.0.dylib`) for **all platforms subject to build** (macOS, iOS, and iOS Simulator), as detailed in the [Building the Project](#building-the-project) section.\n* **Model Files:**\n    * `GeoClassifier.onnx`: The ONNX format of the quantized model.\n    * `GeoClassifier.mlpackage`: The Core ML format of the model.\n* **Evaluation Data:**\n    * `GeoClassifierEvaluationData.json`: The data file used by the application to run automated, sequential evaluation on both the ONNX and Core ML backends.\n\n-----\n\n### Building the Project\n\n\u003cp align=\"center\"\u003e\nXcode Project Build Dependency Graph\n\u003cbr\u003e\u003cbr\u003e\n\u003cimg src=\"data/dg.svg\" alt=\"something went wrong\" style=\"max-width:600px\"\u003e\n\u003c/p\u003e\n\nThis project supports building a Swift-based App or CLI from the command line using `xcodebuild`. The project expects the **`onnxruntime.xcframework`** directory to be located in the root directory of this project and contain the following structure:\n\n```txt\n/geo-coord-classifier\n├── ...\n├── geo-coord-classifier\n├── geo-coord-classifier-cli\n├── geo-coord-classifier.xcodeproj\n├── ...\n├── onnxruntime.xcframework\n│   ├── Info.plist\n│   ├── ios-arm64\n│   │   ├── Headers\n│   │   │   └── onnxruntime\n│   │   └── libonnxruntime.1.23.0.dylib\n│   ├── ios-arm64-simulator\n│   │   ├── Headers\n│   │   │   └── onnxruntime\n│   │   └── libonnxruntime.1.23.0.dylib\n│   └── macos-arm64\n│       ├── Headers\n│       │   └── onnxruntime\n│       └── libonnxruntime.1.23.0.dylib\n└── ...\n```\n#### Building from Command Line 🛠️\n\n```bash\n# Build App for macOS\nmake build-macosx\n\n# Build CLI for macOS\nmake build-cli-macosx\n\n# Build App for iOS Simulator\nmake build-ios-iphonesimulator\n\n# Build App for iOS Device\nmake build-iphoneos\n```\n\n-----\n\n### Running the Project\n\n#### Run App (macOS) 🚀\n\n```bash\nmake run-macosx\n```\n\n#### Run CLI (macOS) 🏃\n\n```bash\nmake run-cli-macosx\n```\n\n#### Run App (ios-simulator)\n\n```bash\nmake start-simulator\nmake run-app-in-ios-simulator\n```\n\n-----\n\n\u003cp align=\"center\"\u003e\niOS Simulator Screenshot\n\u003cbr\u003e\u003cbr\u003e\n\u003cimg src=\"data/SimulatorScreenshotiPhoneAir.png\" \n    alt=\"something went wrong\" width=\"320\" style=\"max-width:320px\"\u003e\n\u003c/p\u003e\n\n-----\n\n### Testing the Project (Continuous Integration)\n\nThese commands are designed for running validation steps locally and are suitable for use in **Continuous Integration (CI/CD)** pipelines (e.g., GitHub Actions, Jenkins).\n\n#### Unit Test Execution (macOS)\n\nRuns the core unit tests for the `GeoCoordClassifierCore` target, validating the C++ bridge, model loading, and `ClassifierProtocol` implementations in Swift.\n\n```bash\nmake test-geoCoordClassifierCore\n```\n\n#### Integration Test (macOS CLI)\n\nPerforms a full end-to-end validation. It runs the CLI against the `GeoClassifierEvaluationData.json` file to confirm that both the ONNX and Core ML backends execute correctly and return consistent classification results.\n\n```bash\nmake sandbox-test\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmi-parkes%2Fgeo-coord-classifier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmi-parkes%2Fgeo-coord-classifier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmi-parkes%2Fgeo-coord-classifier/lists"}