🦀 Kataglyphis-RustProjectTemplate 🦀

Collecting Rust best practices. Part of the Kataglyphis Ecosystem for robust code sharing and rapid development.

For official docs follow this link.

Table of Contents

• About The Project
  • Key Features
  • Dependencies
  • Useful tools
• Getting Started
  • Prerequisites
  • Installation
• Tests
• Run
• Docs
• Updates
• Roadmap
• Contributing
• License
• Contact
• Acknowledgements
• Literature

About The Project

This template is a foundational part of the Kataglyphis Ecosystem, providing robust Rust best practices. It works synergistically with other projects like Kataglyphis ContainerHub to provide seamless code sharing, rapid development, and consistent identity across our web and systems engineering stack.

Key Features

• Features are to be adjusted to your own project needs.

Category	Feature	Implement Status
Packaging agnostic	Binary only deployment	✔️
	Lore ipsum	✔️
Lore ipsum agnostic
	LORE IPSUM	✔️
	Advanced unit testing	🔶
	Advanced performance testing	🔶
	Advanced fuzz testing	🔶

Legend:

• ✔️ - completed
• 🔶 - in progress
• ❌ - not started

Dependencies

This enumeration also includes submodules.

If you just want the newest versions allowed by your current constraints (updates Cargo.lock only):

Update all:

# update packages
cargo update
# update versions in Cargo.toml
cargo install cargo-edit
cargo upgrade --dry-run --verbose
# --pinned 
cargo upgrade --incompatible

Useful tools

• cargo-outdated

Getting Started

Prerequisites

Installation

1. Clone the repo

   git clone --recurse-submodules git@github.com:Kataglyphis/Kataglyphis-RustProjectTemplate.git

Tests

Run

cargo run -- read --path ../README.md

Windows: GStreamer + ONNX Overlay (WGPU)

Build + Run (CPU via tract):

cargo run --bin kataglyphis_rustprojecttemplate --features gui_windows,onnx_tract -- gui --backend dx12

Build + Run (ONNX Runtime + DirectML):

cargo run --bin kataglyphis_rustprojecttemplate --features gui_windows,onnxruntime_directml -- gui --backend dx12

Build + Run (ONNX Runtime + CUDA, NVIDIA):

# PowerShell
$env:KATAGLYPHIS_ORT_DEVICE="cuda"
cargo run --bin kataglyphis_rustprojecttemplate --features gui_windows,onnxruntime_cuda -- gui --backend dx12

# CMD
set KATAGLYPHIS_ORT_DEVICE=cuda
cargo run --bin kataglyphis_rustprojecttemplate --features gui_windows,onnxruntime_cuda -- gui --backend dx12

Optional environment variables:

• KATAGLYPHIS_ONNX_MODEL – Pfad zum ONNX-Modell (Default: models/yolov10m.onnx)
• KATAGLYPHIS_ONNX_BACKEND – tract oder ort (Default: automatisch)
• KATAGLYPHIS_ORT_DEVICE – cpu | auto | cuda (Default: cpu)
• KATAGLYPHIS_PREPROCESS – letterbox | stretch (Default: stretch)
• KATAGLYPHIS_SWAP_XY – setze 1, falls die Modell-Ausgabe X/Y vertauscht (Default: 0)
• KATAGLYPHIS_SCORE_THRESHOLD – Score-Schwelle für Erkennung (Default: 0.5)
• KATAGLYPHIS_INFER_EVERY_MS – Inferenz-Intervall in ms (Default: 100, 0 = jedes Frame)

CUDA Hinweise:

• Benötigt NVIDIA-Treiber + CUDA/cuDNN Runtime auf dem System.
• Wenn CUDA-Init fehlschlägt, kann KATAGLYPHIS_ORT_DEVICE=auto genutzt werden (fällt auf CPU zurück).

Overlay:

• Zeigt FPS, Inferenz-Latenz, CPU/RSS und eine CPU-Historie.
• Inferenz kann im Overlay ein-/ausgeschaltet werden.

Analysis

cargo +nightly check --manifest-path Cargo.toml --target wasm32-unknown-unknown -Z build-std=std,panic_abort

Resource usage logging (CPU/GPU/RAM)

cargo run --features gui_windows,onnxruntime_directml -- --resource-log --resource-log-interval-ms 1000 --resource-log-gpu=true gui

Optional: zusätzlich in Datei schreiben

cargo run --features gui_windows,onnxruntime_directml -- --resource-log --resource-log-file .\resource.log gui

Burn / PyTorch-Replacement Demos

Diese Demos sind als separates Binary integriert und per Feature gated.

cargo run --features burn_demos --bin burn-demos -- --help

Beispiele:

cargo run --features burn_demos --bin burn-demos -- tensor-demo

cargo run --features burn_demos --bin burn-demos -- linear-regression --epochs 50 --steps-per-epoch 50 --lr 0.02 --batch-size 256

cargo run --features burn_demos --bin burn-demos -- xor --epochs 2000 --lr 0.05

cargo run --features burn_demos --bin burn-demos -- two-moons --epochs 200 --steps-per-epoch 50 --lr 0.01 --batch-size 256

# ONNX Runtime YOLOv10m Demo (Default model: models/yolov10m.onnx)
cargo run --features burn_demos --bin burn-demos -- onnx-yolov10 --runs 1 --print-topk 3

Windows

cargo run --features gui_windows -- gui --backend dx12

# Vulkan backend
cargo run --features gui_windows -- gui --backend vulkan

# Auto-select (wgpu PRIMARY)
cargo run --features gui_windows -- gui --backend primary

Windows MSIX packaging

Voraussetzungen:

• Windows SDK (inkl. makeappx und signtool)
• PowerShell 5.1+ oder PowerShell 7+

MSIX bauen (inkl. Release-Build):

powershell -ExecutionPolicy Bypass -File .\scripts\windows\New-MsixPackage.ps1

MSIX bauen und mit einer vorhandenen PFX signieren:

powershell -ExecutionPolicy Bypass -File .\scripts\windows\New-MsixPackage.ps1 `
  -CertificatePath .\certs\my-signing-cert.pfx `
  -CertificatePassword "<PASSWORD>"

MSIX bauen und Testzertifikat automatisch erzeugen:

powershell -ExecutionPolicy Bypass -File .\scripts\windows\New-MsixPackage.ps1 `
  -CreateTestCertificate `
  -CertificatePassword "<TEST_CERT_PASSWORD>"

Output:

• Paket: dist\msix\Kataglyphis.RustProjectTemplate_<VERSION>_x64.msix
• Staging-Inhalt: dist\msix\staging\

Wichtige Parameter:

• -Binary (Default: kataglyphis_rustprojecttemplate)
• -Features (Default: gui_windows,onnxruntime_directml)
• -Version (Format: Major.Minor.Build[.Revision])
• -Publisher (muss zum Signaturzertifikat passen, z. B. CN=Kataglyphis)
• -SkipBuild (packt vorhandenen Release-Build erneut)

MSIX installieren (mit Testzertifikat):

1. PowerShell als Administrator öffnen.
2. Zertifikat in vertrauenswürdige Stores importieren.
3. Paket installieren.

$certPath = "C:\\GitHub\\Kataglyphis-Inference-Engine\\ExternalLib\\Kataglyphis-RustProjectTemplate\\dist\\msix\\Kataglyphis.RustProjectTemplate.testcert.pfx"
$msixPath = "C:\\GitHub\\Kataglyphis-Inference-Engine\\ExternalLib\\Kataglyphis-RustProjectTemplate\\dist\\msix\\Kataglyphis.RustProjectTemplate_0.1.0.0_x64.msix"
$pwd = ConvertTo-SecureString "<TEST_CERT_PASSWORD>" -AsPlainText -Force

Import-PfxCertificate -FilePath $certPath -Password $pwd -CertStoreLocation "Cert:\\LocalMachine\\Root"
Import-PfxCertificate -FilePath $certPath -Password $pwd -CertStoreLocation "Cert:\\LocalMachine\\TrustedPeople"

Add-AppxPackage -Path $msixPath

Installationsprüfung:

Get-AppxPackage -Name "Kataglyphis.RustProjectTemplate" | Select-Object Name, PackageFullName, Status

Troubleshooting:

• 0x800B0109: Zertifikatskette ist nicht vertrauenswürdig. Zertifikat wie oben in LocalMachine\\Root und LocalMachine\\TrustedPeople importieren (Admin erforderlich).
• Import-PfxCertificate: Zugriff verweigert: PowerShell nicht als Administrator gestartet.
• Details zum letzten Deploy-Fehler anzeigen:

Get-AppxLog -ActivityID <ACTIVITY_ID>

App nach Installation starten:

• Über das Startmenü nach Kataglyphis RustProjectTemplate suchen und starten.
• Oder per PowerShell:

$pkg = Get-AppxPackage -Name "Kataglyphis.RustProjectTemplate"
Start-Process "shell:AppsFolder\$($pkg.PackageFamilyName)!App"

MSIX Update / Reinstall:

• Neue Version mit höherer -Version bauen und signieren.
• Dann erneut installieren:

Add-AppxPackage -Path "C:\\GitHub\\Kataglyphis-Inference-Engine\\ExternalLib\\Kataglyphis-RustProjectTemplate\\dist\\msix\\Kataglyphis.RustProjectTemplate_<NEW_VERSION>_x64.msix"

MSIX deinstallieren:

Get-AppxPackage -Name "Kataglyphis.RustProjectTemplate" | Remove-AppxPackage

Linux

# WGPU (recommended)
cargo run --features gui_wgpu -- gui --backend vulkan

# GTK demo
cargo run --features gui_unix -- gui

Docs

cargo doc --open

Updates

How to update all installed packages:

1. Install updater:

cargo install cargo-update

2. Now update all packages:

cargo install-update -a

Cameras

sudo v4l2-ctl --list-formats-ext -d /dev/video0
gst-launch-1.0 v4l2src device=/dev/video0 ! videoconvert ! autovideosink
gst-launch-1.0 videotestsrc ! video/x-raw,width=640,height=480,framerate=30/1 ! autovideosink

Roadmap

Upcoming :)

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Contact

Jonas Heinle - @Cataglyphis_ - jonasheinle@googlemail.com

Project Link: https://github.com/Kataglyphis/...

Acknowledgements

Literature

Some very helpful literature, tutorials, etc.