Shading

Shading controls how vertex and face normals are calculated and applied to the final mesh. Proper shading reduces visible faceting. It enables the use of lower tessellation (quality) of the mesh or path.

• shading.mode (string):
  • Type: string
  • Enum: {“auto”,“flat”,“smooth”}
  • Default: “auto”
  • “auto” — The processor chooses flat vs smooth per-edge based on face dihedral (angle between adjacent normal vectors). Recommended default for general models.
  • “flat” — Compute flat normals per face (no smoothing). Use for faceted, mechanical or intentionally sharp geometry. This is the default parameter because it always produces a mathematically correct mesh.
  • “smooth” — Compute smoothed vertex normal across faces (full smoothing). Use when you want visually continuous curvature. It is not recommended to use this mode, unless you have a specific purpose in mind.

• shading.angle (number):
  • Type: number
  • Unit: degrees
  • Default: 30
  • Angular threshold used only when mode is “auto” (or when smoothing is computed): edges with dihedral angle less than shading.angle are smoothed; edges with larger angles remain hard. Typical range: 10–60° up to 90°.

User notes:

• shading.mode = “auto” inspects the tessellated geometry: if faces are nearly coplanar (dihedral < angle) they are smoothed, otherwise kept flat. The result depends on both shading.angle and the tessellation produced by quality.
• Low tessellation (low quality) can make curved regions still appear faceted even with mode=“auto”. Experiment with angle to reduce faceting before increasing the quality or switching to another type of shading.

Example configuration of shading (ONLY GLOBAL):

"intersection": "VERTICAL",
"quality": 15,
"uv": {
	"patchSize": 150,
	"uvOrigin": "ORIGIN",
	"uOffset": 0,
	"vOffset": 0,
	"uvType": "AUTO"
},
"shading": {
	"mode": "AUTO",
	"angle": 35
}

Practical guidance for the example:

• With quality = 15 and shading.angle = 30, mode=“auto” will smooth edges whose dihedral angle is < 30°. For gently curved profiles this gives a smooth visual; for sharp features edges will remain hard.
• If you observe visible faceting on curved areas (common at low quality), play with angle (for example to 30 or 35) before increasing the quality.
• UV settings do not change normals, but low-quality tessellation may impact UV distortion; when increasing quality, re-check UV layout and seam placement for stability before releasing the project.

Recommended quick checklist:

1. Start with **mode="auto"** and **angle=25-35** for general use.
2. If curved surfaces still show faceting, increase **quality**.
3. For mechanical/sharp geometries use **mode="flat"**.
4. For organic/continuous curvature like a sphere use **mode="smooth"** and moderate-to-high **quality**.

clearpage

[] *Figure a: mode=“auto”, angle=35, quality=15 — lower tessellation, some faceting.*

[] *Figure b: mode=“auto”, angle=35, quality=15 — smoother result.*

*Figure: Shading examples: auto mode at low vs high tessellation.*