user: Describe Expand Mask by Topology from the Blender manual or Python API, including usage steps and snippets.

assistant: Expands a mask from the active vertex.

### Usage

Mask from A to B
:   Start the operator and expand a mask from an origin to your mouse cursor distance.
    Then confirm with `LMB` or `Return`

    By default the expansion will use a *Geodesic* falloff `1`
    to create perfectly accurate distances along the surfaces.
    Use other falloff types via `2`, `3` & `4` to expand via
    triangles, whole faces or scene distances instead.

    [image reference removed]

    The typical result when using the *Diagonals* falloff to expand along the quads of the face.

    Start Expand while pointing at an open boundary to expand from the entire boundary loop.
    This will always use the *Topology* falloff mode.

Fill Connected Meshes
:   Move your cursor outside of the boundaries of the mesh to mask the entire connected mesh.
    This can be done repeatedly to quickly mask separate meshes.

Fill Face Sets
:   Hold `Ctrl` to snap to face sets under your cursor and fill them.
    Any face set that was already covered in the expansion will be filled as well.

Automatically Set Transform Pivot
:   While using any Transform tool, the pivot point
    will automatically snap the border of an Expand result.
    This way areas (Like limbs) can be masked and then immediately rotated or otherwise transformed.

    [image reference removed]

Pattern Creation
:   The different falloff types can be used for circular, triangular and square patterns.
    More loops can also be added/removed via `W` & `Q` to repeat the pattern across the mesh.

    [image reference removed]

    An example of using expand with mirror options,
    loops and a recursion to create wood carving patterns.

    Linear gradients `G` or brush falloff gradients `B` will help to add slanted surfaces
    to the patterns.

    A “Recursions” with `R` or `Alt`-`R` will start
    a new expansion along the border of the current expansion.
    Doing this multiple times, can help for increasingly random patterns
    or advanced pattern creation.

    [image reference removed]

    An example of using loops and gradients with multiple expanded masks.

    Use the [Mesh Filter](../tools/mesh_filter.xhtml)
    to deform the geometry and the [Color Filter](../tools/color_filter.xhtml)
    to add colors, to apply the patterns on the sculpt.

Expanding Textures
:   Textures can be used to affect the shape and gradients of the expanded mask.
    This feature can be combined with loops and recursion to create unique results.

    To use a texture, you need to assign it to your currently active brush in the
    [Texture](../../brush/texture.xhtml) Brush Settings. The texture can be edited/created
    in the [Texture Properties](../../../render/materials/legacy_textures/index.xhtml).

    Use `Y` and `T` to increase or decrease the affect the texture has on the edge of the mask.

### Controls

Invert:
:   `F`
    Flips between expanding a positive mask (value of one) or a negative mask (value of zero).
    In the case of face sets, this option flips between including areas inside the masked area
    or areas outside the masked area.
    .. needs visual technical examples for both

Toggle Preserve State:
:   `E`
    Accumulate the new mask on top of the previous one or replace it.
    For Face Sets, this will toggle between creating Face Sets boundaries
    or replacing the existing Face Sets.

Move Origin:
:   `Spacebar`
    Moves the initial vertex used for calculating the falloff.
    .. needs visual technical example

Geodesic Falloff:
:   `1`
    Uses a falloff based on the [Geodesic](../../../glossary/index.xhtml#term-Geodesic) distances from the edge boundary to the active vertex.

Topology Falloff:
:   `2`
    Uses a falloff based on a flood fill using edges.

Diagonals Falloff:
:   `3`
    Uses a falloff based on a flood fill using polygon diagonals and edges.

Spherical Falloff:
:   `4`
    Uses a falloff based on the Euclidean distances from the edge boundary to the active vertex.
    .. needs visual technical examples

Toggle Gradient:
:   `G`
    Enables linear gradient of values from the origin to the current active vertex.

Toggle Brush Gradient:
:   `B`
    Similar to linear gradient but uses the current brush [Falloff](../../brush/falloff.xhtml)
    to define the shape of the falloff.
    .. needs visual technical examples

Geodesic Recursive Step:
:   `R`
    Start a new expansion with a [Geodesic](../../../glossary/index.xhtml#term-Geodesic) falloff from the boundary of the current falloff.

Topology Recursive Step:
:   `Alt`-`R`
    Start a new expansion with a topology falloff from the boundary of the current falloff.
    .. needs visual technical examples

Snap Expanded to Face Sets:
:   `Ctrl`
    Isolates the expanded region to the boundary of the face set under the cursor.

Loop Count Increase:
:   `W`
    Increase the number of loops or iterations the operator is run;
    using four loops will split the mask into four parts.

Loop Count Decrease:
:   `Q`
    Decrease the number of loops or iterations the operator is run;
    using four loops will split the mask into four parts.
    .. needs visual technical examples

Texture Distortion Increase:
:   `Y`
    Increases the falloff distance when using a texture to distort the mask shape.

Texture Distortion Decrease:
:   `T`
    Decreases the falloff distance when using a texture to distort the mask shape.
    ..needs visual technical examples