user: Give a detailed overview of Normals: syntax, arguments, return values, common patterns.

assistant: In geometry, a normal is a direction or line that is perpendicular to something,
typically a triangle or surface but can also be relative to a line,
a tangent line for a point on a curve, or a tangent plane for a point on a surface.

Normals help to determine the shading of the mesh among other things.

[[image reference removed]](../../_images/modeling_meshes_structure_viewport.png)

A visualization of the face normals of a torus.

In the figure above, each blue line represents the normal for a face on the torus.
The lines are each perpendicular to the face on which they lie.
The visualization can be activated, in Edit Mode,
in the [Mesh Display Viewport Overlays panel](../../editors/3dview/display/overlays.html#mesh-display-normals).

### Shading

Surface normals play a fundamental role in determining how light interacts with 3D objects
and thus greatly influence the shading of those objects. Normals can be shaded smooth or flat.

When a mesh uses flat shading, the faces are rendered and displayed faces uniformly.
This is usually desirable for objects with flat surfaces such as a cube or pyramid.

When a mesh uses smooth shading, the normals are interpolated across the vertices of a polygonal mesh,
smooth transitions between adjacent polygons can be achieved, resulting in a more realistic appearance.

By default face normals have flat shading however, this can be adjusted either for the whole object or per face.

To adjust the shading of the whole object, use:

- [Shade Smooth](../../scene_layout/object/editing/shading.html#bpy-ops-object-shade-smooth) – To mark the whole object as smooth.
- [Shade Auto Smooth](../../scene_layout/object/editing/shading.html#bpy-ops-object-shade-auto-smooth) – To mark portions of the object as smooth.

To revert to flat shading, use [Shade Flat](../../scene_layout/object/editing/shading.html#bpy-ops-object-shade-flat).

The shading of objects can also be adjusted per face, edge, or vertex.

### Custom Split Normals

Custom split normals are a way to tweak/fake shading by pointing normals towards
other directions than the default, auto-computed ones. It is mostly used in game development,
where it helps counterbalance some issues generated by low-poly objects
(the most common examples are low-poly trees, bushes, grass, etc. and the ‘rounded’ corners).

Blender supports custom normals on a ‘smooth fan’ base, defined as a set of neighbor face corners
sharing the same vertex and ‘linked’ by smooth edges. This means you can have normals per face corners,
per a set of neighbor face corners, or per vertex.

Custom split normal data is stored as the `custom_normal`
[Attribute](../geometry_nodes/attributes_reference.html) on the face corner [Domain](../geometry_nodes/attributes_reference.html#attribute-domains).

#### Free Normals

Free normals are a type of custom normal stored directly as direction vectors in object space.
Unlike traditional custom normals, which are defined relative to the surrounding geometry
(known as tangent or corner fan space),
free normals are independent of mesh topology and do not rely on smooth groups or edge connectivity.

Because they are simple vectors, free normals are:

- Efficient: Fast to evaluate, significantly improving viewport performance compared to tangent space normals.
- Lightweight: Require less memory, especially beneficial for dense or heavily instanced meshes.
- Static: They do not automatically update when the mesh is deformed (e.g. through modifiers or animations),
  so they are best suited for static geometry or cases where performance is critical.

Free normals can be assigned using the [Set Mesh Normal Node](../geometry_nodes/mesh/write/set_mesh_normal.html) in Free mode,
and stored on the vertex, face, or face corner domain depending on the desired granularity.

#### Editing Custom Split Normals

There are a number of tools for editing custom split normals.
The custom normal mesh edit tools can affect all normals (the default), or only selected ones.
To select a custom normal associated with a particular vertex and face:

- Make the element selection mode both Vertex and Face (use `Shift`-`LMB` to enable the second one).
- Select one or more vertices, then select a face.
  This can be repeated to select more vertices and a different face and so on.
  It is easiest to see the effect of these tools if you turn on
  the Edit Mode Overlays option *Display vertex-per-face normals as lines*.

### Importing Custom Split Normals

Some tools, particularly those used in CAD, tend to generate irregular geometry
when tessellating their objects into meshes (very thin and long triangles, etc.).
Auto-computed normals on such geometry often gives bad artifacts,
so it is important to be able to import and use the normals as generated by the CAD tool itself.