Slicer API (серверний слайсинг)¶

BamDude вміє слайсити STL і unsliced-3MF файли на сервері, спілкуючись з контейнерним OrcaSlicer чи BambuStudio sidecar по HTTP. Кидаєш файл у бібліотеку, тиснеш Slice, обираєш модель принтера + філамент-профіль — і за хвилину готовий .gcode.3mf лежить у бібліотеці. Без ноутбука, без слайсера-проксі, без перетягування файлів.

Опційно: жоден слайсер не їде в самому BamDude-образі. Sidecar запускається окремо (Docker Compose рецепт нижче), а BamDude'у кажеш, де він живе.

:material-architecture: Архітектура¶

                ┌───────────────┐
   Файл бібл-и  │   BamDude     │   STL / 3MF (settings)
  ──────────►   │   backend     │ ──────────────────►
                │               │                          ┌──────────────────┐
                │  slicer_api   │   POST /slice            │ slicer-api       │
                │  HTTP bridge  │ ──────────────────►      │ sidecar          │
                │               │                          │   OrcaSlicer чи  │
                │               │   GET /slice/progress    │   BambuStudio    │
                │               │ ◄──────────────────      │   CLI всередині  │
                │               │                          │                  │
                │               │   .gcode.3mf bytes       │                  │
                │               │ ◄──────────────────      │                  │
                │               │                          └──────────────────┘
                │  Library row  │
                │  + archive    │
                └───────────────┘

Bridge тримає sliced-output у бібліотеці (чи в архіві, залежно з якої сторінки слайсив), записує кожен параметр, що пішов у слайсинг, і чисто фейлиться, якщо sidecar offline чи відмовив файл.

Підтримувані sidecar'и¶

Слайсер	Контейнер	Примітки
OrcaSlicer	Open-source community-image	Рекомендований — активно розвивається, широка підтримка принтерів/пластиків.
BambuStudio	Офіційний Bambu Lab	Коли треба байт-в-байт повтор результату десктопного Bambu Studio.

Обидва говорять одним і тим самим /slice HTTP API. Можеш запускати один з них або обидва одразу; активний(і) обираєш у Settings → Profiles → Slicer API.

Setup через Docker Compose¶

В репо BamDude уже шипиться готовий стек у slicer-api/ — найпростіший спосіб через нього:

git clone https://github.com/kainpl/bamdude.git
cd bamdude/slicer-api/
cp .env.example .env       # опційно — pin версії слайсерів / порти

# Обери рівно один:
docker compose --profile orca   up -d   # тільки OrcaSlicer    (host port 3003)
docker compose --profile bambu  up -d   # тільки BambuStudio   (host port 3001)
docker compose --profile all    up -d   # обидва

Голий docker compose up -d (без profile) не запустить нічого — треба явно вказати --profile orca, --profile bambu чи --profile all. Потім у BamDude → Settings → Profiles → Slicer API заповни URL для слайсерів, які запустив (http://localhost:3003 для Orca, http://localhost:3001 для BambuStudio).

Docker Desktop 4.71 — обхід для першого білда

Docker Desktop 4.71 (engine 29.4.1 / compose v5.1.x / buildx 0.33.x-desktop) має зламаний buildx bake compose-bridge: docker compose build миттєво падає з failed to execute bake: exit status 1 без жодних деталей, незалежно від форми profiles. COMPOSE_BAKE=false НЕ вимикає bake на цій версії.

Обхід для першого білда — форснути legacy classic builder; image тоді кешується і compose up -d перевикористовує його:

# bash / zsh
DOCKER_BUILDKIT=0 COMPOSE_DOCKER_CLI_BUILD=0 \
  docker compose --profile all build
docker compose --profile all up -d

# PowerShell
$env:DOCKER_BUILDKIT = "0"; $env:COMPOSE_DOCKER_CLI_BUILD = "0"
docker compose --profile all build
$env:DOCKER_BUILDKIT = $null; $env:COMPOSE_DOCKER_CLI_BUILD = $null
docker compose --profile all up -d

Або викликай buildx напряму (modern BuildKit, паралельно, швидше):

docker buildx bake -f docker-compose.yml orca-slicer-api
docker buildx bake -f docker-compose.yml bambu-studio-api
docker compose --profile all up -d

Старіші релізи Docker Desktop (4.70 і нижче) та Docker CE на Linux баг не зачепив — env vars не потрібні.

Запустити sidecar(и) на іншій машині¶

Якщо BamDude-сервер сам не може крутити sidecar-контейнери (resource-ліміти, немає Docker, тощо) — постав sidecar(и) на окремій машині й вкажи їхні URL у BamDude. Той самий slicer-api/docker-compose.yml з репо BamDude використовуй на хості sidecar'ів, потім у Settings → Profiles → Slicer API встанови URL'и http://<sidecar-host>:3003 / :3001 замість localhost. Sidecar не має auth — тримай у trusted network (LAN, Tailscale, WireGuard).

Можеш також override'нути env-дефолти, які BamDude читає на старті: SLICER_API_URL (default http://localhost:3003) і BAMBU_STUDIO_API_URL (default http://localhost:3001). UI-поля URL мають пріоритет, якщо встановлені.

Settings → Profiles → Slicer API¶

Опція	Що робить
Preferred slicer	`OrcaSlicer` чи `Bambu Studio`. Sidecar за замовчуванням для server-side (in-app) слайсингу. Коли обидва sidecar'и налаштовані і доступні, Slice-modal показує per-job радіо "Slice with" для перевизначення цього default'а per source file (вибір запам'ятовується для кожного файлу в browser localStorage).
Enable server-side slicing (`use_slicer_api`)	Master-тоглер. Коли off — кнопка Slice пропадає з File Manager, слайсинг падає на open-in-desktop-slicer через URI scheme.
OrcaSlicer API URL (`orcaslicer_api_url`)	URL OrcaSlicer-sidecar'а — наприклад `http://localhost:3003` для дефолтного compose-рецепту. Порожнє = використати `SLICER_API_URL` env-дефолт.
BambuStudio API URL (`bambu_studio_api_url`)	URL BambuStudio-sidecar'а — наприклад `http://localhost:3001`. Порожнє = `BAMBU_STUDIO_API_URL` env-дефолт.
Slicer stall timeout (`slicer_stall_timeout_minutes`)	У Settings → General → Slicer. Хвилин чекати без жодного прогресу від sidecar'а. Типово 15, діапазон 1–240. Деталі нижче.

Stall timeout — це не обмеження на те, скільки може різатися модель

Поки триває нарізка, BamDude раз на секунду питає sidecar про прогрес — саме це живить toast із відсотками. Годинник скидається на кожному оновленні прогресу, тож важка модель, яка продовжує звітувати, дорізається до кінця хоч скільки часу, і чекання завершує лише справжня тиша.

На старішому sidecar'і, який не вміє звітувати про прогрес, судити про живість нічим — тому те саме число обмежує загальний час нарізки: стара поведінка, але з числом, яке можна підняти, замість п'яти хвилин, зашитих у код.

Sidecar, який узагалі не приймає з'єднання, і далі одразу позначається як недоступний.

Desktop-кнопка Open in Slicer керується окремим, незалежним налаштуванням — Settings → Slicer → Open in Slicer — dropdown'ом, що за замовчуванням стоїть на Same as API slicer. Вкажи інший слайсер, щоб, наприклад, слайсити через Bambu Studio sidecar, а файли відкривати локально в OrcaSlicer (чи навпаки); наявні налаштування не змінюються, поки ти сам не вибереш інше значення.

Preset-tiers (Imported/Local → Orca Cloud → Bambu Cloud → Standard) backend перелічує автоматично у момент слайсингу — per-install setting не потрібен, див. "Слайсинг файлу" нижче.

Слайсинг файлу¶

З File Manager: меню дій на STL / 3MF / STEP / STP файлі → Slice.

Відкривається Slice-modal з трьома preset-dropdown'ами:

Printer profile — з уніфікованого preset-listing'а. Кожен запис прийшов з одного з чотирьох tier'ів у фіксованому порядку пріоритету й без dedup між tier'ами (local → orca_cloud → cloud → standard): local (твої імпортовані/локальні .json-профілі), orca_cloud (per-user Orca Cloud-пресети), cloud (per-user Bambu Cloud-пресети), standard (bundled-defaults у sidecar'і). Оскільки dedup'у немає, однойменний пресет у двох tier'ах перелічується по разу в кожному — він більше не ховається лише через те, що інший tier має пресет із таким самим ім'ям. Modal лейбл показує tier поряд із кожним варіантом. За замовчуванням обирається принтер, під який готувався вихідний 3MF (якщо такий профіль доступний), інакше — перший у списку.
Process profile — ті самі чотири tier'и, але відфільтровані під обраний принтер: профілі для інших принтерів зсуваються в кінцеву групу «Other printers» замість того, щоб зникати, а профілі без інформації про принтер лишаються в основному списку (ніколи не ховаються). За замовчуванням — process, під який готувався 3MF, якщо він сумісний. Зміна принтера перевибирає process, якщо поточний більше не підходить.
Filament profile(s) — один dropdown на кожен слот філаменту, який декларує проєкт, а не лише на ті, якими малює ця плита; фільтрація та сама (сумісні профілі спершу, група «Other printers» в кінці). Modal pre-pick'ає найкращий match per-slot використовуючи filament-metadata з вихідного 3MF (type + colour score), з пониженням несумісних із принтером філаментів, щоб один клік Slice робив правильне для multi-color jobs.

Чому показані всі декларовані слоти, навіть невживані

Слайсер прив'язує цей список за позицією. Модель, яка декларує чотири філаменти, але малює лише слотом 4 — типова форма з MakerWorld — раніше показувала один dropdown, і твій вибір потрапляв у слот 1; а слот 4, яким модель насправді друкує, різався з тим, що там лишив автор. Друк виходив не з того матеріалу, і ніщо на екрані на це не натякало.

Слоти, яких ця плита не використовує, показані сірими (див. нижче), тож вибір філаменту для слота 4 тепер виставляє саме слот 4.

Діалог Print свідомо влаштований інакше: він питає, які котушки потрібні завданню, і йому потрібна вузька відповідь — інакше він змушував би зарядити три котушки, яких друк ніколи не торкнеться.

Modal кешує cloud- і standard-preset-listing'и на кілька хвилин, тож якщо ти видалиш чи перейменуєш пресет у Bambu Studio / Bambu Handy — він може ще якийсь час висіти в dropdown'ах. Контрол Refresh на списку пресетів одразу тягне свіжі listing'и. Імпорт чи видалення локального профілю в Settings також миттєво оновлює пресети Slice-діалогу.

Сумісність визначається власним списком compatible_printers профілю (якщо є), потім за конвенцією іменування @<принтер> — в усіх трьох формах, які пише слайсер: @BBL <model>, повна @Bambu Lab <model> <size> nozzle (яку отримує збережений користувачем пресет) і голий тег @<size>. Голий розмір може виключити принтер, але ніколи не вважається доказом збігу, а розміри порівнюються числово, тож 0.20 і 0.2 — одне й те саме. Профілі Orca Cloud несуть власний список сумісних принтерів, а копія профілю, яка знає свої принтери, ділиться цим списком із копіями, що не знають — саме це не дає профілю, чия назва не містить моделі (Overture PLA Matte @0.2), бути автоматично обраним для принтера, під який його ніколи не робили. Вона враховує сопло, тож process під сопло 0.6 не буде сумісним для принтера із соплом 0.4 (0.4 — неявне за замовчуванням, що не несе суфікса). Той самий matcher керує підбором профілів у майстрі калібрування філаменту; там несумісні профілі ховаються повністю, а не групуються, бо калібрувальний друк на не тому принтері просто марнує стіл.

Slicer-picker сидить угорі Slice-діалогу — дві картки-кнопки (дзеркалять "Filament Tracking"-патерн з Settings) з власними live-індикаторами здоров'я. Авто-локається на єдиний здоровий sidecar, коли інший лежить; ти вибираєш вільно, коли обидва доступні; offline-картки disabled. Перший раз default — глобальний Preferred slicer; наступні відкриття того самого source file пам'ятають твій останній вибір (per-file localStorage).

Override типу столу (5 варіантів: Cool / Engineering / High Temp / Textured PEI / SuperTack) пробрасується в --curr-bed-type на CLI. Default Textured PEI Plate відповідає заводській плиті на сучасній лінійці Bambu; власники A1 / A1-mini переключаються на SuperTack один раз і вибір зберігається в localStorage. Сліцені 3MF із Bambu Studio все ще шанують свій вбудований per-plate bed_type (BamDude форвардить оригінальні байти) — override спрацьовує тільки для джерел без нього.

Контрол джерела пресетів над пресет-dropdown'ами — це 3-станковий segmented owner-фільтр (All / My presets / Built-in), застосований до всіх чотирьох tier'ів. Він класифікує cloud-пресети як custom-vs-builtin за тим самим setting_id-regex'ом, що й сторінка Profiles, ^(P[FPM]US|PF\d|PP\d); local-імпорти завжди custom, standard-пресети завжди built-in. Вибраний фільтр зберігається в localStorage під ключем bamdude:slice-modal:filter-owner. Перемикання фільтра скидає поточний вибір у dropdown'ах, що тепер не матчиться, щоб прихований (відфільтрований) пресет не міг тихо засабмітити при slice.

Для multi-plate 3MF modal вбудовує inline plate-selector угорі body, дзеркаля picker плит з Print modal — вертикальний paginator + details-картка. Плита 1 авто-вибирається на load, щоб filament-requirements + presets-запити йшли без блокування на user-interaction; клік по іншій плиті пере-ключає ці запити. Чекбокс Нарізати всі плити над picker'ом: познач його, щоб нарізати всі плити в один multi-plate вихід (plate=0) замість однієї обраної.

Перенарізання під інший принтер — можна нарізати 3MF, зроблений під іншу модель. Обери будь-який профіль принтера, і слайсер перенаріже під цю ціль (стіл, кінематика, к-сть сопел і start-gcode беруться з обраного профілю). Коли ціль перетинає клас сопла (одне ↔ два сопла H2D/H2C/X2D), BamDude пробрасує --arrange, щоб BambuStudio переставив об'єкти під цільовий стіл і узгодив вбудовані налаштування; крос-клас «нарізати всі плити» нарізає кожну плиту окремо й зливає в один файл. Якщо слайсер усе одно не може дати валідний результат — його причина показується в діалозі, який треба закрити, а не в тості, що зникає.

Нарізати як задумано (зберегти вбудовані налаштування файлу)¶

Зазвичай нарізання застосовує обрані тобою пресети Принтер / Процес / Філамент, які перекривають усе, що автор файлу вклав у вбудований project_settings.config. Саме це перекриття дозволяє перенарізати під інший принтер — але через нього модель із MakerWorld, налаштована, скажімо, на п'ять стінок, виходить із двома за замовчуванням твого пресета.

Коли вихідний 3MF несе вбудовані налаштування і обраний тобою принтер збігається з тим, під який файл проєктували, у модалці з'являється чекбокс Використати вбудовані налаштування файлу. Постав його — і BamDude нарізає без перекриття пресетами, тож результат визначають авторські кількість стінок, заповнення, філамент та інші налаштування процесу.

Дропдауни пресетів і вибір типу столу блокуються — принтер, процес, філамент і тип столу. На цьому шляху вони не використовуються, тож блокуються, щоб це було очевидно (і щоб зміна принтера не витягла тебе непомітно з дизайну, сховавши чекбокс).
Філамент теж береться з файлу, а не з твоїх виборів AMS. Якщо філаменти файлу не збігаються із зарядженим — зістав їх на принтері або зніми чекбокс і обери свої.
Пропонується лише коли твій принтер збігається з цільовою моделлю дизайну. Дотримання вбудованих налаштувань для іншої моделі поставило б об'єкт на неправильний стіл — саме для цього існує шлях із пресетами — тож чекбокс просто не показується, коли принтер інший.

Це не злиття налаштувань

Або-або: ти отримуєш повний профіль дизайнера, або свій. Залишити авторські стінки, підмінивши свій філамент, тут не вийде — для цього є Налаштування друку дизайнера нижче: там вибір по кожному параметру, і воно працює між різними принтерами.

Налаштування друку дизайнера (по параметрах, між принтерами)¶

Середина між «твій пресет» і «нарізати як задумано»: обираєш власні принтер, процес і філаменти — і переносиш лише окремі параметри, які змінив автор.

Коли вихідний 3MF декларує відхилення від свого стокового профілю, діалог Slice додає панель The designer's print settings зі списком саме тих параметрів процесу, які змінив автор, і того, у що кожен виставлений, — з чекбоксом на кожен. Застосовується тільки те, що ти позначив.

Група	Приклади	Типово
Задум дизайну	кількість стінок, щільність і патерн заповнення, висота шару й першого шару, підтримки, шов, брим, ironing	позначено
Підлаштоване під машину — бейдж `machine-tuned`	швидкості, прискорення, ривок, обдув, температури, геометрія prime tower	не позначено

Підлаштовані під машину значення автор обирав для свого принтера. На твоєму вони можуть бути просто хибними — або поза діапазоном, який приймає твій профіль, що завалює нарізку взагалі. Тому вони показані з бейджем і лишені вимкненими, щоб вирішував ти.

Тут нічого не вгадується

Bambu Studio сам записує перелік відхилень у файл (different_settings_to_system у Metadata/project_settings.config). BamDude читає цей перелік, а не порівнює профілі й не здогадується про намір.

Файл, чий перелік не збігається з його ж кількістю слотів філаменту, ігнорується, а не інтерпретується: хибне прочитання ризикує перенести стартовий G-code машини автора на твій принтер.

Панель працює й при нарізці для іншого принтера — саме там, де «нарізати як задумано» не пропонується. Вона так само з'являється при передруку з архіву.

Слоти філаменту, які твоя плита не використовує¶

У мультиплейтовому проєкті кожна плита зазвичай малює лише частиною слотів філаменту проєкту. Діалог нарізання підписує решту «— не використовується цією плитою» і глушить їхні дропдауни — але слайсер усе одно хоче профіль для кожного слота й перевіряє їх усі.

Тому перед нарізанням однієї плити BamDude замінює профіль кожного невикористаного слота профілем із найменшого використаного слота плити. Це зберігає кількість слотів (і посилання файлу на них), водночас роблячи заряджений набір і однорідним за матеріалом, і прив'язаним до цільового принтера — тож жоден валідатор не спрацює на слоті, якого G-code навіть не торкається:

«the temperature difference of the filaments used is too large» — дефолтний ABS поруч із PLA, яким плита насправді друкує.
«filament preset (slot N) is not compatible with printer …» — профіль, збережений для іншого принтера (напр. філамент @Bambu Lab H2D, вшитий у вихідний файл), у слоті, який твоя плита ігнорує.

Нарізання всіх плит цього не робить: у межах усього проєкту кожен визначений слот кимось використовується, тож профіль кожного шанується як обрано.

Індикатори доступності¶

Здоров'я sidecar'ів виходить на трьох поверхнях, всі шерять один React-Query-кеш + ендпоінт GET /api/v1/slicer/health/{slicer} (30 с in-process cache):

Settings → Profiles → Slicer API — невеликий inline-статус біля кожного URL-поля (зелений чек + версія, або червоний хрестик з помилкою).
Slice modal — кожна картка picker'а несе live-індикатор здоров'я (див. вище).
System page → Slicer Sidecars секція — версія + доступність + URL кожного sidecar (auto-refresh 30 с разом із рештою system info).

Persistent-toast у нижньому правому кутку трекає job: live progress percent + elapsed time, заміняється transient success/error toast при завершенні. Sliced-output лягає в ту ж папку бібліотеки як .gcode.3mf з source_type='sliced' provenance — оригінал не чіпається.

Дозволи¶

Permission	Що дозволяє
`library:upload`	Тригерити слайсинг із File Manager (sliced-output — це свіжий library-upload).
`library:read`	Поллити job-tracker toast (`/api/v1/slice-jobs/{id}`) і filament-discovery preview-slice progress (`/api/v1/slicer/preview-progress/{id}`).
`cloud:auth`	Потрібно щоб тягнути `cloud` preset-tier — без неї modal показує тільки `local` + `standard` tier'и.

Settings → Profiles → Slicer API toggle і URL-поля гейтяться settings:update.

Режими провалу¶

Sidecar offline → 502 у toast'і, job marked failed; оригінал не чіпається. «Не вдалося під'єднатися» і «перестав чекати» — це різні повідомлення, і в повідомленні про таймаут названо, який ліміт вичерпано і де його змінити.
Нарізка не дала результату → відповідь, яка є «OK» на кілька байтів — зламана конфігурація slicer-сервісу, reverse proxy, що повернув власну сторінку помилки, обрізана відповідь, падіння слайсера без запису виводу — відхиляється до збереження файлу, а не зберігається, ставиться в чергу й вирушає на принтер, який потім нічого не робить. Нарізку, відхилену як завелику, названо тим, чим вона є: обмеженням розміру на проксі перед слайсером, а не збоєм слайсера.
Profile not found → 400 називає відсутній профіль — додай через K-Profiles або обери інший tier.
Sidecar відмовив файл (corrupt 3MF, unsupported plate, malformed preset, etc.) → toast показує дослівний CLI stdout/stderr sidecar'а — не треба копати в логах контейнера.
Embedded-settings fallback — для 3MF-джерел 5xx від sidecar'а з --load-settings тригерить ОДИН retry без profiles. Тоді слайсинг використовує embedded-settings джерела (ті, що оригінальний слайсер запік у Metadata/slice_info.config); результат несе used_embedded_settings: true у metadata. У STL embedded-settings нема, тож 5xx там terminal.
Cloud presets unreachable (token expired / network down) → modal рендерить cloud-tier зі status-banner'ом і фолится на local + standard only.

Дивись також¶

File Manager — де живе кнопка Slice.
K-Profiles — як завантажити локальні OrcaSlicer-профілі філаменту в local-tier.
MakerWorld import — поєднай імпорти з server-side слайсингом, коли жодна плита не підходить твоєму принтеру.