Merge pull request #3 from AMLResearchProject/release-1-0-0

Release 1 0 0

.github/workflows/codeql-analysis.yml

@@ -32,7 +32,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        language: [  ]
+        language: [ 'python' ]
         # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ]
         # Learn more:
         # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021 Peter Moss Acute Myeloid & Lymphoblastic Leukemia AI Research Project
+Copyright (c) 2021 Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,2 +1,153 @@
-# ALL-Jetson-Nano-Classifier
-An Acute Lymphoblastic Leukemia classifier developed for the NVIDIA Jetson Nano. Jetson AI Certification project by Adam Milton-Barker.
+# Peter Moss Acute Myeloid & Lymphoblastic Leukemia AI Research Project
+## Acute Lymphoblastic Leukemia Jetson Nano Classifier
+
+![Acute Lymphoblastic Leukemia Jetson Nano Classifier](assets/images/project-banner.jpg)
+
+[![CURRENT RELEASE](https://img.shields.io/badge/CURRENT%20RELEASE-1.0.0-blue.svg)](https://github.com/AMLResearchProject/ALL-Jetson-Nano-Classifier/tree/1.0.0) [![DEV BRANCH](https://img.shields.io/badge/DEV%20BRANCH-develop-blue.svg)](https://github.com/AMLResearchProject/ALL-Jetson-Nano-Classifier/tree/develop) [![Contributions Welcome!](https://img.shields.io/badge/Contributions-Welcome-lightgrey.svg)](CONTRIBUTING.md)  [![Issues](https://img.shields.io/badge/Issues-Welcome-lightgrey.svg)](issues)
+
+[![PEP8](https://img.shields.io/badge/code%20style-pep8-orange.svg)](https://www.python.org/dev/peps/pep-0008/) [![Documentation Status](https://readthedocs.org/projects/all-jetson-nano-classifier/badge/?version=latest)](https://all-jetson-nano-classifier.readthedocs.io/en/latest/?badge=latest) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/5068/badge)](https://bestpractices.coreinfrastructure.org/projects/5068) [![DOI](https://zenodo.org/badge/383255630.svg)](https://zenodo.org/badge/latestdoi/383255630)
+
+
+ [![LICENSE](https://img.shields.io/badge/LICENSE-MIT-blue.svg)](LICENSE)
+
+ 
+
+# Table Of Contents
+
+- [Introduction](#introduction)
+- [NVIDIA Jetson Nano](#nvidia-jetson-nano)
+- [TFRT](#tfrt)
+- [ONNX](#onnx)
+- [TensorRT](#tensorrt)
+- [Motivation](#motivation)
+- [DISCLAIMER](#disclaimer)
+- [Acute Lymphoblastic Leukemia](#acute-lymphoblastic-leukemia)
+- [ALL IDB](#all-idb)
+- [Getting Started](#getting-started)
+- [Quick Start](#quick-start)
+- [Contributing](#contributing)
+  - [Contributors](#contributors)
+- [Versioning](#versioning)
+- [License](#license)
+- [Bugs/Issues](#bugs-issues)
+
+ 
+
+# Introduction
+
+The **Acute Lymphoblastic Leukemia Jetson Nano Classifier** is a Convolutional Neural Network (CNN) developed using [Intel® oneAPI AI Analytics Toolkit](https://software.intel.com/content/www/us/en/develop/tools/oneapi.html) and [Intel® Optimization for Tensorflow*](https://software.intel.com/content/www/us/en/develop/articles/getting-started-with-intel-optimization-of-pytorch.html) to accelerate the training process, and [TensorRT](https://developer.nvidia.com/tensorrt) for high performance inference on the [NVIDIA® Jetson Nano™](https://developer.nvidia.com/embedded/jetson-nano-developer-kit).
+
+In this project you will do the following.
+
+- Train a custom CNN for Acute Lymphoblastic Leukemia on your development machine.
+- Convert the Tensorflow SavedModel to TFRT format
+- Convert the Tensorflow SavedModel to ONNX format
+- Convert the Tensorflow ONNX model to TensorRT format
+- Test the CNN on your development machine.
+- Download or create a custom docker container for your NVIDIA Jetson Nano.
+- Run the CNN on your NVIDIA Jetson Nano using Tensorflow.
+- Run the CNN on your NVIDIA Jetson Nano using TFRT.
+- Run the CNN on your NVIDIA Jetson Nano using TensorRT.
+
+ 
+
+# NVIDIA Jetson Nano
+
+![NVIDIA Jetson Nano Devkit](assets/images/nvidia-jetson-nano-devkit.jpg)
+
+The NVIDIA® Jetson Nano™ is a small, powerful computer that is capable of running multiple neural networks in parallel for applications like image classification, object detection, segmentation, and speech processing.
+
+ 
+
+# TFRT
+
+"TFRT is a new TensorFlow runtime. It aims to provide a unified, extensible infrastructure layer with best-in-class performance across a wide variety of domain specific hardware. It provides efficient use of multithreaded host CPUs, supports fully asynchronous programming models, and focuses on low-level efficiency."
+
+[Source](https://github.com/tensorflow/runtime)
+
+ 
+
+# ONNX
+
+"ONNX is an open format built to represent machine learning models. ONNX defines a common set of operators - the building blocks of machine learning and deep learning models - and a common file format to enable AI developers to use models with a variety of frameworks, tools, runtimes, and compilers."
+
+[Source](https://onnx.ai/)
+
+ 
+
+TensorRT
+
+"NVIDIA® TensorRT™ is an SDK for high-performance deep learning inference. It includes a deep learning inference optimizer and runtime that delivers low latency and high throughput for deep learning inference applications."
+
+[Source](https://developer.nvidia.com/tensorrt)
+
+ 
+
+# Motivation
+
+The motivation behind this project was to test the capabilities of the NVIDIA® Jetson Nano™ for the classification of Acute Lymphoblastic Leukemia on the edge. This project is also a submission for the [NVIDIA Jetson AI Specialist Certification](https://developer.nvidia.com/embedded/learn/jetson-ai-certification-programs).
+
+ 
+
+# DISCLAIMER
+
+_This project should be used for research purposes only. The purpose of the project is to show the potential of Artificial Intelligence for medical support systems such as diagnostic systems._
+
+_Although the model is accurate and shows good results both on paper and in real world testing, it is trained on a small amount of data and needs to be trained on larger datasets to really evaluate it's accuracy._
+
+_Developers that have contributed to this repository have experience in using Artificial Intelligence for detecting certain types of cancer. They are not doctors, medical or cancer experts._
+
+ 
+
+# Acute Lymphoblastic Leukemia
+[Acute lymphoblastic leukemia (ALL)](https://www.leukemiaairesearch.com/research/leukemia), also known as Acute Lymphocytic Leukemia, is a cancer that affects the lymphoid blood cell lineage. It is the most common leukemia in children, and it accounts for 10-20% of acute leukemias in adults. The prognosis for both adult and especially childhood ALL has improved substantially since the 1970s. The 5- year survival is approximately 95% in children. In adults, the 5-year survival varies between 25% and 75%, with more favorable results in younger than in older patients.
+
+For more information about Acute Lymphoblastic Leukemia  please visit our [Leukemia Information Page](https://www.leukemiaairesearch.com/research/leukemia)
+
+ 
+
+# ALL-IDB
+
+![Acute Lymphoblastic Leukemia Jetson Nano Classifier](assets/images/all-idb.jpg)
+
+You need to be granted access to use the Acute Lymphoblastic Leukemia Image Database for Image Processing dataset. You can find the application form and information about getting access to the dataset on [this page](https://homes.di.unimi.it/scotti/all/#download) as well as information on how to contribute back to the project [here](https://homes.di.unimi.it/scotti/all/results.php). If you are not able to obtain a copy of the dataset please feel free to try this tutorial on your own dataset, we would be very happy to find additional AML & ALL datasets.
+
+ 
+
+# Getting Started
+
+To get started follow the project [documentation](docs/index.md).
+
+ 
+
+# Quick Start
+
+- [Ubuntu Installation Guide](docs/installation/ubuntu.md)
+- [Notebook Usage Guide](docs/usage/notebooks.md)
+- [NVIDIA Jetson Nano Installation Guide](docs/installation/jetson.md)
+- [NVIDIA Jetson Nano Usage Guide](docs/usage/jetson.md)
+
+ 
+
+# Contributing
+Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss encourages and welcomes code contributions, bug fixes and enhancements from the Github community.
+
+Please read the [CONTRIBUTING](https://github.com/AMLResearchProject/Contributing-Guide/blob/main/CONTRIBUTING.md "CONTRIBUTING") document for a full guide to forking our repositories and submitting your pull requests. You will also find our code of conduct in the [Code of Conduct](https://github.com/AMLResearchProject/Contributing-Guide/blob/main/CODE-OF-CONDUCT.md) document.
+
+## Contributors
+- [Adam Milton-Barker](https://www.leukemiaairesearch.com/association/volunteers/adam-milton-barker "Adam Milton-Barker") - [Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss](https://www.leukemiaresearchassociation.ai "Asociación de Investigacion en Inteligencia Artificial Para la Leucemia Peter Moss") President/Founder & Lead Developer, Sabadell, Spain
+
+ 
+
+# Versioning
+We use [SemVer](https://semver.org/) for versioning.
+
+ 
+
+# License
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE "LICENSE") file for details.
+
+ 
+
+# Bugs/Issues
+We use the [repo issues](issues "repo issues") to track bugs and general requests related to using this project. See [CONTRIBUTING](CONTRIBUTING.md "CONTRIBUTING") for more info on how to submit bugs, feature requests and proposals.

classifier.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+""" ALL Jetson Nano Classifier
+
+An Acute Lymphoblastic Leukemia classifier developed for the NVIDIA Jetson Nano.
+Jetson AI Certification project by Adam Milton-Barker.
+
+MIT License
+
+Copyright (c) 2021 Asociación de Investigacion en Inteligencia Artificial
+Para la Leucemia Peter Moss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files(the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Contributors:
+- Adam Milton-Barker
+
+"""
+
+import sys
+
+from abc import ABC, abstractmethod
+
+from modules.AbstractClassifier import AbstractClassifier
+
+from modules.helpers import helpers
+from modules.model import model
+from modules.server import server
+
+
+class classifier(AbstractClassifier):
+	""" ALL Jetson Nano Classifier
+
+	Represents a AI classifier that processes data
+	using the ALL Jetson Nano Classifier model.
+	"""
+
+	def train(self):
+		""" Creates & trains the model. """
+
+		self.model.prepare_data()
+		self.model.prepare_network()
+		self.model.train()
+		self.model.evaluate()
+
+	def init_model(self):
+		""" Initializes the model class """
+
+		self.model = model(self.helpers)
+
+	def load_model(self):
+		""" Loads the trained model """
+
+		self.model.load()
+
+	def load_model_tfrt(self):
+		""" Loads the trained TFRT model """
+
+		self.model.load_tfrt()
+
+	def inference(self):
+		""" Classifies test data locally """
+
+		self.load_model()
+		self.model.test()
+
+	def server(self):
+		""" Starts the API server """
+
+		self.load_model()
+		self.server = server(self.helpers, self.model,
+							 self.model_type)
+		self.server.start()
+
+	def inference_http(self):
+		""" Classifies test data via HTTP requests """
+
+		self.model.test_http()
+
+	def inference_tfrt(self):
+		""" Classifies test data via HTTP requests """
+
+		self.load_model_tfrt()
+		self.model.test_tfrt()
+
+	def init_engine(self):
+		""" Initizializes the engine class """
+
+		from modules.engine import engine
+
+		self.engine = engine(self.helpers)
+
+	def inference_tensorrt(self):
+		""" Classifies test data via HTTP requests """
+
+		self.engine.load_engine()
+		self.engine.test()
+
+	def signal_handler(self, signal, frame):
+		self.helpers.logger.info("Disconnecting")
+		sys.exit(1)
+
+
+classifier = classifier()
+
+
+def main():
+
+	if len(sys.argv) < 2:
+		print("You must provide an argument")
+		exit()
+	elif sys.argv[1] not in classifier.helpers.confs["agent"]["params"]:
+		print("Mode not supported! server, train or inference")
+		exit()
+
+	mode = sys.argv[1]
+
+	if mode == "train":
+		classifier.init_model()
+		classifier.train()
+
+	elif mode == "classify":
+		classifier.init_model()
+		classifier.inference()
+
+	elif mode == "server":
+		classifier.init_model()
+		classifier.server()
+
+	elif mode == "classify_http":
+		classifier.init_model()
+		classifier.inference_http()
+
+	elif mode == "classify_tfrt":
+		classifier.init_model()
+		classifier.inference_tfrt()
+
+	elif mode == "classify_tensorrt":
+		classifier.init_engine()
+		classifier.inference_tensorrt()
+
+
+if __name__ == "__main__":
+	main()

configuration/config.json

@@ -0,0 +1,64 @@
+{
+    "agent": {
+        "cores": 8,
+        "port": 1234,
+        "params": [
+            "train",
+            "classify",
+            "server",
+            "classify_http",
+            "classify_tfrt",
+            "classify_tensorrt"
+        ]
+    },
+    "data": {
+        "dim": 100,
+        "file_type": ".jpg",
+        "labels": [0, 1],
+        "rotations": 10,
+        "seed": 2,
+        "split": 0.255,
+        "test": "model/data/test",
+        "test_data": [
+            "Im006_1.jpg",
+            "Im020_1.jpg",
+            "Im024_1.jpg",
+            "Im026_1.jpg",
+            "Im028_1.jpg",
+            "Im031_1.jpg",
+            "Im035_0.jpg",
+            "Im041_0.jpg",
+            "Im047_0.jpg",
+            "Im053_1.jpg",
+            "Im057_1.jpg",
+            "Im060_1.jpg",
+            "Im063_1.jpg",
+            "Im069_0.jpg",
+            "Im074_0.jpg",
+            "Im088_0.jpg",
+            "Im095_0.jpg",
+            "Im099_0.jpg",
+            "Im101_0.jpg",
+            "Im106_0.jpg"
+        ],
+        "train_dir": "model/data/train",
+        "valid_types": [
+            ".jpg"
+        ]
+    },
+    "model": {
+        "model": "model/all_jetson_nano.json",
+        "weights": "model/all_jetson_nano.h5",
+        "saved": "model/saved",
+        "tfrt": "model/tfrt",
+        "onnx": "model/all_jetson_nano.onnx",
+        "tensorrt": "model/all_jetson_nano.plan"
+    },
+    "train": {
+        "batch": 100,
+        "decay_adam": 1e-6,
+        "epochs": 150,
+        "learning_rate_adam": 1e-4,
+        "val_steps": 10
+    }
+}