Mask Tools

Blender currently lacks the functionality to save dynatopo sculpt masks. Even though this can be done with a hacky method its confusing for most.

This add-on allows saving masks as vertexgroups and coverting vertex groups to masks.

Thanks to Psy-fi for his hint on bpy api.

Thanks to Stan Pancakes for Cutom Data Layer Access patch.

Thanks to Ideasman42 for review / patch commit.

Mask Tools : Mask Tools v.035

Update 07 / 14 / 2015 : Uploaded v.035

— v.035 Update Log —

  1. Bugfix on script after 2.75a Blender release

— v.03 Update Log —

  1. Addon now supports Cavity Masking

  2. Addon now supports Edge Masking

  3. Addon now supports Smooth All Mask

Note : Cavity and Edge Masking is computationally heavy. If your sculpt vertex count is greater than 100k make sure to save your work before using it. Also wait for blender to finish it can take up to 10-15 seconds for 600 k - 800 k meshes.

Its in view3d > tool panel > sculpting

There are 3 buttons for converting masks to vertex groups; 3 buttons for converting vertex groups to masks.

Mask To VGroup :

Create Vgroup: Creates a new vgroup and assigns the mask.

Vgroup Add : If a vgroup is selected, adds the current mask to it.

Vgroup Remove : If a vgroup is selected, removes the current mask from it.

VGroup To Mask :

Create Mask: If a vgroup is selected, creates a mask from it. Deleting existing mask

Mask Add : If a vgroup is selected, adds the selected vgroup to the mask.

Mask Remove : If a vgroup is selected, removes the selected vgroup from the mask.

Mask by Edges :

Based on the angle input and strength, create a edge mask.

Mask by Cavity :

Create : Based on the angle input and strength, create a cavity mask.

Mask Smooth :

Smooth all mask based on strength. (For clean blending , apply then increase strength gradually)


Installation Note : Please use " Install from file" option in preferences/addons.
If you are doing manual install make sure you extract all files together to the addons folder (they need to be together).

Note: This addon will only work for dynatopo sculpts, multi-res won’t work.


@yii7: hey bro, have you streamlined the code with the new way of getting mask data in phyton?, if so do i have your permission to vulture some of the codes?, i have a great idea for an addon that will make the Dyntopo Sculpture Club very happy. :slight_smile:


Nope its not new way. I do check the commit logs every other day ( might have missed it dunno ?). This still uses the hacky way… :frowning:

Yea you can help yourself with whatever is in the python files ( as long as its free and open-source ).

1 Like

remember StanPancakes sample code for converting mask to vgroups using the new python exposing the mask layer? that’s it, i was hoping you incorporated that.

Yeah I remember, his code accessed vertex custom data layer (which holds the mask info per vertex). That needs to be committed to trunk so that I can implement something similar; as far as I know that patch is still not in trunk.

@yii7 if you can, please write little video with usage of script. thx

yii7, it should be there, it was committed.

@Stan Pancakes: got any sample code i could use bro?, mask to vgroups using the new python for these thing.

Ah I see, Campbell committed it at 23 April ; that’s why I missed it. I didn’t think it would be that quickly added. Thanks Stan.

If I manage to implement something useful can I add your name to the add-on info ?

iceking, sure, here’s the function I use. It’s a bit convoluted, because it checks if the code to access mask is in there, and if not it falls back to the hide-unhide-selection hack:

def mask_to_vertex_group(obj, name):
    vgroup =
    if 'paint_mask' in dir(bmesh.types.BMLayerAccessVert):
        bm =
        deform_layer =
        if deform_layer is None: deform_layer =
        mask =
        if mask is not None:
            for v in bm.verts:
                # Don't forget to invert the value
                v[deform_layer][vgroup.index] = 1.0-v[mask]
            for v in bm.verts:
                v[deform_layer][vgroup.index] = 1.0
        # Deselect everything in edit mode
        # Hide masked area
        bpy.ops.paint.hide_show(action='HIDE', area='MASKED')
        # Select everything (i.e. not masked)
        # Reveal masked area
        bpy.ops.paint.hide_show(action='SHOW', area='MASKED')
    return vgroup

I’ve been meaning to update my sculpt add-on with this for a while now, but haven’t gotten around to it yet.

yii7, if you want to, sure :slight_smile: Patch and this code are for all to use!

@Stan Pancakes: thanks man…, so seeing as the code is here to stay, that part could be omitted. this will have so many uses. thanks again.

I used to achieve this the long way:

I’d mask off something in Sculpt Mode. Then I’d invert the mask selection and hide the selected, I’d immediately go into Edit Mode and highlight the vertices and assign/save those as a vertex group. Then I go back into Sculpt Mode and un-hide the selection. I could go back and re-call that vertex group in Edit Mode, invert the selection and hide other vertices, go into Sculpt Mode and Mask that visible piece of geometry, and then go back to Edit Mode to un-hide the rest of the mesh.

This was my original way of “saving” masks and turning masks into vertex groups. A rather arduous process, esp. when you’ve got to do it a lot. It seems this addon pretty achieve much the same effect, but in a far more workflow-friendly way. This addon is a godsend!

It will save me so much time, allow greater freedom in recalling masking groups, in converting masked regions into vertex groups, and hopefully, serve as a foundation to future masking improvements in Blender (such as coupling the Dirty Vertex Color tool or the AO node in Cycles with Sculpt Mode’s masking ability to get a Masking by AO selection feature, or using the 3D Printing Toolbox’s ability to select certain kinds of surface conditions such as Volume and Overhang with Sculpt Mode’s masking to get Mask by Volume/Mask by Overhang, etc.) So much potential for this kind of thing!

I can also see that I might can better use the Sculpt Tools addon with this, to use saved masks for mesh extractions á la ZBrush’s Mesh Extraction. Hopefully, this would lead to adding mesh management (“subtools” as ZBrush calls it) in Blender’s Sculpt Mode, along with some layer management functionality, to truly bring masking in Blender sculpting to fuller life.

Then, other stuff like rigging up “Insert Brushes”-like brushes that insert instances of a mesh along a curve (converted Grease Pencil or precise-control curves) using the Array Modifier, but all ready within Sculpt Mode. Man, there’s just so much re-using existing Blender features to make Sculpt Mode (and Texture Paint Mode) fill out well. And I think such potential starts with small steps at a time, like this addon.

Anyways, I realize this stuff takes time, I don’t want to undermine this useful addon (to which I am thankful), and Blender development all depends on the priorities/abilities/free time of generous developers, but maybe this kind of thing will motivate and lead to some future focus for Blender development. I don’t think Blender will ever become a “free version of ZBrush” or anything that ambitious, but it could become a pretty respectful alternative.

Anyways, thanks!

Thanks :smiley: . And Thanks to Stanislav too.

Cavity masks and mask from dirty vertex colors are nice ideas, hope me (or anyone) can implement something like that. I have couple of more advanced uses for masks.

I’m currently apply an easier approach based on the patch from Stan. If I can finish it, we can move on to the other features.

I have tried your addon and i like, but i think would be more useful if works with multires modifier.
i had another idea to implement,

i hope you have something like that on your plans.

I was waiting for this when I saw the API addition, so awesome!

Nice idea too ; forgot about this i will add it to future feature list. Thanks.

Ps: Multi-res system is completely different and as far as I know we can’t edit the multi-res subdivision layers from outside C code. I guess multi-res keeps the subdvision on a cache (on the disk or memory). To save a mask we either need to access the cache and edit it (read/write) or make some kind of projection ; and for that python api needs access to this multi - res layers :frowning:

@ Crocadillian : Yea the API update opened the way for better implementations and possible other uses, I started updating the script, the mask to vertex group and vertexgroup to mask with blending is done, but still need to finish the add remove part for vgroup to mask (hopefully soon). Then some tests and addon will be updated after 2.75 relase.

1 Like

I’m getting this error when trying to create mask from vertex group:

hi , atekron. This is strange, it is trying to invoke " bpy.ops.mesh.customdata_clear_mask.poll() " function and can’t find it. Thus the error.

That function is a built-in blender function which means it should be in all blender python API’s… Unless the version you are using is older than the version it was introduced.

can you tell me which version are you running ? - Never mind i can see it in the error screen capture. 2.74 78250f1

Can you test the add-on with you default blender instead of a newer revision

It seems someone changed the name of the " customdata_clear_mask " to " customdata_mask_clear " that is causing the issue.

The addon should work with 2.74 official release, but it won’t work on 2.75, I have to ask if this is going to change or not and depending on the answer update the add-on. It something trivial really you can make a fix by editing the python file if its urgent. Just change line 33 in > bpy.ops.mesh.customdata_clear_mask.poll() > to > bpy.ops.mesh.customdata_mask_clear.poll()

Or you can use the official 2.74 build until I make the changes official. Cheers

EDIT : There were 2 lines that needed changing so I made a 2.75 compatible version.Adding the link to the original post and this post.

bpy python API change compatible Mask Tools 2.75 : Link

I had to replace “custom data clear mask” not only in line 33 but all occurrences in this file to make it work, thank you great addon!