ZSLICEDOCS

Project

The zslice app

The zslice app has one core and one native shell for each platform:

PlatformShellFolderStatus
LinuxGTK4, Clinux/Works
WebHTML, JavaScript, WebGL2web/app/First version: see web/app/README.md
macOSSwiftUI, AppKit, Metalmacos/First version: see the macOS app
iOSSwiftUIios/Planned
WindowsWin32, C++windows/Planned
AndroidKotlinandroid/Planned

The rule: logic in the core, widgets in the shell

The app core (src/app.zig, C API in include/zslice-app.h) has all the app logic: the model, the settings, the slice job, the result, the layer paths for the preview, and the license list.

A shell does only three things:

  1. It draws native widgets.
  2. It reads and writes files. The core does no file I/O, so it works in a sandbox (iOS, a browser).
  3. It moves core events to its UI thread.

If a shell needs a decision (when to slice again, what a setting means, how to format a value from the core), the decision goes in the core, and each shell calls it. Then all shells behave the same.

The contract

Read include/zslice-app.h first. The main points:

The core has the printer library (zs_printers_*) and the packets of the printer search (zs_discovery_*). A shell draws the picker from them; the facts, the search, the match of a printer on the network, and the machine profile of a model come from the core. Native builds embed the library. The web app loads printers.txt when the picker opens. The core does no network I/O: the shell sends the mDNS query and gives the answers to the core, and it asks a new printer for /api/version (or the Klipper toolhead). A browser cannot do this, so the web picker asks for an address.

The bed model of the current printer comes from the library too. zs_printers_find_machine finds the model of the machine profile (machine.model, else a machine.name that is the title of a model), and zs_printers_bed names its two files in the bed folder. The shell reads the files and gives the bytes to zs_view_set_bed; the core reads the mesh and the PNG, places the bed, and sends it to the GPU once. The GTK shell reads the files from share/zslice/beds (installed by meson), or from src/printers/beds of the source tree, or from $ZSLICE_BEDS_DIR (see ui/bed-model.h). The web app fetches them from beds/. Both pickers draw a flat texture (zs_printer_bed.flat) on the plate of the build volume.

The 3D view

The core draws the 3D view of a slice (src/render/). The shell gives a native surface, and calls the zs_view_* functions of include/zslice-app.h:

  1. Make a native surface for the view widget: on Linux, a Wayland subsurface under the window (linux/src/ui/native-surface.c); later an HWND on Windows and an ANativeWindow on Android. On macOS and in a browser, the shell draws the frame data itself (ZS_SURFACE_FRAME), so the core needs no surface.
  2. zs_view_new with the surface and the size in pixels.
  3. After ZS_EVENT_SLICED: zs_view_load.
  4. On a change (layer, drag, scroll, size): call zs_view_set_layer, zs_view_orbit, zs_view_zoom, or zs_view_resize, then zs_view_draw once. Draw only after a change, so that a static view uses no CPU.

The goal of the view is to look like the finished print. Each segment is a bead with the real cross section (a flat top and bottom, round sides), round ends, the width of the plastic that is really deposited, the cooled size (the shrinkage compensation removed), and the filament color (filament.color). zs_view_set_mode switches to one color for each feature.

The backend is Vulkan on Linux (and later Windows and Android). In a browser and on macOS, the frame backend (src/render/web.zig) keeps the frame data in the memory of the core, and the shell draws it: the page with WebGL2 (see web/app/README.md), and the macOS app with Metal (see the macOS app). The core loads the Vulkan loader at run time, so a shell does not link it. Without Vulkan, zs_view_new returns ZS_NOT_SUPPORTED, and the shell shows the 2D view only.

On Linux, the GTK window is transparent, and the view widget draws nothing: the subsurface shows through it. Each other part of the window must paint its whole area (use padding, not margins).

The GTK shell has options for development and tests. See Test hooks of the GTK shell.

Inspect a path

A click on a path in a view picks it: zs_app_pick_layer in a 2D layer view (a point in mm), and zs_view_pick in the 3D view (a pixel). zs_app_inspect then gives what the path is, its real values (the bead width, the planned and the real speed, the flow, the time span), the reasons for them in plain words, and the names of the settings that change it. The shell shows the text and an editor for each setting, and highlights the path (zs_view_highlight).

After a new slice, the path numbers change. The GTK shell keeps the layer and a point of the selected path, and picks the path at that place again, so that the inspector stays on the same line after a setting changes.

A shell with no access to the app on its UI thread (the web app: the app is in a worker) uses the loaded view instead. zs_view_pick_layer picks in a 2D view, zs_view_layer_beads, zs_view_layer_marks, and zs_view_outlines give the data of one layer to draw, and zs_view_step, zs_view_nearest_on_layer, and zs_view_segment_at_time give the steps of the keys h, j, k, and l. A pick uses the pick index of the view, so it stays under a millisecond on a plate of many parts.

Replay

zs_view_set_time(view, t) shows the print as it is t seconds after the start: each bead that is done, and the part of the bead that the nozzle is printing. The times come from the G-code emitter, with the cooling slow-down, so the replay follows the G-code. A shell moves t on each frame while it plays (GTK: a frame-clock tick callback, at a speed of 1x to 100x), and shows zs_view_layer_at_time on its layer slider. zs_view_set_layer ends the replay.

The GTK shell

The GTK shell is in linux/src. Each .c file has a header that explains its interface:

FolderFileWhat it has
main.cThe application, and a watchdog of the UI thread
model/app-modelThe core as a GObject: signals on the UI thread, the saved state
prefs/printersThe printers of the user, and the app settings file
net/printer-linkHTTP and USB connections to printers
discoveryThe search of the network for printers (mDNS), with the packets of the core
project-sourceThe files of a printdeck.yml project: a folder, or a public GitHub repository
ui/windowThe main window: the header bar, the file dialogs, the send to a printer, and the status bar
previewThe 2D and 3D preview with the tool strip, the layer slider, the dock at the bottom (the plates, the replay, and the history), the place of the print card, the view buttons of the header bar, the measure readout, and the keyboard navigation
layer-drawThe cairo drawing of one layer in the 2D view
toolpath-navThe next segment and the nearest line, for the keyboard navigation
layer-rangeThe slider with two knobs for the layers that show
view3dThe widget of the 3D view, the drag of a part, and the rings of the Turn tool
bed-modelThe bed model of the current printer in the 3D view: finds the bed folder and reads the files
native-surfaceThe Wayland subsurface for the 3D view
floatThe cards over the view: their places in the overlay of the preview, and the drag of their head
searchThe settings search (/): settings with live controls, and actions
line-cardThe card of a selected line: its numbers, and the settings that matter for it
part-cardThe card of a selected part: its actions and its own settings
shortcutsThe sheet of the keyboard shortcuts (?): one table of the keys
settings-panelThe panel (a drawer: hidden, over the view, or pinned) with the Settings page and the Selected page, and one top row with the path and one back arrow
inspectorThe "Selected" page: the values of a line and the settings that change it
project-pageThe page of the Project dialog: a printdeck.yml project, its plates and parts, and the status of each plate
farm-pageThe Printers page over the view: a tile for each printer, and the plates to print
historyThe history group of the dock under the preview, and the list of the changes in a popover over it
part-pageThe page of a part: its place, turn, and scale, and the placement
settings-browserThe "Settings" page: all settings in three columns
setting-rowOne setting as a row of a grid
setting-editorThe editor of one setting, and the text of a value
widgetsSmall widget helpers that the pages share
printer-pickerThe printer picker: the first-start onboarding and "Add a printer…"
preferences, licensesThe Preferences and the Licenses windows
colors.hThe feature colors

Test hooks of the GTK shell

These environment variables change the start of the GTK shell, for development, tests, and screenshots. They are the only hidden options of the shell. The last column names the file that reads each one.

VariableEffectRead in
ZSLICE_BEDS_DIR=dirReads the bed models of the printers from dir.ui/bed-model.c
ZSLICE_STATE_DIR=dirKeeps the settings and the printers in dir, not in ~/.config/zslice.prefs/printers.c
ZSLICE_NON_UNIQUE=1Starts a separate instance. Without it, a second start sends its file to the running instance.main.c
ZSLICE_TEST_HANG=sStops the UI thread for s seconds, 3 s after the start, to test the watchdog.main.c
ZSLICE_VIEW=2d or 3dOpens the 2D or the 3D view.ui/preview.c
ZSLICE_COLORS=nStarts with the color mode n (enum zs_view_mode).ui/preview.c
ZSLICE_LAYERS=lo,hiShows the layers from lo to hi after the first slice.ui/preview.c
ZSLICE_TIME=tShows the replay at t seconds before the first frame.ui/view3d.c
ZSLICE_MEASURE=x0,y0,x1,y1Picks the Measure tool, and clicks two points at the pixels x0, y0 and x1, y1 of the view that shows (2D or 3D), 1 s after the first slice.ui/preview.c
ZSLICE_PICK=x,yPicks the path at the pixel x, y of the 3D view after the first load.ui/view3d.c
ZSLICE_DOUBLE_CLICK=x,yA double click at the pixel x, y of the 3D view, 1 s after the first slice: on a side of a part, the view turns to face that side; elsewhere, the view resets.ui/view3d.c
ZSLICE_COPY_FOR_AI=1With ZSLICE_PICK: runs "Copy for AI" on the picked line, and prints the report to the log (with no input event, Wayland can refuse the clipboard).ui/view3d.c
ZSLICE_GAPS=1Turns the gaps view on. ZSLICE_GAP=N then selects gap N of the top layer after a slice.ui/view3d.c
ZSLICE_SETTING_LIST=1With ZSLICE_SETTING: shows the settings list of its section, not its detail page.ui/settings-browser.c
ZSLICE_PROFILE=up or downWith ZSLICE_PICK: runs "New profile from here up" (or down) on the picked line. ZSLICE_PROFILE_SET=name=value then changes one setting in it.ui/view3d.c
ZSLICE_PART=iSelects part i of the plate after the first load.ui/view3d.c
ZSLICE_RING_DRAG=x0,y0,x1,y1 or autoWith ZSLICE_PART: picks the Turn tool, and drags a ring of the part from the pixel x0, y0 to x1, y1 (auto: from the point of the rings at +X to the point at +Y) of the 3D view in 12 steps, 1 s after the first slice. The log gives the axis and the turn.ui/view3d.c
ZSLICE_SUPPORT_DO=stepsPicks the Support tool 1 s after the first slice, and runs one step each 600 ms, as the mouse and the keys would. Steps, with ; between them: orbit dx dy, click x y, shift x y (a click with Shift), key Return (a key by its GDK name), drag i j x y (point j of area i to x, y), kind k (button k of the card), see 0 or see 1, undo, redo. x, y are points of the 3D view. The log gives the areas, their points on the screen, the history, and the filament after each step.ui/support-tool.c
ZSLICE_ZOOM=zStarts the 3D view at the zoom z (for example 0.3: nearer).ui/view3d.c
ZSLICE_ZOOM_AT=x,y,nZooms n wheel steps toward the pixel x, y after the first load.ui/view3d.c
ZSLICE_INSPECT_FOCUS=namePuts the focus on the row of the setting name in the inspector after the first selection.ui/inspector.c
ZSLICE_SETTING=nameOpens the Settings page at the setting name.ui/settings-browser.c
ZSLICE_PROJECT=dir or owner/repoOpens the printdeck.yml project of a folder or of a GitHub repository at the start, and shows the Project dialog. ZSLICE_PROJECT_PLATE=n then opens plate n (from 1), also for the project of the last session.ui/project-page.c
ZSLICE_PROJECT_DO=stepsChanges the widgets of the Project page 3 s after the start, one step each second, as a click would. Steps, with ; between them: status 1 printed, count 2 0, check 2 off, scroll 600, sent, set machine.max_height 300, end, close.ui/project-page.c
ZSLICE_ACTION=nameRuns an action 1.5 s after the first slice, as a click would. The name is a detailed action name, for example win.search-part(int64 0) (the search of part 0), win.show-page('history'), or win.shortcuts. win.show-page accepts settings, selected, history (the popover over the dock), project (the dialog), or farm (the Printers page). win.show-setting('project.infill_density') opens the panel at a setting.ui/window.c
ZSLICE_UNDO_TEST=1Changes the infill, undoes and redoes, moves part 0 and undoes the move, edits the wall count with the focus on its editor, goes to step 1, and clears the history after it, one step each second. The log gives the values and the steps of the history.ui/window.c
ZSLICE_PLATE_TEST=fileAdds a plate and puts the model file on it, adds an empty plate and removes it, goes to plate 1 and back, and removes the plate with the file, one step each second. The log gives the plates of the set (zs_set_plate_info).ui/window.c
ZSLICE_PREFS=1Opens Preferences 1.5 s after the start. With it, ZSLICE_GET_KEY=1 presses "Get a key" for the current printer.ui/window.c, ui/preferences.c
ZSLICE_PICKER=1Opens the printer picker at the start. With it: ZSLICE_PICKER_QUERY=text types a search, ZSLICE_PICKER_MODEL=id selects a model, ZSLICE_PICKER_FOUND=n selects printer n of the network when the search ends, and ZSLICE_PICKER_STEP=2 (the second step) or add (add the printer at once).ui/printer-picker.c

To run the app for a check without your own settings:

ZSLICE_STATE_DIR=$(mktemp -d) ZSLICE_NON_UNIQUE=1 ZSLICE_VIEW=2d linux/build/zslice-gtk part.stl

The preview colors

All shells use the same colors, in the order of enum zs_feature:

FeatureColor
Outer wall#d9480f
Inner wall#f59f00
Skin#1c7ed6
Infill#2b8a3e
Ironing#ae3ec9
Skirt and brim#8d6e63
Support#adb5bd
Support interface#495057
Slope smoothing#0ca6ae
Slope ironing#82c91e
Bridge#66ccf2

Add a shell

  1. Build the core for the platform: zig build lib -Dtarget=<target> -Doptimize=ReleaseFast. It makes libzslice.a and the two headers.
  2. Wrap zs_set (or one zs_app) in one object of the platform (a GObject, an ObservableObject, a ViewModel) that owns the core and moves the events to the UI thread. See linux/src/model/app-model.c.
  3. Build the window: open, export, the settings panel, the preview with a layer slider, a status bar, and a Licenses screen.
  4. Use the GTK shell as the reference for the behavior.

The structure follows the Lookout Marine app (a Zig core with native shells for each platform, by the same author).