Merge branch 'docs-1.2.0.2' into docs

# Conflicts:
#	docs/index.html
#	docs/requirements/index.html
#	docs/sitemap.xml.gz
#	source_docs/codeExamples.md
#	source_docs/contribution.md
#	source_docs/explanation.md
#	source_docs/how-to-guide.md
#	source_docs/index.md

.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Upload Teachable Machine Lite to PyPI when a Tag is Pushed
+
+on:
+  push:
+    tags:
+      - 'v*'  # Triggers on any tag that starts with 'v' (e.g., v1.2)
+
+jobs:
+  pypi-publish:
+    name: Publish release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/teachable-machine-lite
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install setuptools wheel
+      - name: Build package
+        run: |
+          python setup.py sdist bdist_wheel
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -191,5 +191,5 @@ src/screenshot.jpg
 /venv-tm-lite/*
 /src/frame.jpg
 /venv-tm-lite/lib64/
-/src/model/*
+/model/*
 /.idea/*

README.md

@@ -3,12 +3,12 @@ _By: [Meqdad Darwish](https://github.com/MeqdadDev)_
 
 <p align="center">
 <picture>
-  <img alt="Teachable Machine Lite Package Logo" src="logo.png" width="50%" height="50%" >
+  <img alt="Teachable Machine Lite Package Logo" src="https://meqdaddev.github.io/teachable-machine-lite/logo.png" width="80%" height="80%" >
 </picture>
 </p>
 
-[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
 [![Downloads](https://static.pepy.tech/badge/teachable-machine-lite)](https://pepy.tech/project/teachable-machine-lite)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
 [![PyPI](https://img.shields.io/pypi/v/teachable-machine-lite)](https://pypi.org/project/teachable-machine-lite/)
 
 ## Description
@@ -21,13 +21,19 @@ Read more about the project (requirements, installation, examples and more) in t
 
 ## Supported Classifiers
 
-**Image Classification**: Use exported and quantized TensorFlow Lite model from [Teachable Machine platfrom](https://teachablemachine.withgoogle.com/) (a model file with `tflite` extension).
+**Image Classification**: Use exported and quantized TensorFlow Lite model from [Teachable Machine Platform](https://teachablemachine.withgoogle.com/) (a model file with `tflite` extension).
 
 
 ## Requirements
 
+For detailed information about package requirements and dependencies, please visit our [documentation](https://meqdaddev.github.io/teachable-machine-lite/requirements/)
+
 ```
-Python >= 3.7
+Python >= 3.9
+```
+
+```
+numpy < 2.0 (v1.26.4 recommended)
 ```
 
 ## How to install Teachable Machine Lite Package
@@ -81,8 +87,6 @@ For more; take a look on [these examples](https://meqdaddev.github.io/teachable-
 
 ## Links:
 
-### Links:
-
 - [Documentation](https://meqdaddev.github.io/teachable-machine-lite)
 
 - [PyPI](https://pypi.org/project/teachable-machine-lite/)

docs/index.html

@@ -176,5 +176,5 @@ <h2 id="links">Links</h2>
 
 <!--
 MkDocs version : 1.6.1
-Build Date UTC : 2024-11-17 21:12:51.962100+00:00
+Build Date UTC : 2024-11-18 09:10:28.547949+00:00
 -->

docs/requirements/index.html

@@ -50,6 +50,10 @@
     <li class="toctree-l2"><a class="reference internal" href="#python-version">Python Version</a>
     </li>
     <li class="toctree-l2"><a class="reference internal" href="#dependencies">Dependencies</a>
+        <ul>
+    <li class="toctree-l3"><a class="reference internal" href="#important-compatibility-note">Important Compatibility Note:</a>
+    </li>
+        </ul>
     </li>
     </ul>
                 </li>
@@ -91,11 +95,21 @@
 
                 <h2 id="requirements">Requirements</h2>
 <h3 id="python-version">Python Version</h3>
-<p><code>Python &gt;= 3.7</code></p>
+<pre><code class="language-bash">Python &gt;= 3.9
+</code></pre>
 <h3 id="dependencies">Dependencies</h3>
 <pre><code class="language-bash">tflite_runtime
 Pillow
 numpy
+</code></pre>
+<h4 id="important-compatibility-note">Important Compatibility Note:</h4>
+<p>The Google Teachable Machine platform currently exports models that are not compatible with <code>numpy 2.x</code>. This package requires <code>numpy 1.x</code> (recommended <code>version 1.26.4</code>) to function correctly. Models exported from Teachable Machine may fail or produce unexpected results with <code>numpy 2.x</code>.</p>
+<p><strong>Numpy Installation recommendation:</strong></p>
+<pre><code class="language-bash">pip install numpy==1.26.4
+</code></pre>
+<p>This will ensure the compatibility with Teachable Machine models</p>
+<p>If you experience any model loading or inference issues, please verify your numpy version using:</p>
+<pre><code class="language-bash">python -m pip list | grep numpy
 </code></pre>
 
             </div>

mkdocs.yml

@@ -12,4 +12,7 @@ nav:
   - Requirements: requirements.md
   - Code Examples: codeExamples.md
   - Explanation: explanation.md
-  - Contributing: contribution.md
+  - Contributing: contribution.md
+
+docs_dir: source_docs
+site_dir: docs

setup.py

@@ -0,0 +1,38 @@
+from setuptools import setup
+
+with open("README.md", "r") as fh:
+    long_description = fh.read()
+
+setup(
+    name="teachable_machine_lite",
+    version="1.2.0.2",
+    description="A lightweight Python package optimized for integrating exported models from Google's Teachable Machine Platform into robotics and embedded systems environments. This streamlined version of Teachable Machine Package is specifically designed for resource-constrained devices, making it easier to deploy and use your trained models in embedded applications.",
+    py_modules=["teachable_machine_lite"],
+    package_dir={"": "src"},
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3.13",
+        "Topic :: Scientific/Engineering :: Image Processing",
+        "Topic :: Scientific/Engineering :: Image Recognition",
+        "Topic :: Scientific/Engineering :: Information Analysis",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    install_requires=[
+        "numpy==1.26.4",
+        "tflite-runtime",
+        "Pillow"
+    ],
+    python_requires=">=3.7",
+    url="https://github.com/MeqdadDev/teachable-machine-lite/",
+    author="Meqdad Dev",
+    author_email="[email protected]",
+)

source_docs/codeExamples.md

@@ -0,0 +1,93 @@
+## Code Examples
+
+Before running any of the code examples, ensure that the package is installed successfully.
+You can find the installation instructions [here](https://meqdaddev.github.io/teachable-machine-lite/how-to-guide/#how-to-install-the-package).
+
+You also need to have an exported model (and also **quantized**) (with `.tflite` file extension) with an associated labels text file for the package to use in annotations.
+
+**Note:** You can get an exported and quantized model from the TensorFlow Lite tab while exporting your model (in the Teachable Machine platform).
+
+Expected structure before running the code examples:
+
+```
+test-directory/
+├── model.tflite
+├── labels.txt
+└── app.py (your code example file)
+```
+
+### Example 1
+
+In this example for the teachable machine lite package with OpenCV, we will classify frames coming from the camera view and display 
+the classification results on the camera view itself. We use `classify_and_show` to achieve this. See the code example below:
+
+```python
+from teachable_machine_lite import TeachableMachineLite
+import cv2 as cv
+
+cap = cv.VideoCapture(0)
+
+model_path = 'model.tflite'
+labels_path = "labels.txt"
+image_file_name = "screenshot.jpg"
+
+tm_model = TeachableMachineLite(model_path=model_path, labels_file_path=labels_path)
+
+while True:
+    ret, img = cap.read()
+    cv.imwrite(image_file_name, img)
+
+    results, resultImage = tm_model.classify_and_show(image_file_name, convert_to_bgr=True)
+    print("results:", results)
+
+    cv.imshow("Camera", resultImage)
+    k = cv.waitKey(1)
+    if k == 27:  # Press ESC to close the camera view
+        break
+
+cap.release()
+cv.destroyAllWindows()
+```
+
+The values of `result` are assigned based on the content of the `labels.txt` file.
+
+### Example 2
+
+In this example for the teachable machine package with OpenCV, we will classify frames coming from the camera view and display 
+the classification results on the camera view itself, but with separated methods for each task.
+
+We use `classify_image` to classify the captured image but without showing the results on the camera view. Also, we use `show_prediction_on_image` to
+get a frame with previous classification results.
+
+Note that the `classify_image` method returns only the prediction results (a Python `dict`), not an image (numpy array or PIL.Image).
+
+See the code example below:
+
+```python
+from teachable_machine_lite import TeachableMachineLite
+import cv2 as cv
+
+cap = cv.VideoCapture(0)
+
+model_path = 'model.tflite'
+labels_path = "labels.txt"
+image_file_name = "screenshot.jpg"
+
+tm_model = TeachableMachineLite(model_path=model_path, labels_file_path=labels_path)
+
+while True:
+    ret, img = cap.read()
+    cv.imwrite(image_file_name, img)
+
+    results = tm_model.classify_image(image_file_name, False)
+    resultImage = tm_model.show_prediction_on_image(image_file_name, results)
+    print("results:", results)
+
+    cv.imshow("Camera", resultImage)
+    k = cv.waitKey(1)
+    if k == 27:  # Press ESC to close the camera view
+        break
+
+cap.release()
+cv.destroyAllWindows()
+```

source_docs/contribution.md

@@ -0,0 +1,16 @@
+## Contributing
+
+### Instructions
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+
+For new features, please make sure you've tested your code in real environment. 
+And to avoid duplications, please take a sneak peek on the project structure and practices before making your PR.
+
+For more details and questions, contact me via links below.
+
+### 🔗 Contact me
+[![Email Badge](https://img.shields.io/badge/Gmail-Contact_Me?style=for-the-badge&logo=gmail&logoColor=white)](mailto:[email protected])
+
+[![linkedin](https://img.shields.io/badge/linkedin-0A66C2?style=for-the-badge&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/meqdad-darwish/)
+
+[![twitter](https://img.shields.io/badge/twitter-1DA1F2?style=for-the-badge&logo=twitter&logoColor=white)](https://twitter.com/MeqdadDev)

source_docs/explanation.md

@@ -0,0 +1,5 @@
+## Explanation
+
+### Package Components
+
+::: src.teachable_machine_lite

source_docs/how-to-guide.md

@@ -0,0 +1,7 @@
+# How-To Guide
+
+## How to install the package
+
+```bash
+pip install teachable-machine-lite
+```

source_docs/index.md

@@ -0,0 +1,38 @@
+# Welcome to Teachable Machine Lite Package
+_By: [Meqdad Darwish](https://github.com/MeqdadDev)_
+
+<p align="center">
+<picture>
+  <img alt="Teachable Machine Lite Package Logo" src="logo.png" width="80%" height="80%" >
+</picture>
+</p>
+
+[![Downloads](https://static.pepy.tech/badge/teachable-machine-lite)](https://pepy.tech/project/teachable-machine-lite)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
+[![PyPI](https://img.shields.io/pypi/v/teachable-machine-lite)](https://pypi.org/project/teachable-machine-lite/)
+
+
+## Description
+A lightweight Python package optimized for integrating exported models from Google's [Teachable Machine Platform](https://teachablemachine.withgoogle.com/) into robotics and embedded systems environments. This streamlined version of [Teachable Machine Package](https://github.com/MeqdadDev/teachable-machine) is specifically designed for resource-constrained devices, making it easier to deploy and use your trained models in embedded applications. With a focus on efficiency and minimal dependencies, this tool maintains the core functionality while being more suitable for robotics and IoT projects.
+
+Source Code is published on [GitHub](https://github.com/MeqdadDev/teachable-machine-lite)
+
+## Table Of Contents
+
+1. [How-To Guide](how-to-guide.md)
+2. [Requirements](requirements.md)
+2. [Code Examples](codeExamples.md)
+3. [Explanation](explanation.md)
+4. [Contributing](contribution.md)
+
+## Supported Classifiers
+
+**Image Classification**
+
+## Links
+
+- [PyPI](https://pypi.org/project/teachable-machine-lite/)
+
+- [Source Code](https://github.com/MeqdadDev/teachable-machine-lite)
+
+- [Teachable Machine Platform](https://teachablemachine.withgoogle.com/)

source_docs/requirements.md

@@ -0,0 +1,29 @@
+## Requirements
+
+### Python Version
+
+```bash
+Python >= 3.9
+```
+
+### Dependencies
+
+```bash
+tflite_runtime
+Pillow
+numpy
+```
+
+#### Important Compatibility Note:
+The Google Teachable Machine platform currently exports models that are not compatible with `numpy 2.x`. This package requires `numpy 1.x` (recommended `version 1.26.4`) to function correctly. Models exported from Teachable Machine may fail or produce unexpected results with `numpy 2.x`.
+
+**Numpy Installation recommendation:**
+```bash
+pip install numpy==1.26.4
+```
+This will ensure the compatibility with Teachable Machine models
+
+If you experience any model loading or inference issues, please verify your numpy version using:
+```bash
+python -m pip list | grep numpy
+```