Merge remote-tracking branch 'origin/master'

README.md

@@ -1,13 +1,14 @@
-# Blender - Bake ID Mask Plugin
+# Blender - ID Mask Tools
 
-A plugin to quickly bake ID masks for meshes from/to different sources and targets.
+A set of tools to quickly create ID masks for meshes.
 
-### Currently supported:
+### What is this?
-Sources:
+For usage in specific programs like Substance Painter, its useful to create a mask for specific parts for your mesh, so you can easily make out parts of the mesh, to f.E. apply a mterial. 
-- Material Index
+You can specify colors in color attributes that define "IDs" for specific parts of the mesh, which you can then use in different programs.
 
-Targets:
+Currently this workflow requires you to assign them tediously by using a mixture of Edit Mode and Vertex Paint to paint the mesh correctly. 
-- Vertex Color
+
+This plugin tries to fix that, by providing proper tools for it. The most important is probably the [ID Mask Editor](docu/features/id_mask_editor.md), that allows you to quickly add IDs to faces all within the Edit Mode.
 
 ## Installation
 1. Download the newest file from the releases tab.
@@ -16,12 +17,4 @@ Targets:
 4. After selecting it, just enable it and done.
 
 ## Usage
-You find the tool in the panel on the right of the "3D Viewport" under "Tool".
+Check out the [Features](docu/features.md) page to find more specific information about the usage of each feature.
-![Panel Location](docu/images/panel.png)
-
-How to use properly it, highly depends on the selected source.
-
-### Usage - Material Index Source
-Here the IDs are given based on the object and its material indices.
-
-Lets say, you have 10 objects and each has 2 materials attached to it. Then the amount of IDs given is 20, since each object contains the two material indecies.

build/.version

@@ -1 +1 @@
-1.3.0+build.1
+1.3.1+build.2

docu/features.md

@@ -0,0 +1,3 @@
+# Features
+- [ID Mask Editor](features/id_mask_editor.md)
+- [Bake ID Mask](features/bake_id_mask.md)

docu/features/bake_id_mask.md

@@ -0,0 +1,52 @@
+# Bake ID Mask
+This tool allows you to quickly create a ID mask based on different sources
+
+The tool is found in the Tool category in the Side Panel of the 3D View.
+![Panel Location](../images/bake_id_mask.panel.png)
+
+## The UI
+![UI](../images/bake_id_mask.ui.png)
+
+1. The Bake button. Click on it to bake, after you have setup your selection
+2. Selection Mode. See "Parameters"
+3. This panel gives you infos about how many ID you gonna bake and how many colors you have in your color source
+4. The source specifies, what kind of dataset the system will take to calculate its IDs
+5. This box allows the source to have parameters, you can change
+6. The target specifies, where the ID get drawn to. Currently only color attributes are supported
+7. as with the source, the target can have parameters, as well.
+8. This allows you to change the color source, from where the system takes the colors.
+
+## Parameters
+### Selection Mode
+The "Selection Mode" has 3 different options:
+1. Only active element - The bake will only apply to the actively selected object. If no active object was found, nothing will happens.
+2. Use Selection, separate - The bake will apply to all selected objects, but each object will be processed individually by the source. 
+Example: With Material Index, the ID will always correspond with the Material Index, ignoring what ever happens with the other objects.
+3. Use Selection, combined - The bake will apply to all selected object and will be processed together by the source.
+Example: With Material Index, it will count up every Material Index it finds.
+
+### Sources
+#### Material Index
+This source will give away IDs based on the material index, a face uses. 
+This can be useful, when you use multiple materials in one mesh and want to export it with only one material and without loosing the info, which face had different materials.
+
+The "Remove all source materials" option will, if checked, remove all material indecies from the mesh, allowing you to directly export it to your application.
+
+#### Object ID
+This source will only work properly in "Use Selection, combined" - Selection Mode. The source works by giving every selected Object an incrementing ID.
+
+### Targets
+#### Color Attribute / Vertex Color
+This target will save the ID-color onto the color attribute specified.
+
+By default, it will remove the old color attribute completely and replace it, if one already exists with the name. This can be prevent by unchecking "Override Color Attribute".
+The ID-color will then just painted on top of the existing attribute, overriding existing colors, if there were any.
+
+### Color Sources
+#### Generated
+This color source will generate a list of colors to use, which get increasingly less saturated and bright as further, you approach the limit.
+
+#### Color Palette
+This allows you to specify an own palette, previously created in Blender. 
+
+Due to the way palettes work in Blender, you can **not** create or edit the palette here. You can create one in one of the "Paint" modes, like Vertex Paint.

docu/features/id_mask_editor.md

@@ -0,0 +1,29 @@
+# ID Mask Editor
+The "ID Mask Editor" allows you to quickly add IDs to faces in a mesh.
+
+## Getting started
+The editor is found in the Tool category in the Side Panel of the 3D View. The editor is only visible when you are in Edit Mode.
+![Panel Location](../images/id_mask_editor.panel.png)
+
+By default, its pretty empty. That is because you need to specify a color attribute, you want to paint your ID-mask to.
+You can either select an already existing color attribute or you create a new one using the "Plus"-button. That will automatically create color attribute called "ID_MASK" and set it as ID-mask.
+
+With the attribute selected, you will see a few more options.
+
+## The UI
+![Panel Options](../images/id_mask_editor.options_0.png)
+1. The color source. That specifies how the initial colors are generated, when adding new IDs using the "Plus"-Button
+2. This is the ID-list. It works similarly to the Vertex Groups-list. The only big difference is how the items works. You can change the color and name of an ID. Change the color will cause the two buttons to be enabled. They allow you to either "Revert" the change you made or to "Apply" it, which will change the ID-mask to reflect the change.
+3. Clicking the "Paint"-button will paint the currently active ID (indicated by the blue background in the list) onto the currently selected **faces**.
+4. Clicking the "Select"-button will select every face currently using the currently active ID (indicated by the blue background in the list)
+5. Changing the color on a ID will not automatically apply it onto the attribute. This will allow you to apply/revert all those changes, with one click.
+
+### Additional Features
+Using the arrow next to the list allows you to find additional features:
+- Find used colors: Using this feature will automatically detect colors found in the attribute, but not found in the ID list, and add them. 
+Very useful when dealing with a mesh created without this tool or if you accidentally removed an ID from the list.
+
+## One additional thing
+While not directly related to the ID-Mask, but still kinda, there is a new selection found under the "Select" menu.
+This will allow you to quickly select faces, with the same ID, then the face you have currently active.
+![Select by ID Mask](../images/id_mask_editor.select_by_id_mask.png)

src/__init__.py

@@ -1,17 +1,17 @@
 import bpy
 
-from src.menu import id_mask_select_menu
+from . menu import id_mask_select_menu
-from src.menu.id_mask_editor_options import IDEDITOR_IDMaskEditorOptionsMenu
+from . menu.id_mask_editor_options import IDEDITOR_IDMaskEditorOptionsMenu
-from src.operators.create_id_mask import CreateIDMaskOperator
+from . operators.create_id_mask import CreateIDMaskOperator
-from src.operators.id_editor_apply_color import IDEDITOR_ColorApplyOperator
+from . operators.id_editor_apply_color import IDEDITOR_ColorApplyOperator
-from src.operators.id_editor_create_id import IDEDITOR_CreateIDOperator
+from . operators.id_editor_create_id import IDEDITOR_CreateIDOperator
-from src.operators.id_editor_find_used_ids import IDEDITOR_FindUsedIDsOperator
+from . operators.id_editor_find_used_ids import IDEDITOR_FindUsedIDsOperator
-from src.operators.id_editor_paint import IDEDITOR_PaintIDMaskOperator
+from . operators.id_editor_paint import IDEDITOR_PaintIDMaskOperator
-from src.operators.id_editor_remove_id import IDEDITOR_RemoveIDOperator
+from . operators.id_editor_remove_id import IDEDITOR_RemoveIDOperator
-from src.operators.id_editor_revert_color import IDEDITOR_ColorResetOperator
+from . operators.id_editor_revert_color import IDEDITOR_ColorResetOperator
-from src.operators.id_mask_select import IDEDITOR_SelectIDMaskOperator
+from . operators.id_mask_select import IDEDITOR_SelectIDMaskOperator
-from src.panels.id_mask_editor_id_list import IDMaskEditorIDList
+from . panels.id_mask_editor_id_list import IDMaskEditorIDList
-from src.properties.id_mask_editor_value_properties import IDMaskEditorValueProperties
+from . properties.id_mask_editor_value_properties import IDMaskEditorValueProperties
 from . panels.bake_panel_options import BakeToIDOptionsPanel
 from . operators.bake_to_id_map import BakeToIDMapOperator
 from . panels.bake_panel import BakeToIDMapPanel
@@ -19,7 +19,7 @@ from . panels.bake_panel_info import BakeToIDInfoPanel
 from . panels.id_mask_editor import IDMaskEditorPanel
 from . properties.bake_properties import BakeToIDProperties
 
-from src.properties.id_mask_editor_properties import IDMaskEditorProperties
+from . properties.id_mask_editor_properties import IDMaskEditorProperties
 
 bl_info = {
     "name": "ID Mask - Tools",

src/menu/id_mask_editor_options.py

@@ -1,6 +1,6 @@
 import bpy
 
-from src.operators.id_editor_find_used_ids import IDEDITOR_FindUsedIDsOperator
+from .. operators.id_editor_find_used_ids import IDEDITOR_FindUsedIDsOperator
 
 
 class IDEDITOR_IDMaskEditorOptionsMenu(bpy.types.Menu):

src/menu/id_mask_select_menu.py

@@ -1,6 +1,6 @@
 import bpy
 
-from src.operators.id_mask_select import IDEDITOR_SelectIDMaskOperator
+from .. operators.id_mask_select import IDEDITOR_SelectIDMaskOperator
 
 def id_mask_select_menu_function(self, context):
     self.layout.operator(IDEDITOR_SelectIDMaskOperator.bl_idname).isCalledFromEditor = False

src/operators/create_id_mask.py

@@ -1,6 +1,5 @@
 import bpy
 
-
 class CreateIDMaskOperator(bpy.types.Operator):
     bl_idname = "id_mask_editor.create_id_mask_attribute"
     bl_label = "Create ID Mask - Attribute"

src/operators/id_editor_create_id.py

@@ -1,7 +1,6 @@
 import bpy
 
-from src.properties.id_mask_editor_value_properties import IDMaskEditorValueProperties
+from .. types.colors import get_color
-from src.types.colors import get_color
 
 
 class IDEDITOR_CreateIDOperator(bpy.types.Operator):

src/operators/id_editor_remove_id.py

@@ -1,9 +1,5 @@
 import bpy
 
-from src.properties.id_mask_editor_value_properties import IDMaskEditorValueProperties
-from src.types.colors import get_color
-
-
 class IDEDITOR_RemoveIDOperator(bpy.types.Operator):
     bl_idname = "id_mask_editor.remove_id_mask"
     bl_label = "id_mask_editor.remove_id_mask"

src/operators/id_mask_select.py

@@ -1,6 +1,5 @@
 import bpy
 
-
 class IDEDITOR_SelectIDMaskOperator(bpy.types.Operator):
     bl_idname = "id_mask_editor.select_id_mask"
     bl_label = "Select by ID Mask"

src/panels/id_mask_editor.py

@@ -1,14 +1,14 @@
 import bpy
 
-from src.menu.id_mask_editor_options import IDEDITOR_IDMaskEditorOptionsMenu
+from .. menu.id_mask_editor_options import IDEDITOR_IDMaskEditorOptionsMenu
-from src.operators.create_id_mask import CreateIDMaskOperator
+from .. operators.create_id_mask import CreateIDMaskOperator
-from src.operators.id_editor_apply_color import IDEDITOR_ColorApplyOperator
+from .. operators.id_editor_apply_color import IDEDITOR_ColorApplyOperator
-from src.operators.id_editor_create_id import IDEDITOR_CreateIDOperator
+from .. operators.id_editor_create_id import IDEDITOR_CreateIDOperator
-from src.operators.id_editor_paint import IDEDITOR_PaintIDMaskOperator
+from .. operators.id_editor_paint import IDEDITOR_PaintIDMaskOperator
-from src.operators.id_editor_remove_id import IDEDITOR_RemoveIDOperator
+from .. operators.id_editor_remove_id import IDEDITOR_RemoveIDOperator
-from src.operators.id_editor_revert_color import IDEDITOR_ColorResetOperator
+from .. operators.id_editor_revert_color import IDEDITOR_ColorResetOperator
-from src.operators.id_mask_select import IDEDITOR_SelectIDMaskOperator
+from .. operators.id_mask_select import IDEDITOR_SelectIDMaskOperator
-from src.types.colors import get_color
+from .. types.colors import get_color
 
 
 class IDMaskEditorPanel(bpy.types.Panel):
@@ -59,9 +59,6 @@ class IDMaskEditorPanel(bpy.types.Panel):
         row = layout.row()
 
         col = row.column()
-        button_row = col.row()
-        button_row.operator(IDEDITOR_PaintIDMaskOperator.bl_idname, text='Paint', icon='VPAINT_HLT')
-        button_row.operator(IDEDITOR_SelectIDMaskOperator.bl_idname, text='Select', icon='SELECT_SET').isCalledFromEditor = True
 
         col.template_list(
             'IDMaskEditorIDList',
@@ -73,7 +70,11 @@ class IDMaskEditorPanel(bpy.types.Panel):
             rows=3
         )
 
-        color_button_row = col.row(align=True)
+        button_row = col.row()
+        button_row.operator(IDEDITOR_PaintIDMaskOperator.bl_idname, text='Paint', icon='VPAINT_HLT')
+        button_row.operator(IDEDITOR_SelectIDMaskOperator.bl_idname, text='Select', icon='SELECT_SET').isCalledFromEditor = True
+
+        color_button_row = button_row.row(align=True)
         has_color_changed = False
         for id in properties.possible_ids:
             if not id.color_changed:

src/panels/id_mask_editor_id_list.py

@@ -1,9 +1,7 @@
 import bpy
 
-from src.operators.id_editor_apply_color import IDEDITOR_ColorApplyOperator
+from .. operators.id_editor_apply_color import IDEDITOR_ColorApplyOperator
-from src.operators.id_editor_find_used_ids import IDEDITOR_FindUsedIDsOperator
+from .. operators.id_editor_revert_color import IDEDITOR_ColorResetOperator
-from src.operators.id_editor_paint import IDEDITOR_PaintIDMaskOperator
-from src.operators.id_editor_revert_color import IDEDITOR_ColorResetOperator
 
 
 class IDMaskEditorIDList(bpy.types.UIList):

src/properties/bake_properties.py

@@ -1,9 +1,9 @@
 from bpy.types import (PropertyGroup, Palette)
 from bpy.props import (EnumProperty, BoolProperty, IntProperty, StringProperty, PointerProperty)
 
-from src.types.colors import get_color_enum
+from .. types.colors import get_color_enum
-from src.types.sources import get_source_enum
+from .. types.sources import get_source_enum
-from src.types.targets import get_targets_enum
+from .. types.targets import get_targets_enum
 
 
 class BakeToIDProperties(PropertyGroup):

src/properties/id_mask_editor_properties.py

@@ -3,8 +3,8 @@ import bpy
 from bpy.types import (PropertyGroup, Palette, FloatColorAttribute)
 from bpy.props import (EnumProperty, BoolProperty, IntProperty, StringProperty, PointerProperty, CollectionProperty)
 
-from src.properties.id_mask_editor_value_properties import IDMaskEditorValueProperties
+from .. properties.id_mask_editor_value_properties import IDMaskEditorValueProperties
-from src.types.colors import get_color_enum
+from .. types.colors import get_color_enum
 
 def on_target_attribute_set(self, value):
     return None