Sculpt Operators

bpy.ops.sculpt.brush_stroke(stroke=None, mode='NORMAL', ignore_background_click=False)

Sculpt a stroke into the geometry

Parameters

• stroke (bpy_prop_collection of OperatorStrokeElement, (optional)) – Stroke

• mode (enum in ['NORMAL', 'INVERT', 'SMOOTH'], (optional)) –

  Stroke Mode, Action taken when a paint stroke is made

  • NORMAL Regular – Apply brush normally.

  • INVERT Invert – Invert action of brush for duration of stroke.

  • SMOOTH Smooth – Switch brush to smooth mode for duration of stroke.

• ignore_background_click (boolean, (optional)) – Ignore Background Click, Clicks on the background do not start the stroke

bpy.ops.sculpt.cloth_filter(area_normal_radius=0.25, strength=1.0, type='GRAVITY', force_axis={'X', 'Y', 'Z'}, orientation='LOCAL', cloth_mass=1.0, cloth_damping=0.0, use_face_sets=False, use_collisions=False)

Applies a cloth simulation deformation to the entire mesh

Parameters

• area_normal_radius (float in [0.001, 5], (optional)) – Normal Radius, Radius used for calculating area normal on initial click,in percentage of brush radius

• strength (float in [-10, 10], (optional)) – Strength, Filter strength

• type (enum in ['GRAVITY', 'INFLATE', 'EXPAND', 'PINCH', 'SCALE'], (optional)) –

  Filter Type, Operation that is going to be applied to the mesh

  • GRAVITY Gravity – Applies gravity to the simulation.

  • INFLATE Inflate – Inflates the cloth.

  • EXPAND Expand – Expands the cloth’s dimensions.

  • PINCH Pinch – Pulls the cloth to the cursor’s start position.

  • SCALE Scale – Scales the mesh as a soft body using the origin of the object as scale.

• force_axis (enum set in {'X', 'Y', 'Z'}, (optional)) –

  Force Axis, Apply the force in the selected axis

  • X X – Apply force in the X axis.

  • Y Y – Apply force in the Y axis.

  • Z Z – Apply force in the Z axis.

• orientation (enum in ['LOCAL', 'WORLD', 'VIEW'], (optional)) –

  Orientation, Orientation of the axis to limit the filter force

  • LOCAL Local – Use the local axis to limit the force and set the gravity direction.

  • WORLD World – Use the global axis to limit the force and set the gravity direction.

  • VIEW View – Use the view axis to limit the force and set the gravity direction.

• cloth_mass (float in [0, 2], (optional)) – Cloth Mass, Mass of each simulation particle

• cloth_damping (float in [0, 1], (optional)) – Cloth Damping, How much the applied forces are propagated through the cloth

• use_face_sets (boolean, (optional)) – Use Face Sets, Apply the filter only to the Face Set under the cursor

• use_collisions (boolean, (optional)) – Use Collisions, Collide with other collider objects in the scene

bpy.ops.sculpt.color_filter(area_normal_radius=0.25, strength=1.0, type='HUE', fill_color=(0.0, 0.0, 0.0))

Applies a filter to modify the active color attribute

Parameters

• area_normal_radius (float in [0.001, 5], (optional)) – Normal Radius, Radius used for calculating area normal on initial click,in percentage of brush radius

• strength (float in [-10, 10], (optional)) – Strength, Filter strength

• type (enum in ['FILL', 'HUE', 'SATURATION', 'VALUE', 'BRIGHTNESS', 'CONTRAST', 'SMOOTH', 'RED', 'GREEN', 'BLUE'], (optional)) –

  Filter Type

  • FILL Fill – Fill with a specific color.

  • HUE Hue – Change hue.

  • SATURATION Saturation – Change saturation.

  • VALUE Value – Change value.

  • BRIGHTNESS Brightness – Change brightness.

  • CONTRAST Contrast – Change contrast.

  • SMOOTH Smooth – Smooth colors.

  • RED Red – Change red channel.

  • GREEN Green – Change green channel.

  • BLUE Blue – Change blue channel.

• fill_color (float array of 3 items in [0, inf], (optional)) – Fill Color

bpy.ops.sculpt.detail_flood_fill()

Flood fill the mesh with the selected detail setting

bpy.ops.sculpt.dynamic_topology_toggle()

Dynamic topology alters the mesh topology while sculpting

bpy.ops.sculpt.dyntopo_detail_size_edit()

Modify the detail size of dyntopo interactively

bpy.ops.sculpt.expand(target='MASK', falloff_type='GEODESIC', invert=False, use_mask_preserve=False, use_falloff_gradient=False, use_modify_active=False, use_reposition_pivot=True, max_geodesic_move_preview=10000)

Generic sculpt expand operator

Parameters

• target (enum in ['MASK', 'FACE_SETS', 'COLOR'], (optional)) – Data Target, Data that is going to be modified in the expand operation

• falloff_type (enum in ['GEODESIC', 'TOPOLOGY', 'TOPOLOGY_DIAGONALS', 'NORMALS', 'SPHERICAL', 'BOUNDARY_TOPOLOGY', 'BOUNDARY_FACE_SET', 'ACTIVE_FACE_SET'], (optional)) – Falloff Type, Initial falloff of the expand operation

• invert (boolean, (optional)) – Invert, Invert the expand active elements

• use_mask_preserve (boolean, (optional)) – Preserve Previous, Preserve the previous state of the target data

• use_falloff_gradient (boolean, (optional)) – Falloff Gradient, Expand Using a linear falloff

• use_modify_active (boolean, (optional)) – Modify Active, Modify the active Face Set instead of creating a new one

• use_reposition_pivot (boolean, (optional)) – Reposition Pivot, Reposition the sculpt transform pivot to the boundary of the expand active area

• max_geodesic_move_preview (int in [0, inf], (optional)) – Max Vertex Count for Geodesic Move Preview, Maximum number of vertices in the mesh for using geodesic falloff when moving the origin of expand. If the total number of vertices is greater than this value, the falloff will be set to spherical when moving

bpy.ops.sculpt.face_set_box_gesture(xmin=0, xmax=0, ymin=0, ymax=0, wait_for_input=True, use_front_faces_only=False, use_limit_to_segment=False)

Add face set within the box as you move the brush

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

• use_front_faces_only (boolean, (optional)) – Front Faces Only, Affect only faces facing towards the view

• use_limit_to_segment (boolean, (optional)) – Limit to Segment, Apply the gesture action only to the area that is contained within the segment without extending its effect to the entire line

bpy.ops.sculpt.face_set_change_visibility(mode='TOGGLE')

Change the visibility of the Face Sets of the sculpt

Parameters

mode (enum in ['TOGGLE', 'SHOW_ACTIVE', 'HIDE_ACTIVE', 'INVERT'], (optional)) –

Mode

• TOGGLE Toggle Visibility – Hide all Face Sets except for the active one.

• SHOW_ACTIVE Show Active Face Set – Show Active Face Set.

• HIDE_ACTIVE Hide Active Face Sets – Hide Active Face Sets.

• INVERT Invert Face Set Visibility – Invert Face Set Visibility.

bpy.ops.sculpt.face_set_edit(mode='GROW', modify_hidden=True)

Edits the current active Face Set

Parameters

• mode (enum in ['GROW', 'SHRINK', 'DELETE_GEOMETRY', 'FAIR_POSITIONS', 'FAIR_TANGENCY'], (optional)) –

  Mode

  • GROW Grow Face Set – Grows the Face Sets boundary by one face based on mesh topology.

  • SHRINK Shrink Face Set – Shrinks the Face Sets boundary by one face based on mesh topology.

  • DELETE_GEOMETRY Delete Geometry – Deletes the faces that are assigned to the Face Set.

  • FAIR_POSITIONS Fair Positions – Creates a smooth as possible geometry patch from the Face Set minimizing changes in vertex positions.

  • FAIR_TANGENCY Fair Tangency – Creates a smooth as possible geometry patch from the Face Set minimizing changes in vertex tangents.

• modify_hidden (boolean, (optional)) – Modify Hidden, Apply the edit operation to hidden Face Sets

bpy.ops.sculpt.face_set_lasso_gesture(path=None, use_front_faces_only=False, use_limit_to_segment=False)

Add face set within the lasso as you move the brush

Parameters

• path (bpy_prop_collection of OperatorMousePath, (optional)) – Path

• use_front_faces_only (boolean, (optional)) – Front Faces Only, Affect only faces facing towards the view

• use_limit_to_segment (boolean, (optional)) – Limit to Segment, Apply the gesture action only to the area that is contained within the segment without extending its effect to the entire line

bpy.ops.sculpt.face_sets_create(mode='MASKED')

Create a new Face Set

Parameters

mode (enum in ['MASKED', 'VISIBLE', 'ALL', 'SELECTION'], (optional)) –

Mode

• MASKED Face Set from Masked – Create a new Face Set from the masked faces.

• VISIBLE Face Set from Visible – Create a new Face Set from the visible vertices.

• ALL Face Set Full Mesh – Create an unique Face Set with all faces in the sculpt.

• SELECTION Face Set from Edit Mode Selection – Create an Face Set corresponding to the Edit Mode face selection.

bpy.ops.sculpt.face_sets_init(mode='LOOSE_PARTS', threshold=0.5)

Initializes all Face Sets in the mesh

Parameters

• mode (enum in ['LOOSE_PARTS', 'MATERIALS', 'NORMALS', 'UV_SEAMS', 'CREASES', 'BEVEL_WEIGHT', 'SHARP_EDGES', 'FACE_MAPS', 'FACE_SET_BOUNDARIES'], (optional)) –

  Mode

  • LOOSE_PARTS Face Sets from Loose Parts – Create a Face Set per loose part in the mesh.

  • MATERIALS Face Sets from Material Slots – Create a Face Set per Material Slot.

  • NORMALS Face Sets from Mesh Normals – Create Face Sets for Faces that have similar normal.

  • UV_SEAMS Face Sets from UV Seams – Create Face Sets using UV Seams as boundaries.

  • CREASES Face Sets from Edge Creases – Create Face Sets using Edge Creases as boundaries.

  • BEVEL_WEIGHT Face Sets from Bevel Weight – Create Face Sets using Bevel Weights as boundaries.

  • SHARP_EDGES Face Sets from Sharp Edges – Create Face Sets using Sharp Edges as boundaries.

  • FACE_MAPS Face Sets from Face Maps – Create a Face Set per Face Map.

  • FACE_SET_BOUNDARIES Face Sets from Face Set Boundaries – Create a Face Set per isolated Face Set.

• threshold (float in [0, 1], (optional)) – Threshold, Minimum value to consider a certain attribute a boundary when creating the Face Sets

bpy.ops.sculpt.face_sets_randomize_colors()

Generates a new set of random colors to render the Face Sets in the viewport

bpy.ops.sculpt.mask_by_color(contiguous=False, invert=False, preserve_previous_mask=False, threshold=0.35)

Creates a mask based on the active color attribute

Parameters

• contiguous (boolean, (optional)) – Contiguous, Mask only contiguous color areas

• invert (boolean, (optional)) – Invert, Invert the generated mask

• preserve_previous_mask (boolean, (optional)) – Preserve Previous Mask, Preserve the previous mask and add or subtract the new one generated by the colors

• threshold (float in [0, 1], (optional)) – Threshold, How much changes in color affect the mask generation

bpy.ops.sculpt.mask_expand(invert=True, use_cursor=True, update_pivot=True, smooth_iterations=2, mask_speed=5, use_normals=True, keep_previous_mask=False, edge_sensitivity=300, create_face_set=False)

Expands a mask from the initial active vertex under the cursor

Parameters

• invert (boolean, (optional)) – Invert, Invert the new mask

• use_cursor (boolean, (optional)) – Use Cursor, Expand the mask to the cursor position

• update_pivot (boolean, (optional)) – Update Pivot Position, Set the pivot position to the mask border after creating the mask

• smooth_iterations (int in [0, 10], (optional)) – Smooth Iterations

• mask_speed (int in [1, 10], (optional)) – Mask Speed

• use_normals (boolean, (optional)) – Use Normals, Generate the mask using the normals and curvature of the model

• keep_previous_mask (boolean, (optional)) – Keep Previous Mask, Generate the new mask on top of the current one

• edge_sensitivity (int in [0, 2000], (optional)) – Edge Detection Sensitivity, Sensitivity for expanding the mask across sculpted sharp edges when using normals to generate the mask

• create_face_set (boolean, (optional)) – Expand Face Mask, Expand a new Face Mask instead of the sculpt mask

bpy.ops.sculpt.mask_filter(filter_type='SMOOTH', iterations=1, auto_iteration_count=True)

Applies a filter to modify the current mask

Parameters

• filter_type (enum in ['SMOOTH', 'SHARPEN', 'GROW', 'SHRINK', 'CONTRAST_INCREASE', 'CONTRAST_DECREASE'], (optional)) –

  Type, Filter that is going to be applied to the mask

  • SMOOTH Smooth Mask – Smooth mask.

  • SHARPEN Sharpen Mask – Sharpen mask.

  • GROW Grow Mask – Grow mask.

  • SHRINK Shrink Mask – Shrink mask.

  • CONTRAST_INCREASE Increase Contrast – Increase the contrast of the paint mask.

  • CONTRAST_DECREASE Decrease Contrast – Decrease the contrast of the paint mask.

• iterations (int in [1, 100], (optional)) – Iterations, Number of times that the filter is going to be applied

• auto_iteration_count (boolean, (optional)) – Auto Iteration Count, Use a automatic number of iterations based on the number of vertices of the sculpt

bpy.ops.sculpt.mask_from_cavity(mix_mode='MIX', mix_factor=1.0, settings_source='OPERATOR', factor=0.5, blur_steps=2, use_curve=False, invert=False)

Creates a mask based on the curvature of the surface

Parameters

• mix_mode (enum in ['MIX', 'MULTIPLY', 'DIVIDE', 'ADD', 'SUBTRACT'], (optional)) – Mode, Mix mode

• mix_factor (float in [0, 5], (optional)) – Mix Factor

• settings_source (enum in ['OPERATOR', 'BRUSH', 'SCENE'], (optional)) –

  Settings, Use settings from here

  • OPERATOR Operator – Use settings from operator properties.

  • BRUSH Brush – Use settings from brush.

  • SCENE Scene – Use settings from scene.

• factor (float in [0, 5], (optional)) – Factor, The contrast of the cavity mask

• blur_steps (int in [0, 25], (optional)) – Blur, The number of times the cavity mask is blurred

• use_curve (boolean, (optional)) – Custom Curve

• invert (boolean, (optional)) – Cavity (Inverted)

bpy.ops.sculpt.mask_init(mode='RANDOM_PER_VERTEX')

Creates a new mask for the entire mesh

Parameters

mode (enum in ['RANDOM_PER_VERTEX', 'RANDOM_PER_FACE_SET', 'RANDOM_PER_LOOSE_PART'], (optional)) – Mode

bpy.ops.sculpt.mesh_filter(area_normal_radius=0.25, strength=1.0, type='INFLATE', deform_axis={'X', 'Y', 'Z'}, orientation='LOCAL', surface_smooth_shape_preservation=0.5, surface_smooth_current_vertex=0.5, sharpen_smooth_ratio=0.35, sharpen_intensify_detail_strength=0.0, sharpen_curvature_smooth_iterations=0)

Applies a filter to modify the current mesh

Parameters

• area_normal_radius (float in [0.001, 5], (optional)) – Normal Radius, Radius used for calculating area normal on initial click,in percentage of brush radius

• strength (float in [-10, 10], (optional)) – Strength, Filter strength

• type (enum in ['SMOOTH', 'SCALE', 'INFLATE', 'SPHERE', 'RANDOM', 'RELAX', 'RELAX_FACE_SETS', 'SURFACE_SMOOTH', 'SHARPEN', 'ENHANCE_DETAILS', 'ERASE_DISCPLACEMENT'], (optional)) –

  Filter Type, Operation that is going to be applied to the mesh

  • SMOOTH Smooth – Smooth mesh.

  • SCALE Scale – Scale mesh.

  • INFLATE Inflate – Inflate mesh.

  • SPHERE Sphere – Morph into sphere.

  • RANDOM Random – Randomize vertex positions.

  • RELAX Relax – Relax mesh.

  • RELAX_FACE_SETS Relax Face Sets – Smooth the edges of all the Face Sets.

  • SURFACE_SMOOTH Surface Smooth – Smooth the surface of the mesh, preserving the volume.

  • SHARPEN Sharpen – Sharpen the cavities of the mesh.

  • ENHANCE_DETAILS Enhance Details – Enhance the high frequency surface detail.

  • ERASE_DISCPLACEMENT Erase Displacement – Deletes the displacement of the Multires Modifier.

• deform_axis (enum set in {'X', 'Y', 'Z'}, (optional)) –

  Deform Axis, Apply the deformation in the selected axis

  • X X – Deform in the X axis.

  • Y Y – Deform in the Y axis.

  • Z Z – Deform in the Z axis.

• orientation (enum in ['LOCAL', 'WORLD', 'VIEW'], (optional)) –

  Orientation, Orientation of the axis to limit the filter displacement

  • LOCAL Local – Use the local axis to limit the displacement.

  • WORLD World – Use the global axis to limit the displacement.

  • VIEW View – Use the view axis to limit the displacement.

• surface_smooth_shape_preservation (float in [0, 1], (optional)) – Shape Preservation, How much of the original shape is preserved when smoothing

• surface_smooth_current_vertex (float in [0, 1], (optional)) – Per Vertex Displacement, How much the position of each individual vertex influences the final result

• sharpen_smooth_ratio (float in [0, 1], (optional)) – Smooth Ratio, How much smoothing is applied to polished surfaces

• sharpen_intensify_detail_strength (float in [0, 10], (optional)) – Intensify Details, How much creases and valleys are intensified

• sharpen_curvature_smooth_iterations (int in [0, 10], (optional)) – Curvature Smooth Iterations, How much smooth the resulting shape is, ignoring high frequency details

bpy.ops.sculpt.optimize()

Recalculate the sculpt BVH to improve performance

bpy.ops.sculpt.project_line_gesture(xstart=0, xend=0, ystart=0, yend=0, flip=False, cursor=5, use_front_faces_only=False, use_limit_to_segment=False)

Project the geometry onto a plane defined by a line

Parameters

• xstart (int in [-inf, inf], (optional)) – X Start

• xend (int in [-inf, inf], (optional)) – X End

• ystart (int in [-inf, inf], (optional)) – Y Start

• yend (int in [-inf, inf], (optional)) – Y End

• flip (boolean, (optional)) – Flip

• cursor (int in [0, inf], (optional)) – Cursor, Mouse cursor style to use during the modal operator

• use_front_faces_only (boolean, (optional)) – Front Faces Only, Affect only faces facing towards the view

• use_limit_to_segment (boolean, (optional)) – Limit to Segment, Apply the gesture action only to the area that is contained within the segment without extending its effect to the entire line

bpy.ops.sculpt.reveal_all()

Unhide all geometry

bpy.ops.sculpt.sample_color()

Sample the vertex color of the active vertex

bpy.ops.sculpt.sample_detail_size(location=(0, 0), mode='DYNTOPO')

Sample the mesh detail on clicked point

Parameters

• location (int array of 2 items in [0, 32767], (optional)) – Location, Screen coordinates of sampling

• mode (enum in ['DYNTOPO', 'VOXEL'], (optional)) –

  Detail Mode, Target sculpting workflow that is going to use the sampled size

  • DYNTOPO Dyntopo – Sample dyntopo detail.

  • VOXEL Voxel – Sample mesh voxel size.

bpy.ops.sculpt.sculptmode_toggle()

Toggle sculpt mode in 3D view

bpy.ops.sculpt.set_detail_size()

Set the mesh detail (either relative or constant one, depending on current dyntopo mode)

bpy.ops.sculpt.set_persistent_base()

Reset the copy of the mesh that is being sculpted on

bpy.ops.sculpt.set_pivot_position(mode='UNMASKED', mouse_x=0.0, mouse_y=0.0)

Sets the sculpt transform pivot position

Parameters

• mode (enum in ['ORIGIN', 'UNMASKED', 'BORDER', 'ACTIVE', 'SURFACE'], (optional)) –

  Mode

  • ORIGIN Origin – Sets the pivot to the origin of the sculpt.

  • UNMASKED Unmasked – Sets the pivot position to the average position of the unmasked vertices.

  • BORDER Mask Border – Sets the pivot position to the center of the border of the mask.

  • ACTIVE Active Vertex – Sets the pivot position to the active vertex position.

  • SURFACE Surface – Sets the pivot position to the surface under the cursor.

• mouse_x (float in [0, inf], (optional)) – Mouse Position X, Position of the mouse used for “Surface” mode

• mouse_y (float in [0, inf], (optional)) – Mouse Position Y, Position of the mouse used for “Surface” mode

bpy.ops.sculpt.symmetrize(merge_tolerance=0.001)

Symmetrize the topology modifications

Parameters

merge_tolerance (float in [0, inf], (optional)) – Merge Distance, Distance within which symmetrical vertices are merged

bpy.ops.sculpt.trim_box_gesture(xmin=0, xmax=0, ymin=0, ymax=0, wait_for_input=True, use_front_faces_only=False, use_limit_to_segment=False, trim_mode='DIFFERENCE', use_cursor_depth=False, trim_orientation='VIEW')

Trims the mesh within the box as you move the brush

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

• use_front_faces_only (boolean, (optional)) – Front Faces Only, Affect only faces facing towards the view

• use_limit_to_segment (boolean, (optional)) – Limit to Segment, Apply the gesture action only to the area that is contained within the segment without extending its effect to the entire line

• trim_mode (enum in ['DIFFERENCE', 'UNION', 'JOIN'], (optional)) –

  Trim Mode

  • DIFFERENCE Difference – Use a difference boolean operation.

  • UNION Union – Use a union boolean operation.

  • JOIN Join – Join the new mesh as separate geometry, without performing any boolean operation.

• use_cursor_depth (boolean, (optional)) – Use Cursor for Depth, Use cursor location and radius for the dimensions and position of the trimming shape

• trim_orientation (enum in ['VIEW', 'SURFACE'], (optional)) –

  Shape Orientation

  • VIEW View – Use the view to orientate the trimming shape.

  • SURFACE Surface – Use the surface normal to orientate the trimming shape.

bpy.ops.sculpt.trim_lasso_gesture(path=None, use_front_faces_only=False, use_limit_to_segment=False, trim_mode='DIFFERENCE', use_cursor_depth=False, trim_orientation='VIEW')

Trims the mesh within the lasso as you move the brush

Parameters

• path (bpy_prop_collection of OperatorMousePath, (optional)) – Path

• use_front_faces_only (boolean, (optional)) – Front Faces Only, Affect only faces facing towards the view

• use_limit_to_segment (boolean, (optional)) – Limit to Segment, Apply the gesture action only to the area that is contained within the segment without extending its effect to the entire line

• trim_mode (enum in ['DIFFERENCE', 'UNION', 'JOIN'], (optional)) –

  Trim Mode

  • DIFFERENCE Difference – Use a difference boolean operation.

  • UNION Union – Use a union boolean operation.

  • JOIN Join – Join the new mesh as separate geometry, without performing any boolean operation.

• use_cursor_depth (boolean, (optional)) – Use Cursor for Depth, Use cursor location and radius for the dimensions and position of the trimming shape

• trim_orientation (enum in ['VIEW', 'SURFACE'], (optional)) –

  Shape Orientation

  • VIEW View – Use the view to orientate the trimming shape.

  • SURFACE Surface – Use the surface normal to orientate the trimming shape.

bpy.ops.sculpt.uv_sculpt_stroke(mode='NORMAL')

Sculpt UVs using a brush

Parameters

mode (enum in ['NORMAL', 'INVERT', 'RELAX'], (optional)) –

Mode, Stroke Mode

• NORMAL Regular – Apply brush normally.

• INVERT Invert – Invert action of brush for duration of stroke.

• RELAX Relax – Switch brush to relax mode for duration of stroke.