🦀 Kataglyphis-RustProjectTemplate 🦀

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

For official docs follow this link.

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

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.

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

Legend:

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

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

• cargo-outdated

1. Clone the repo

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

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

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.

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

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

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

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

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

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

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

cargo doc --open

How to update all installed packages:

1. Install updater:

cargo install cargo-update

2. Now update all packages:

cargo install-update -a

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

Upcoming :)

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

Jonas Heinle - @Cataglyphis_ - jonasheinle@googlemail.com

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

Some very helpful literature, tutorials, etc.