user: How do I use Uv Operators in Blender? Include parameters, examples, warnings and best practices.

assistant: # Uv Operators

bpy.ops.uv.align(*\**, *axis='ALIGN_AUTO'*, *position_mode='MEAN'*)
:   Aligns selected UV vertices on a line

    Parameters:
    :   - **axis** (enum in [`'ALIGN_S'`, `'ALIGN_T'`, `'ALIGN_U'`, `'ALIGN_AUTO'`, `'ALIGN_X'`, `'ALIGN_Y'`], (optional)) –

          Axis, Axis to align UV locations on

          - `ALIGN_S`
            Straighten – Align UV vertices along the line defined by the endpoints.
          - `ALIGN_T`
            Straighten X – Align UV vertices, moving them horizontally to the line defined by the endpoints.
          - `ALIGN_U`
            Straighten Y – Align UV vertices, moving them vertically to the line defined by the endpoints.
          - `ALIGN_AUTO`
            Align Auto – Automatically choose the direction on which there is most alignment already.
          - `ALIGN_X`
            Align Vertically – Align UV vertices on a vertical line.
          - `ALIGN_Y`
            Align Horizontally – Align UV vertices on a horizontal line.
        - **position_mode** (enum in [`'MEAN'`, `'MIN'`, `'MAX'`], (optional)) –

          Position Mode, Method of calculating the alignment position

          - `MEAN`
            Mean – Align UVs along the mean position.
          - `MIN`
            Minimum – Align UVs along the minimum position.
          - `MAX`
            Maximum – Align UVs along the maximum position.

bpy.ops.uv.align_rotation(*\**, *method='AUTO'*, *axis='X'*, *correct_aspect=False*)
:   Align the UV island’s rotation

    Parameters:
    :   - **method** (enum in [`'AUTO'`, `'EDGE'`, `'GEOMETRY'`], (optional)) –

          Method, Method to calculate rotation angle

          - `AUTO`
            Auto – Align from all edges.
          - `EDGE`
            Edge – Only selected edges.
          - `GEOMETRY`
            Geometry – Align to Geometry axis.
        - **axis** (enum in [`'X'`, `'Y'`, `'Z'`], (optional)) –

          Axis, Axis to align to

          - `X`
            X – X axis.
          - `Y`
            Y – Y axis.
          - `Z`
            Z – Z axis.
        - **correct_aspect** (*boolean**,* *(**optional**)*) – Correct Aspect, Take image aspect ratio into account

    File:
    :   [startup/bl_operators/uvcalc_transform.py:360](https://projects.blender.org/blender/blender/src/branch/main/scripts/startup/bl_operators/uvcalc_transform.py#L360)

bpy.ops.uv.arrange_islands(*\**, *initial_position='BOUNDING_BOX'*, *axis='Y'*, *align='MIN'*, *order='LARGE_TO_SMALL'*, *margin=0.05*)
:   Arrange selected UV islands on a line

    Parameters:
    :   - **initial_position** (enum in [`'BOUNDING_BOX'`, `'UV_GRID'`, `'ACTIVE_UDIM'`, `'CURSOR'`], (optional)) –

          Initial Position, Initial position to arrange islands from

          - `BOUNDING_BOX`
            Bounding Box – Initial alignment based on the islands bounding box.
          - `UV_GRID`
            UV Grid – Initial alignment based on UV Tile Grid.
          - `ACTIVE_UDIM`
            Active UDIM – Initial alignment based on Active UDIM.
          - `CURSOR`
            2D Cursor – Initial alignment based on 2D cursor.
        - **axis** (enum in [`'X'`, `'Y'`], (optional)) –

          Axis, Axis to arrange UV islands on

          - `X`
            X – Align UV islands along the X axis.
          - `Y`
            Y – Align UV islands along the Y axis.
        - **align** (enum in [`'MIN'`, `'MAX'`, `'CENTER'`, `'NONE'`], (optional)) –

          Align, Location to align islands on

          - `MIN`
            Min – Align the islands to the min of the island.
          - `MAX`
            Max – Align the islands to the left side of the island.
          - `CENTER`
            Center – Align the islands to the center of the largest island.
          - `NONE`
            None – Preserve island alignment.
        - **order** (enum in [`'LARGE_TO_SMALL'`, `'SMALL_TO_LARGE'`, `'Fixed'`], (optional)) –

          Order, Order of islands

          - `LARGE_TO_SMALL`
            Largest to Smallest – Sort islands from largest to smallest.
          - `SMALL_TO_LARGE`
            Smallest to Largest – Sort islands from smallest to largest.
          - `Fixed`
            Fixed – Preserve island order.
        - **margin** (*float in* *[**0**,* *1**]**,* *(**optional**)*) – Margin, Space between islands

bpy.ops.uv.average_islands_scale(*\**, *scale_uv=False*, *shear=False*)
:   Average the size of separate UV islands, based on their area in 3D space

    Parameters:
    :   - **scale_uv** (*boolean**,* *(**optional**)*) – Non-Uniform, Scale U and V independently
        - **shear** (*boolean**,* *(**optional**)*) – Shear, Reduce shear within islands

bpy.ops.uv.copy()
:   Copy selected UV vertices

bpy.ops.uv.copy_mirrored_faces(*\**, *direction='POSITIVE'*, *precision=3*)
:   Copy mirror UV coordinates on the X axis based on a mirrored mesh

    Parameters:
    :   - **direction** (enum in [`'POSITIVE'`, `'NEGATIVE'`], (optional)) – Axis Direction
        - **precision** (*int in* *[**1**,* *16**]**,* *(**optional**)*) – Precision, Tolerance for finding vertex duplicates

bpy.ops.uv.cube_project(*\**, *cube_size=1.0*, *correct_aspect=True*, *clip_to_bounds=False*, *scale_to_bounds=False*)
:   Project the UV vertices of the mesh over the six faces of a cube

    Parameters:
    :   - **cube_size** (*float in* *[**0**,* *inf**]**,* *(**optional**)*) – Cube Size, Size of the cube to project on
        - **correct_aspect** (*boolean**,* *(**optional**)*) – Correct Aspect, Map UVs taking aspect ratio of the image associated with the material into account
        - **clip_to_bounds** (*boolean**,* *(**optional**)*) – Clip to Bounds, Clip UV coordinates to bounds after unwrapping
        - **scale_to_bounds** (*boolean**,* *(**optional**)*) – Scale to Bounds, Scale UV coordinates to bounds after unwrapping

bpy.ops.uv.cursor_set(*\**, *location=(0.0, 0.0)*)
:   Set 2D cursor location

    Parameters:
    :   **location** ([`mathutils.Vector`](mathutils.html#mathutils.Vector "mathutils.Vector") of 2 items in [-inf, inf], (optional)) – Location, Cursor location in normalized (0.0 to 1.0) coordinates

bpy.ops.uv.custom_region_set(*\**, *xmin=0*, *xmax=0*, *ymin=0*, *ymax=0*, *wait_for_input=True*)
:   Set the boundaries of the user region

    Parameters:
    :   - **xmin** (*int in* *[**-inf**,* *inf**]**,* *(**optional**)*) – X Min
        - **xmax** (*int in* *[**-inf**,* *inf**]**,* *(**optional**)*) – X Max
        - **ymin** (*int in* *[**-inf**,* *inf**]**,* *(**optional**)*) – Y Min
        - **ymax** (*int in* *[**-inf**,* *inf**]**,* *(**optional**)*) – Y Max
        - **wait_for_input** (*boolean**,* *(**optional**)*) – Wait for Input

bpy.ops.uv.cylinder_project(*\**, *direction='VIEW_ON_EQUATOR'*, *align='POLAR_ZX'*, *pole='PINCH'*, *seam=False*, *radius=1.0*, *correct_aspect=True*, *clip_to_bounds=False*, *scale_to_bounds=False*)
:   Project the UV vertices of the mesh over the curved wall of a cylinder

    Parameters:
    :   - **direction** (enum in [`'VIEW_ON_EQUATOR'`, `'VIEW_ON_POLES'`, `'ALIGN_TO_OBJECT'`], (optional)) –

          Direction, Direction of the sphere or cylinder

          - `VIEW_ON_EQUATOR`
            View on Equator – 3D view is on the equator.
          - `VIEW_ON_POLES`
            View on Poles – 3D view is on the poles.
          - `ALIGN_TO_OBJECT`
            Align to Object – Align according to object transform.
        - **align** (enum in [`'POLAR_ZX'`, `'POLAR_ZY'`], (optional)) –

          Align, How to determine rotation around the pole

          - `POLAR_ZX`
            Polar ZX – Polar 0 is X.
          - `POLAR_ZY`
            Polar ZY – Polar 0 is Y.
        - **pole** (enum in [`'PINCH'`, `'FAN'`], (optional)) –

          Pole, How to handle faces at the poles

          - `PINCH`
            Pinch – UVs are pinched at the poles.
          - `FAN`
            Fan – UVs are fanned at the poles.
        - **seam** (*boolean**,* *(**optional**)*) – Preserve Seams, Separate projections by islands isolated by seams
        - **radius** (*float in* *[**0**,* *inf**]**,* *(**optional**)*) – Radius, Radius of the sphere or cylinder
        - **correct_aspect** (*boolean**,* *(**optional**)*) – Correct Aspect, Map UVs taking aspect ratio of the image associated with the material into account
        - **clip_to_bounds** (*boolean**,* *(**optional**)*) – Clip to Bounds, Clip UV coordinates to bounds after unwrapping
        - **scale_to_bounds** (*boolean**,* *(**optional**)*) – Scale to Bounds, Scale UV coordinates to bounds after unwrapping

bpy.ops.uv.export_layout(*\**, *filepath=''*, *export_all=False*, *export_tiles='NONE'*, *modified=False*, *mode='PNG'*, *size=(1024, 1024)*, *opacity=0.25*, *check_existing=True*)
:   Export UV layout to file

    Parameters:
    :   - **filepath** (*string**,* *(**optional**,* *never None**)*) – filepath
        - **export_all** (*boolean**,* *(**optional**)*) – All UVs, Export all UVs in this mesh (not just visible ones)
        - **export_tiles** (enum in [`'NONE'`, `'UDIM'`, `'UV'`], (optional)) –

          Export Tiles, Choose whether to export only the [0, 1] range, or all UV tiles

          - `NONE`
            None – Export only UVs in the [0, 1] range.
          - `UDIM`
            UDIM – Export tiles in the UDIM numbering scheme: 1001 + u_tile + 10\*v_tile.
          - `UV`
            UVTILE – Export tiles in the UVTILE numbering scheme: u(u_tile + 1)_v(v_tile + 1).
        - **modified** (*boolean**,* *(**optional**)*) – Modified, Exports UVs from the modified mesh
        - **mode** (enum in [`'SVG'`, `'EPS'`, `'PNG'`], (optional)) –

          Format, File format to export the UV layout to

          - `SVG`
            Scalable Vector Graphic (.svg) – Export the UV layout to a vector SVG file.
          - `EPS`
            Encapsulated PostScript (.eps) – Export the UV layout to a vector EPS file.
          - `PNG`
            PNG Image (.png) – Export the UV layout to a bitmap image.
        - **size** (*int array* *of* *2 items in* *[**8**,* *32768**]**,* *(**optional**)*) – Size, Dimensions of the exported file
        - **opacity** (*float in* *[**0**,* *1**]**,* *(**optional**)*) – Fill Opacity, Set amount of opacity for exported UV layout
        - **check_existing** (*boolean**,* *(**optional**)*) – check_existing

    File:
    :   [addons_core/io_mesh_uv_layout/__init__.py:139](https://projects.blender.org/blender/blender/src/branch/main/scripts/addons_core/io_mesh_uv_layout/__init__.py#L139)

bpy.ops.uv.follow_active_quads(*\**, *mode='LENGTH_AVERAGE'*)
:   Follow UVs from active quads along continuous face loops

    Parameters:
    :   **mode** (enum in [`'EVEN'`, `'LENGTH'`, `'LENGTH_AVERAGE'`], (optional)) –

        Edge Length Mode, Method to space UV edge loops

        - `EVEN`
          Even – Space all UVs evenly.
        - `LENGTH`
          Length – Average space UVs edge length of each loop.
        - `LENGTH_AVERAGE`
          Length Average – Average space UVs edge length of each loop.

    File:
    :   [startup/bl_operators/uvcalc_follow_active.py:302](https://projects.blender.org/blender/blender/src/branch/main/scripts/startup/bl_operators/uvcalc_follow_active.py#L302)

bpy.ops.uv.hide(*\**, *unselected=False*)
:   Hide (un)selected UV vertices

    Parameters:
    :   **unselected** (*boolean**,* *(**optional**)*) – Unselected, Hide unselected rather than selected

bpy.ops.uv.lightmap_pack(*\**, *PREF_CONTEXT='SEL_FACES'*, *PREF_PACK_IN_ONE=True*, *PREF_NEW_UVLAYER=False*, *PREF_BOX_DIV=12*, *PREF_MARGIN_DIV=0.1*)
:   Pack each face’s UVs into the UV bounds

    Parameters:
    :   - **PREF_CONTEXT** (enum in [`'SEL_FACES'`, `'ALL_FACES'`], (optional)) –

          Selection

          - `SEL_FACES`
            Selected Faces – Space all UVs evenly.
          - `ALL_FACES`
            All Faces – Average space UVs edge length of each loop.
        - **PREF_PACK_IN_ONE** (*boolean**,* *(**optional**)*) – Share Texture Space, Objects share texture space, map all objects into a single UV map
        - **PREF_NEW_UVLAYER** (*boolean**,* *(**optional**)*) – New UV Map, Create a new UV map for every mesh packed
        - **PREF_BOX_DIV** (*int in* *[**1**,* *48**]**,* *(**optional**)*) – Pack Quality, Quality of the packing. Higher values will be slower but waste less space
        - **PREF_MARGIN_DIV** (*float in* *[**0.001**,* *1**]**,* *(**optional**)*) – Margin, Size of the margin as a division of the UV

    File:
    :   [startup/bl_operators/uvcalc_lightmap.py:662](https://projects.blender.org/blender/blender/src/branch/main/scripts/startup/bl_operators/uvcalc_lightmap.py#L662)

bpy.ops.uv.mark_seam(*\**, *clear=False*)
:   Mark selected UV edges as seams

    Parameters:
    :   **clear** (*boolean**,* *(**optional**)*) – Clear Seams, Clear instead of marking seams

bpy.ops.uv.minimize_stretch(*\**, *fill_holes=True*, *blend=0.0*, *iterations=0*)
:   Reduce UV stretching by relaxing angles

    Parameters:
    :   - **fill_holes** (*boolean**,* *(**optional**)*) – Fill Holes, Virtually fill holes in mesh before unwrapping, to better avoid overlaps and preserve symmetry
        - **blend** (*float in* *[**0**,* *1**]**,* *(**optional**)*) – Blend, Blend factor between stretch minimized and original
        - **iterations** (*int in* *[**0**,* *inf**]**,* *(**optional**)*) – Iterations, Number of iterations to run, 0 is unlimited when run interactively

bpy.ops.uv.move_on_axis(*\**, *type='UDIM'*, *axis='X'*, *distance=1*)
:   Move UVs on an axis

    Parameters:
    :   - **type** (enum in [`'DYNAMIC'`, `'PIXEL'`, `'UDIM'`], (optional)) –

          Type, Move Type

          - `DYNAMIC`
            Dynamic – Move by dynamic grid.
          - `PIXEL`
            Pixel – Move by pixel.
          - `UDIM`
            UDIM – Move by UDIM.
        - **axis** (enum in [`'X'`, `'Y'`], (optional)) –

          Axis, Axis to move UVs on

          - `X`
            X axis – Move vertices on the X axis.
          - `Y`
            Y axis – Move vertices on the Y axis.
        - **distance** (*int in* *[**-inf**,* *inf**]**,* *(**optional**)*) – Distance, Distance to move UVs

bpy.ops.uv.pack_islands(*\**, *udim_source='CLOSEST_UDIM'*, *rotate=True*, *rotate_method='ANY'*, *scale=True*, *merge_overlap=False*, *margin_method='SCALED'*, *margin=0.001*, *pin=False*, *pin_method='LOCKED'*, *shape_method='CONCAVE'*)
:   Transform all islands so that they fill up the UV/UDIM space as much as possible

    Parameters:
    :   - **udim_source** (enum in [`'CLOSEST_UDIM'`, `'ACTIVE_UDIM'`, `'ORIGINAL_AABB'`, `'CUSTOM_REGION'`], (optional)) –

          Pack to

          - `CLOSEST_UDIM`
            Closest UDIM – Pack islands to closest UDIM.
          - `ACTIVE_UDIM`
            Active UDIM – Pack islands to active UDIM image tile or UDIM grid tile where 2D cursor is located.
          - `ORIGINAL_AABB`
            Original bounding box – Pack to starting bounding box of islands.
          - `CUSTOM_REGION`
            Custom Region – Pack islands to custom region.
        - **rotate** (*boolean**,* *(**optional**)*) – Rotate, Rotate islands to improve layout
        - **rotate_method** (enum in [`'ANY'`, `'CARDINAL'`, `'AXIS_ALIGNED'`, `'AXIS_ALIGNED_X'`, `'AXIS_ALIGNED_Y'`], (optional)) –

          Rotation Method

          - `ANY`
            Any – Any angle is allowed for rotation.
          - `CARDINAL`
            Cardinal – Only 90 degree rotations are allowed.
          - `AXIS_ALIGNED`
            Axis-aligned – Rotated to a minimal rectangle, either vertical or horizontal.
          - `AXIS_ALIGNED_X`
            Axis-aligned (Horizontal) – Rotate islands to be aligned horizontally.
          - `AXIS_ALIGNED_Y`
            Axis-aligned (Vertical) – Rotate islands to be aligned vertically.
        - **scale** (*boolean**,* *(**optional**)*) – Scale, Scale islands to fill unit square
        - **merge_overlap** (*boolean**,* *(**optional**)*) – Merge Overlapping, Overlapping islands stick together
        - **margin_method** (enum in [`'SCALED'`, `'ADD'`, `'FRACTION'`], (optional)) –

          Margin Method

          - `SCALED`
            Scaled – Use scale of existing UVs to multiply margin.
          - `ADD`
            Add – Just add the margin, ignoring any UV scale.
          - `FRACTION`
            Fraction – Specify a precise fraction of final UV output.
        - **margin** (*float in* *[**0**,* *1**]**,* *(**optional**)*) – Margin, Space between islands
        - **pin** (*boolean**,* *(**optional**)*) – Lock Pinned Islands, Constrain islands containing any pinned UV’s
        - **pin_method** (enum in [`'SCALE'`, `'ROTATION'`, `'ROTATION_SCALE'`, `'LOCKED'`], (optional)) –

          Pin Method

          - `SCALE`
            Scale – Pinned islands won’t rescale.
          - `ROTATION`
            Rotation – Pinned islands won’t rotate.
          - `ROTATION_SCALE`
            Rotation and Scale – Pinned islands will translate only.
          - `LOCKED`
            All – Pinned islands are locked in place.
        - **shape_method** (enum in [`'CONCAVE'`, `'CONVEX'`, `'AABB'`], (optional)) –

          Shape Method

          - `CONCAVE`
            Exact Shape (Concave) – Uses exact geometry.
          - `CONVEX`
            Boundary Shape (Convex) – Uses convex hull.
          - `AABB`
            Bounding Box – Uses bounding boxes.

bpy.ops.uv.paste()
:   Paste selected UV vertices

bpy.ops.uv.pin(*\**, *clear=False*, *invert=False*)
:   Set/clear selected UV vertices as anchored between multiple unwrap operations

    Parameters:
    :   - **clear** (*boolean**,* *(**optional**)*) – Clear, Clear pinning for the selection instead of setting it
        - **invert** (*boolean**,* *(**optional**)*) – Invert, Invert pinning for the selection instead of setting it

bpy.ops.uv.project_from_view(*\**, *orthographic=False*, *camera_bounds=True*, *correct_aspect=True*, *clip_to_bounds=False*, *