diff --git a/examples/README.md b/examples/README.md
deleted file mode 100644
index ae4a89c75..000000000
--- a/examples/README.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Examples
-
-This folder contains examples of [FEDn Projects](https://fedn.readthedocs.io/en/latest/projects.html).
diff --git a/examples/welding-defect-detection/README.md b/examples/welding-defect-detection/README.md
new file mode 100644
index 000000000..6248a8e5d
--- /dev/null
+++ b/examples/welding-defect-detection/README.md
@@ -0,0 +1,123 @@
+
+ **Note:**
+
+ **One of the dependencies in this example has an APGL license. This dependy is used in this particular example and not in FEDn in general.**
+
+ **If you are new to FEDn, we recommend that you start with the MNIST-Pytorch example instead: https://github.com/scaleoutsystems/fedn/tree/master/examples/mnist-pytorch**
+
+# Welding Defect Object Detection Example
+
+This is an example FEDn project that trains a YOLOv8n model on images of welds to classify them as "good", "bad", or "defected". The dataset is pre-labeled and can be accessed for free from Kaggle https://www.kaggle.com/datasets/sukmaadhiwijaya/welding-defect-object-detection. See a few examples below,
+
+
+
+
+
+
+
+
+This example is generalizable to many manufacturing and operations use cases, such as automatic optical inspection. The federated setup enables the organization to make use of available data in different factories and in different parts of the manufacturing process, without having to centralize the data.
+
+
+## How to run the example
+
+To run the example, follow the steps below. For a more detailed explanation, follow the Quickstart Tutorial: https://fedn.readthedocs.io/en/stable/quickstart.html
+
+**Note: To be able to run this example, you need to have GPU access.**
+
+
+### 1. Prerequisites
+
+- `Python >=3.8, <=3.12 `__
+- `A project in FEDn Studio `__
+- `A Kaggle account `__
+- GPU access
+
+
+### 2. Install FEDn and clone GitHub repo
+
+Install fedn:
+
+```
+pip install fedn
+```
+
+Clone this repository, then locate into this directory:
+
+```
+git clone https://github.com/scaleoutsystems/fedn.git
+cd fedn/examples/welding-defect-detection
+```
+
+
+### 3. Creating the compute package and seed model
+
+Create the compute package:
+
+```
+fedn package create --path client
+```
+
+This creates a file 'package.tgz' in the project folder.
+
+Next, generate the seed model:
+
+```
+fedn run build --path client
+```
+
+This will create a model file 'seed.npz' in the root of the project. This step will take a few minutes, depending on hardware and internet connection (builds a virtualenv).
+
+### 4. Running the project on FEDn
+
+To learn how to set up your FEDn Studio project and connect clients, take the quickstart tutorial: https://fedn.readthedocs.io/en/stable/quickstart.html. When activating the first client, you will be asked to provide your login credentials to Kaggle to download the welding defect dataset and split it into separate client folders.
+
+
+## Experiments with results
+
+Below are a few examples of experiments which have been run using this example. A centralized setup has been used as baseline to compare against. Two clients have been used in the federated setup and a few different epoch-to-round ratios have been tested.
+
+
+### Experimental setup
+
+Aggregator:
+- FedAvg
+
+Hyperparameters:
+- batch size: 16
+- learning rate: 0.01
+- imgsz: 640
+
+Approach: The number of epochs and rounds in each experiment are divided such that rounds * epochs = 250.
+
+#### Centralized setup
+
+| Experiment ID| # clients | epochs | rounds |
+| ----------- | ---------- | -------- | ------ |
+| 0 | 1 | 250 | 1 |
+
+#### Federated setup
+
+| Experiment ID| # clients | epochs | rounds |
+| ----------- | ---------- | -------- | ------ |
+| 1 | 2 | 5 | 50 |
+| 2 | 2 | 10 | 25 |
+| 3 | 2 | 25 | 10 |
+
+
+
+### Results
+
+Centralized:
+
+
+
+
+Federated:
+
+
+
+
+
+
+
diff --git a/examples/welding-defect-detection/client/custom.yaml b/examples/welding-defect-detection/client/custom.yaml
new file mode 100644
index 000000000..f37044c8e
--- /dev/null
+++ b/examples/welding-defect-detection/client/custom.yaml
@@ -0,0 +1,46 @@
+# Ultralytics YOLO 🚀, AGPL-3.0 license
+# YOLOv8 object detection model with P3-P5 outputs. For Usage examples see https://docs.ultralytics.com/tasks/detect
+
+# Parameters
+nc: 3 # number of classes
+scales: # model compound scaling constants, i.e. 'model=yolov8n.yaml' will call yolov8.yaml with scale 'n'
+ # [depth, width, max_channels]
+ n: [0.33, 0.25, 1024] # YOLOv8n summary: 225 layers, 3157200 parameters, 3157184 gradients, 8.9 GFLOPs
+ s: [0.33, 0.50, 1024] # YOLOv8s summary: 225 layers, 11166560 parameters, 11166544 gradients, 28.8 GFLOPs
+ m: [0.67, 0.75, 768] # YOLOv8m summary: 295 layers, 25902640 parameters, 25902624 gradients, 79.3 GFLOPs
+ l: [1.00, 1.00, 512] # YOLOv8l summary: 365 layers, 43691520 parameters, 43691504 gradients, 165.7 GFLOPs
+ x: [1.00, 1.25, 512] # YOLOv8x summary: 365 layers, 68229648 parameters, 68229632 gradients, 258.5 GFLOPs
+
+# YOLOv8.0n backbone
+backbone:
+ # [from, repeats, module, args]
+ - [-1, 1, Conv, [64, 3, 2]] # 0-P1/2
+ - [-1, 1, Conv, [128, 3, 2]] # 1-P2/4
+ - [-1, 3, C2f, [128, True]]
+ - [-1, 1, Conv, [256, 3, 2]] # 3-P3/8
+ - [-1, 6, C2f, [256, True]]
+ - [-1, 1, Conv, [512, 3, 2]] # 5-P4/16
+ - [-1, 6, C2f, [512, True]]
+ - [-1, 1, Conv, [1024, 3, 2]] # 7-P5/32
+ - [-1, 3, C2f, [1024, True]]
+ - [-1, 1, SPPF, [1024, 5]] # 9
+
+# YOLOv8.0n head
+head:
+ - [-1, 1, nn.Upsample, [None, 2, "nearest"]]
+ - [[-1, 6], 1, Concat, [1]] # cat backbone P4
+ - [-1, 3, C2f, [512]] # 12
+
+ - [-1, 1, nn.Upsample, [None, 2, "nearest"]]
+ - [[-1, 4], 1, Concat, [1]] # cat backbone P3
+ - [-1, 3, C2f, [256]] # 15 (P3/8-small)
+
+ - [-1, 1, Conv, [256, 3, 2]]
+ - [[-1, 12], 1, Concat, [1]] # cat head P4
+ - [-1, 3, C2f, [512]] # 18 (P4/16-medium)
+
+ - [-1, 1, Conv, [512, 3, 2]]
+ - [[-1, 9], 1, Concat, [1]] # cat head P5
+ - [-1, 3, C2f, [1024]] # 21 (P5/32-large)
+
+ - [[15, 18, 21], 1, Detect, [nc]] # Detect(P3, P4, P5)
diff --git a/examples/welding-defect-detection/client/data.py b/examples/welding-defect-detection/client/data.py
new file mode 100644
index 000000000..8564bd3af
--- /dev/null
+++ b/examples/welding-defect-detection/client/data.py
@@ -0,0 +1,131 @@
+import os
+from math import floor
+import opendatasets
+import shutil
+
+dir_path = os.path.dirname(os.path.realpath(__file__))
+abs_path = os.path.abspath(dir_path)
+
+
+def load_labels(label_dir):
+ label_files = os.listdir(label_dir)
+ data = []
+ for label_file in label_files:
+ with open(os.path.join(label_dir, label_file), "r") as file:
+ lines = file.readlines()
+ for line in lines:
+ class_id, x_center, y_center, width, height = map(float, line.strip().split())
+ data.append([class_id, x_center, y_center, width, height])
+ return data
+
+
+def load_data(data_path, step):
+ if data_path is None:
+ data_env = os.environ.get("FEDN_DATA_PATH")
+ if data_env is None:
+ data_path = f"{abs_path}/data/clients/1"
+ else:
+ data_path = f"{abs_path}{data_env}"
+ if step == "train":
+ y = os.listdir(f"{data_path}/train/labels")
+ length = len(y)
+ elif step == "test":
+ y = os.listdir(f"{data_path}/test/labels")
+ length = len(y)
+ else:
+ y = os.listdir(f"{data_path}/valid/labels")
+ length = len(y)
+
+ X = f"{data_path}/data.yaml"
+ return X, length
+
+
+def move_data_yaml(base_dir, new_path):
+ old_image_path = os.path.join(base_dir, "data.yaml")
+ new_image_path = os.path.join(new_path, "data.yaml")
+ shutil.copy(old_image_path, new_image_path)
+
+
+def splitset(dataset, parts):
+ n = len(dataset)
+ local_n = floor(n / parts)
+ result = []
+ for i in range(parts):
+ result.append(dataset[i * local_n : (i + 1) * local_n])
+ return result
+
+
+def build_client_folder(folder, data, idx, subdir):
+
+ os.makedirs(f"{subdir}/{folder}/images")
+ os.makedirs(f"{subdir}/{folder}/labels")
+ if folder=="train":
+ x = "x_train"
+ y = "y_train"
+ elif folder=="test":
+ x = "x_test"
+ y = "y_test"
+ else:
+ x = "x_val"
+ y = "y_val"
+
+ for image in data[x][idx]:
+ old_image_path = os.path.join(f"{abs_path}/welding-defect-object-detection/The Welding Defect Dataset/\
+The Welding Defect Dataset/{folder}/images", image)
+ new_image_path = os.path.join(f"{subdir}/{folder}/images", image)
+ shutil.move(old_image_path, new_image_path)
+ for label in data[y][idx]:
+ old_image_path = os.path.join(f"{abs_path}/welding-defect-object-detection/The Welding Defect Dataset/\
+The Welding Defect Dataset/{folder}/labels", label)
+ new_image_path = os.path.join(f"{subdir}/{folder}/labels", label)
+ shutil.move(old_image_path, new_image_path)
+
+def split(out_dir="data"):
+ n_splits = int(os.environ.get("FEDN_NUM_DATA_SPLITS", 1))
+
+ # Make dir
+ if not os.path.exists(f"{out_dir}/clients"):
+ os.makedirs(f"{out_dir}/clients")
+ opendatasets.download("https://www.kaggle.com/datasets/sukmaadhiwijaya/welding-defect-object-detection")
+ # Load data and convert to dict
+ X_train = [f for f in os.listdir(f"{abs_path}/welding-defect-object-detection/The Welding Defect Dataset/\
+The Welding Defect Dataset/train/images")]
+ X_test = [f for f in os.listdir(f"{abs_path}/welding-defect-object-detection/The Welding Defect Dataset/\
+The Welding Defect Dataset/test/images")]
+ X_val = [f for f in os.listdir(f"{abs_path}/welding-defect-object-detection/The Welding Defect Dataset/\
+The Welding Defect Dataset/valid/images")]
+
+ y_train = [f for f in os.listdir(f"{abs_path}/welding-defect-object-detection/The Welding Defect Dataset/\
+The Welding Defect Dataset/train/labels")]
+ y_test = [f for f in os.listdir(f"{abs_path}/welding-defect-object-detection/The Welding Defect Dataset/\
+The Welding Defect Dataset/test/labels")]
+ y_val = [f for f in os.listdir(f"{abs_path}/welding-defect-object-detection/The Welding Defect Dataset/\
+The Welding Defect Dataset/valid/labels")]
+
+ data = {
+ "x_train": splitset(X_train, n_splits),
+ "y_train": splitset(y_train, n_splits),
+ "x_test": splitset(X_test, n_splits),
+ "y_test": splitset(y_test, n_splits),
+ "x_val": splitset(X_val, n_splits),
+ "y_val": splitset(y_val, n_splits),
+ }
+
+ # Make splits
+ folders = ["train", "test", "valid"]
+ for i in range(n_splits):
+ subdir = f"{out_dir}/clients/{str(i+1)}"
+ if not os.path.exists(subdir):
+ for folder in folders:
+ build_client_folder(folder, data, i, subdir)
+ move_data_yaml(f"{abs_path}/welding-defect-object-detection/The Welding Defect Dataset/\
+The Welding Defect Dataset", subdir)
+ # Remove downloaded directory
+ if os.path.exists(f"{abs_path}/welding-defect-object-detection"):
+ shutil.rmtree(f"{abs_path}/welding-defect-object-detection")
+
+
+if __name__ == "__main__":
+ # Prepare data if not already done
+ if not os.path.exists(abs_path + "/data/clients/1"):
+ split()
diff --git a/examples/welding-defect-detection/client/fedn.yaml b/examples/welding-defect-detection/client/fedn.yaml
new file mode 100644
index 000000000..526b4a428
--- /dev/null
+++ b/examples/welding-defect-detection/client/fedn.yaml
@@ -0,0 +1,11 @@
+python_env: python_env.yaml
+entry_points:
+ build:
+ command: python model.py
+ startup:
+ command: python data.py
+ train:
+ command: python train.py
+ validate:
+ command: python validate.py
+
\ No newline at end of file
diff --git a/examples/welding-defect-detection/client/model.py b/examples/welding-defect-detection/client/model.py
new file mode 100644
index 000000000..d1e783e8a
--- /dev/null
+++ b/examples/welding-defect-detection/client/model.py
@@ -0,0 +1,65 @@
+import collections
+from ultralytics import YOLO
+import torch
+
+from fedn.utils.helpers.helpers import get_helper
+
+HELPER_MODULE = "numpyhelper"
+helper = get_helper(HELPER_MODULE)
+
+
+def compile_model():
+ """Compile the pytorch model.
+
+ :return: The compiled model.
+ :rtype: torch.nn.Module
+ """
+ model = YOLO("custom.yaml")
+ return model
+
+
+def save_parameters(model, out_path):
+ """Save model paramters to file.
+
+ :param model: The model to serialize.
+ :type model: torch.nn.Module
+ :param out_path: The path to save to.
+ :type out_path: str
+ """
+ parameters_np = [val.cpu().numpy() for _, val in model.state_dict().items()]
+ helper.save(parameters_np, out_path)
+
+
+def load_parameters(model_path):
+ """Load model parameters from file and populate model.
+
+ param model_path: The path to load from.
+ :type model_path: str
+ :return: The loaded model.
+ :rtype: torch.nn.Module
+ """
+ model = compile_model()
+ parameters_np = helper.load(model_path)
+
+ params_dict = zip(model.state_dict().keys(), parameters_np)
+ state_dict = collections.OrderedDict({key: torch.tensor(x) for key, x in params_dict})
+ model.load_state_dict(state_dict, strict=True)
+ torch.save(model,"tempfile.pt")
+ model = YOLO("tempfile.pt")
+ return model
+
+
+def init_seed(out_path="seed.npz"):
+ """Initialize seed model and save it to file.
+
+
+ :param out_path: The path to save the seed model to.
+ :type out_path: str
+ """
+ # Init and save
+ model = compile_model()
+ save_parameters(model, out_path)
+
+
+if __name__ == "__main__":
+ init_seed("../seed.npz")
diff --git a/examples/welding-defect-detection/client/python_env.yaml b/examples/welding-defect-detection/client/python_env.yaml
new file mode 100644
index 000000000..9ecdd44e5
--- /dev/null
+++ b/examples/welding-defect-detection/client/python_env.yaml
@@ -0,0 +1,15 @@
+name: welding-defect-detection
+build_dependencies:
+ - pip
+ - setuptools
+ - wheel
+dependencies:
+ - fedn
+ - torch==2.4.1; (sys_platform == "darwin" and platform_machine == "arm64") or (sys_platform == "win32" or sys_platform == "win64" or sys_platform == "linux")
+ # PyTorch macOS x86 builds deprecation
+ - torch==2.2.2; sys_platform == "darwin" and platform_machine == "x86_64"
+ - numpy==2.0.2; (sys_platform == "darwin" and platform_machine == "arm64" and python_version >= "3.9") or (sys_platform == "win32" or sys_platform == "win64" or sys_platform == "linux" and python_version >= "3.9")
+ - numpy==1.26.4; (sys_platform == "darwin" and platform_machine == "x86_64" and python_version >= "3.9")
+ - numpy==1.24.4; python_version == "3.8"
+ - ultralytics
+ - opendatasets
diff --git a/examples/welding-defect-detection/client/train.py b/examples/welding-defect-detection/client/train.py
new file mode 100644
index 000000000..8c29b9bd0
--- /dev/null
+++ b/examples/welding-defect-detection/client/train.py
@@ -0,0 +1,58 @@
+import sys
+from model import load_parameters, save_parameters
+from data import load_data
+from fedn.utils.helpers.helpers import save_metadata
+import os
+
+# Get the list of all files and directories
+
+dir_path = os.path.dirname(os.path.realpath(__file__))
+sys.path.append(os.path.abspath(dir_path))
+
+
+def train(in_model_path, out_model_path, data_path=None, batch_size=16, epochs=1, lr=0.01):
+ """Complete a model update.
+
+ Load model paramters from in_model_path (managed by the FEDn client),
+ perform a model update, and write updated paramters
+ to out_model_path (picked up by the FEDn client).
+
+ :param in_model_path: The path to the input model.
+ :type in_model_path: str
+ :param out_model_path: The path to save the output model to.
+ :type out_model_path: str
+ :param data_path: The path to the data file.
+ :type data_path: str
+ :param batch_size: The batch size to use.
+ :type batch_size: int
+ :param epochs: The number of epochs to train.
+ :type epochs: int
+ :param lr: The learning rate to use.
+ :type lr: float
+ """
+ # Load data
+ data, length = load_data(data_path, step="train")
+ # Load parmeters and initialize model
+ model = load_parameters(in_model_path)
+ # Train
+ model.train(data=data, epochs=epochs, imgsz=640, batch=batch_size, lr0=lr, warmup_epochs=0, optimizer="Adam")
+
+
+ # Metadata needed for aggregation server side
+ metadata = {
+ # num_examples are mandatory
+ "num_examples": length,
+ "batch_size": batch_size,
+ "epochs": epochs,
+ "lr": lr,
+ }
+
+ # Save JSON metadata file (mandatory)
+ save_metadata(metadata, out_model_path)
+
+ # Save model update (mandatory)
+ save_parameters(model, out_model_path)
+
+
+if __name__ == "__main__":
+ train(sys.argv[1], sys.argv[2])
diff --git a/examples/welding-defect-detection/client/validate.py b/examples/welding-defect-detection/client/validate.py
new file mode 100644
index 000000000..1825558aa
--- /dev/null
+++ b/examples/welding-defect-detection/client/validate.py
@@ -0,0 +1,39 @@
+import os
+import sys
+
+from model import load_parameters
+from data import load_data
+from fedn.utils.helpers.helpers import save_metrics
+
+dir_path = os.path.dirname(os.path.realpath(__file__))
+sys.path.append(os.path.abspath(dir_path))
+
+
+def validate(in_model_path, out_json_path, data_path=None):
+ """Validate model.
+
+ :param in_model_path: The path to the input model.
+ :type in_model_path: str
+ :param out_json_path: The path to save the output JSON to.
+ :type out_json_path: str
+ :param data_path: The path to the data file.
+ :type data_path: str
+ """
+ # Load data
+ test_data_yaml, test_data_length = load_data(data_path, step="test")
+ model = load_parameters(in_model_path)
+ validation_results = model.val(data=test_data_yaml)
+
+
+ # JSON schema
+ report = {
+ "map50-95": float(validation_results.box.map), # map50-95
+ "map50": float(validation_results.box.map50), # map50
+ "map75": float(validation_results.box.map75), # map75
+ }
+ # Save JSON
+ save_metrics(report, out_json_path)
+
+
+if __name__ == "__main__":
+ validate(sys.argv[1], sys.argv[2])
diff --git a/examples/welding-defect-detection/figs/2clients_10epochs_25rounds.png b/examples/welding-defect-detection/figs/2clients_10epochs_25rounds.png
new file mode 100644
index 000000000..677609deb
Binary files /dev/null and b/examples/welding-defect-detection/figs/2clients_10epochs_25rounds.png differ
diff --git a/examples/welding-defect-detection/figs/2clients_25epochs_10rounds.png b/examples/welding-defect-detection/figs/2clients_25epochs_10rounds.png
new file mode 100644
index 000000000..3ec4b27cc
Binary files /dev/null and b/examples/welding-defect-detection/figs/2clients_25epochs_10rounds.png differ
diff --git a/examples/welding-defect-detection/figs/2clients_5epochs_50rounds.png b/examples/welding-defect-detection/figs/2clients_5epochs_50rounds.png
new file mode 100644
index 000000000..2b69931ae
Binary files /dev/null and b/examples/welding-defect-detection/figs/2clients_5epochs_50rounds.png differ
diff --git a/examples/welding-defect-detection/figs/CentralizedmAP50.png b/examples/welding-defect-detection/figs/CentralizedmAP50.png
new file mode 100644
index 000000000..c96c4e494
Binary files /dev/null and b/examples/welding-defect-detection/figs/CentralizedmAP50.png differ
diff --git a/examples/welding-defect-detection/figs/fig1.jpg b/examples/welding-defect-detection/figs/fig1.jpg
new file mode 100644
index 000000000..b92b63f54
Binary files /dev/null and b/examples/welding-defect-detection/figs/fig1.jpg differ
diff --git a/examples/welding-defect-detection/figs/fig2.jpg b/examples/welding-defect-detection/figs/fig2.jpg
new file mode 100644
index 000000000..9237fade7
Binary files /dev/null and b/examples/welding-defect-detection/figs/fig2.jpg differ
diff --git a/examples/welding-defect-detection/figs/fig3.jpg b/examples/welding-defect-detection/figs/fig3.jpg
new file mode 100644
index 000000000..5d59e7d21
Binary files /dev/null and b/examples/welding-defect-detection/figs/fig3.jpg differ