examples: Improve xor_trees and mnist_cnn

Author: jonnor

examples/mnist_cnn/README.md

@@ -0,0 +1,68 @@
+
+# Image classification using Convolutional Neural Network
+
+
+## Install requirements
+
+Make sure to have Python **3.10** installed.
+At the time TinyMaix, used for CNN, only supports Tensorflow <2.14,
+which is not supported on Python 3.12 or later.
+
+Make sure to have the Unix port of MicroPython 1.23 setup.
+On Windows you can use Windows Subsystem for Linux (WSL), or Docker.
+
+Install the dependencies of this example:
+```console
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Run training
+
+This will train a Convolutional Neural Network using Keras.
+The process will output `.tmdl` that is our built model.
+
+```console
+python mnist_train.py
+```
+
+## Running on host
+
+```console
+curl -o tinymaix_cnn.mpy https://github.com/emlearn/emlearn-micropython/raw/refs/heads/gh-pages/builds/master/x64_6.3/tinymaix_cnn.mpy
+
+micropython mnist_cnn_run.py
+```
+
+## Running on device
+
+!Make sure you have it running successfully on host first.
+
+Flash your device with a standard MicroPython firmware,
+from the MicroPython.org downloads page.
+
+```console
+curl -o device/tinymaix_cnn.mpy https://github.com/emlearn/emlearn-micropython/raw/refs/heads/gh-pages/builds/master/xtensawin_6.3/tinymaix_cnn.mpy
+```
+
+```console
+mpremote cp device/tinymaix_cnn.mpy :
+mpremote cp mnist_cnn.tmdl :
+mpremote cp -r data/ :
+mpremote run mnist_cnn_run.py
+```
+
+## Running with live camera input
+
+This example requires hardware with an ESP32 chip, and an OV2640 camera module.
+It has been tested on Lilygo T-Camera Mic v1.6. 
+
+You need to build a custom ESP32 firmware,
+and add this C module for camera access:
+https://github.com/cnadler86/micropython-camera-API
+
+```
+mpremote run mnist_cnn_camera.py
+```
+

examples/mnist_cnn/mnist_train.py

@@ -54,12 +54,15 @@ def train_mnist(h5_file, epochs=10):
     model.summary()
 
     model.compile(optimizer='adam', loss = "categorical_crossentropy", metrics = ["categorical_accuracy"]) 
-    H = model.fit(x_train, y_train, batch_size=128, epochs=EPOCHS, verbose=1, validation_data = (x_test, y_test), shuffle=True)
+    H = model.fit(x_train, y_train, batch_size=128, epochs=epochs, verbose=1, validation_data = (x_test, y_test), shuffle=True)
 
     model.save(h5_file)
 
 def generate_test_files(out_dir, x, y):
 
+    if not os.path.exists(out_dir):
+        os.makedirs(out_dir)
+
     expect_bytes = 28*28*1
     classes = numpy.unique(y)
     X_series = pandas.Series([s for s in x])
@@ -146,29 +149,34 @@ def format_shape(t : tuple[int]):
     assert os.path.exists(tmld_file), tmld_file
     assert os.path.exists(header_file), header_file
 
+    return tmld_file
 
 def main():
 
     h5_file = "mnist_cnn.h5"
-    tinymaix_tools_dir = './TinyMaix/tools'
+    tinymaix_tools_dir = '../../dependencies/TinyMaix/tools'
+    assert os.path.exists(tinymaix_tools_dir), tinymaix_tools_dir
+
+    quantize_data = None # disables quantization
+    quantize_data = os.path.join(tinymaix_tools_dir, 'quant_img_mnist/')
+    if quantize_data is not None:
+        assert os.path.exists(quantize_data)
+    precision = 'int8' if quantize_data else 'fp32'
 
+    # Run training
     train_mnist(h5_file)
 
     #data = x_test[1]
 
-    quantize_data = True # disables quantization
-    quantize_data = './TinyMaix/tools/quant_img_mnist/'
-    precision = 'int8' if quantize_data else 'fp32'
-
     # Export the model using TinyMaix
-
-    generate_tinymaix_model(h5_file,
+    out = generate_tinymaix_model(h5_file,
         input_shape=(28,28,1),
         output_shape=(1,),
         tools_dir=tinymaix_tools_dir,
         precision=precision,
         quantize_data=quantize_data,
     )
+    print('Wrote model to', out)
 
 if __name__ == '__main__':
     main()

examples/mnist_cnn/requirements.txt

@@ -0,0 +1,4 @@
+tensorflow-cpu<2.14.1
+numpy<2.0.0
+pandas>=2.0.0
+pillow>=10.0.0

examples/xor_trees/README.md

@@ -0,0 +1,53 @@
+
+# XOR using Random Forest
+
+The XOR problem stems from the famous Perceptrons (1969) book
+by Marvin Minsky and Seymour Papert.
+It can be trivially solved by a decision-tree or decision-tree ensemble.
+Thus it is a kind of "Hello World" example.
+Simple and an OK sanity check, but particularly useful.
+
+## Install requirements
+
+Make sure to have Python 3.10+ installed.
+
+Make sure to have the Unix port of MicroPython 1.23 setup.
+On Windows you can use Windows Subsystem for Linux (WSL), or Docker.
+
+```console
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Run training
+
+This will train a RandomForest model using scikit-learn, and output `xor_model.csv`
+
+```console
+python xor_train.py
+```
+
+## Running on host
+
+```console
+curl -o emltrees.mpy https://github.com/emlearn/emlearn-micropython/raw/refs/heads/gh-pages/builds/master/x64_6.3/emltrees.mpy
+micropython xor_run.py
+```
+
+## Running on device
+
+!Make sure you have it running successfully on host first.
+
+This command is for ESP32 (xtensawin).
+For other hardware, replace the string.
+
+```console
+mkdir -p device
+curl -o device/emltrees.mpy https://github.com/emlearn/emlearn-micropython/raw/refs/heads/gh-pages/builds/master/xtensawin_6.3/emltrees.mpy
+mpremote cp emltrees.mpy :
+```
+
+```
+mpremote run xor_run.py
+```

examples/xor_trees/requirements.txt

@@ -0,0 +1,3 @@
+emlearn>=0.21.0
+scikit-learn>=1.5.0
+setuptools>=75.0.0