====== Shading ======

=== Parameters ("shading.mode", "shading.angle") ===

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):**
<code json>
"intersection": "VERTICAL",
"quality": 15,
"uv": {
	"patchSize": 150,
	"uvOrigin": "ORIGIN",
	"uOffset": 0,
	"vOffset": 0,
	"uvType": "AUTO"
},
"shading": {
	"mode": "AUTO",
	"angle": 35
}
</code>

**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}}
=== Visual examples ===

[]
*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.*