§10 — Structure
Bump mapping & ZBump
One gizmo, three modes, one idea: a grayscale image becomes physical relief at slice time. What changes between the modes is where the relief goes and how it is scoped.
- Libre Mode + env var
- expert-only, on purpose
The gizmo only appears with both Libre Mode active and the debug environment
variable ORCA_DEBUG_TEXTUREBUMP set before launch. Top mode additionally needs
ORCA_DEBUG_ZBUMP (or ORCA_DEBUG_ALL=1) for ZBump to actually apply
when slicing.
Some option combinations here are genuinely capable of producing bad extrusion, which is
the whole reason for the gate. It is kept off unless you have deliberately opted in and are
prepared to read the resulting G-code. The per-OS activation steps live in
NEOTKOCM_RELEASE_2_35.md.
All mode: wall texture
Applies one texture to every wall of the selected object, projected via Planar, Cylindrical, Spherical or Cubic. Three on-canvas 3D handles adjust it without leaving the viewport, and a live textured overlay shows the pattern on the object before slicing so you can line it up by eye. The real object dims while the gizmo is open so the projection is not hidden behind it.
| Handle | Colour | Drag controls |
|---|---|---|
| V | blue | Scale, the tile size in mm |
| U | orange | Repeat count |
| Yaw ring | purple | Rotation around the pivot |
| Pivot | pink | Pan, moving the tile origin |
Wall-texture bump needs the Arachne wall generator. It is deliberately disabled on Classic, because a real test print showed Classic silently over-extrudes when adjacent walls carry different bump amounts, and the preview hides it while the G-code does not. NeoArachne is not wired up for it either. Even on Arachne, adjacent walls with very different bump amounts can still show a visible gap between them, because nothing adjusts line width to compensate, only the centreline moves. That is a known open limitation, not something the gate gets you past.
Painter mode: per zone
Paint zones on the model, with the same brush and erase interaction as the other painter gizmos, and assign each zone its own texture, projection mode, scale and thickness. Independent of the object's base All-mode settings and of every other zone. Each zone gets its own overlay preview and a thumbnail in the zone list, so you can tell them apart at a glance.
Top mode: ZBump
A different feature entirely, sharing no engine code with the wall texture. It modulates the Z height of the top-surface fill rather than wall XY. A grayscale image becomes a literal height field: brighter pixels raise the top surface, sampled point by point along every top-fill line for a real 2D relief rather than one flat Z per line.
0.8 × nozzle − layer height).
| Control | What it does |
|---|---|
| Height (mm) | Max Z displacement at full-white texture value. Shown in red past a safe-height estimate of 0.8 × nozzle − layer height. That is a warning, not a hard cap: you can go past it and judge from the resulting G-code. |
| Reinforcement passes | Splits the total height across multiple stacked passes when it exceeds what one pass can safely reach on its own. |
| Scale / Repeat | Physical size of one image tile, and how many times it repeats. |
| Pan X / Y | Shifts the tiling phase. Drag the on-canvas green handle, or type exact values. |
| Edge ramp (mm) | Smoothstep margin from the top-fill's own contour, so the wall itself stays flat. |
The green pan handle rests at the object's own centre plus the current offset, and a live textured overlay previews the pattern before slicing, cropped to roughly where top-fill actually starts, inset from the outer edge by the perimeter walls. Drag the handle or type in the numeric fields; both update the same preview live.
The overlay is a GUI-only approximation. The perimeter inset is estimated rather than being
the engine's exact fill boundary, so it is a placement guide and not a pixel-perfect match.
It is cross-checked against the real slicing maths through a calibration log
(ORCA_DEBUG_ZBUMP writing to /tmp/neotko_zbump.log) that logs
identical probe points from both the GUI and the engine side for direct comparison.
The catch
- It is gated for a reason. Some combinations here can produce bad extrusion. Read the G-code.
- Wall bump is Arachne only, disabled on Classic because a real print showed silent over-extrusion, and not wired for NeoArachne.
- Adjacent walls with very different bump can gap. Only the centreline moves; nothing adjusts line width to compensate. Known and open.
- The G-code preview does not draw the Z variation ZBump produces, the same known limitation as Neoweave and the NeoWave contact layer. The G-code is right even when the preview looks flat.
- The on-canvas handles can vanish in any mode of this gizmo when the print bed renders behind them, depending on camera angle. Long-standing, not root-caused yet, and the workaround is to orbit.