[feat] add ref. point feature for flatten uv

- add reference point & uv feature for flatten.
- due to first feature, flatten uv now can process more structure of ballance floor, such as looping floor with low edge count.
- give flatten uv 2 different modes.
- original flatten uv method still existed as a scale size mode.

ballance_blender_plugin/MODS_flatten_uv.py

@@ -3,32 +3,61 @@ import bmesh
 import math
 from . import UTILS_functions
 
+class ScaleDataUnion(object):
+    def __init__(self):
+        self.UseRefPoint: bool = None
+    def SetAsScale(self, scale_num: float):
+        self.UseRefPoint: bool = False
+        self.ScaleSize: float = scale_num
+    def SetAsRefPoint(self, ref_point: int, ref_point_uv: float):
+        self.UseRefPoint: bool = True
+        self.ReferencePoint: int = ref_point
+        self.ReferenceUV: float = ref_point_uv
+
 class BALLANCE_OT_flatten_uv(bpy.types.Operator):
     """Flatten selected face UV. Only works for convex face"""
     bl_idname = "ballance.flatten_uv"
     bl_label = "Flatten UV"
     bl_options = {'REGISTER', 'UNDO'}
 
-    normal_scale_correction = 5.0
+    reference_edge : bpy.props.IntProperty(
-    sink_scale_correction = 5.0 * (math.sqrt(2.5 ** 2 + 0.7 ** 2) / 2.5)
+        name="Reference Edge",
-
+        description="The references edge of UV.\nIt will be placed in V axis.",
-    scale_correction: bpy.props.EnumProperty(
+        min=0,
-        name="Scale Correction",
+        soft_min=0, soft_max=3,
-        description="Choose your UV scale.",
+        default=0,
-        items=(
-            ("NORMAL", "Normal Floor", "Normal floor scale, 5.0"),
-            ("SINK", "Sink Floor", "Sink floor scale, around 5.19")
-        ),
-        default='NORMAL',
     )
 
-    reference_edge : bpy.props.IntProperty(
+    scale_mode: bpy.props.EnumProperty(
-        name="Reference edge",
+        name="Scale Mode",
-        description="The references edge of UV. It will be placed in V axis.",
+        items=(('NUM', "Scale Size", "Scale UV with specific number."),
+               ('REF', "Ref. Point", "Scale UV with Reference Point feature."),
+               ),
+    )
+
+    scale_number : bpy.props.FloatProperty(
+        name="Scale Size",
+        description="The size which will be applied for scale.",
         min=0,
-        soft_min=0,
+        soft_min=0, soft_max=5,
-        soft_max=3,
+        default=5.0,
-        default=0,
+        step=0.1, precision=1,
+    )
+
+    reference_point : bpy.props.IntProperty(
+        name="Reference Point",
+        description="The references point of UV.\nIt's U component will be set to the number specified by Reference Point UV.\nThis point index is related to the start point of reference edge.",
+        min=2,  # 0 and 1 is invalid. we can not order the reference edge to be set on the outside of uv axis
+        soft_min=2, soft_max=3,
+        default=2,
+    )
+
+    reference_uv : bpy.props.FloatProperty(
+        name="Reference Point UV",
+        description="The U component which should be applied to references point in UV.",
+        soft_min=0, soft_max=1,
+        default=0.5,
+        step=0.1, precision=2,
     )
 
     @classmethod
@@ -42,26 +71,38 @@ class BALLANCE_OT_flatten_uv(bpy.types.Operator):
             return False
         return True
 
-    def get_scale_correction(self):
-        if self.scale_correction == 'NORMAL':
-            return BALLANCE_OT_flatten_uv.normal_scale_correction
-        elif self.scale_correction == 'SINK':
-            return BALLANCE_OT_flatten_uv.sink_scale_correction
-        else:
-            raise Exception("Unknow scale correction.")
-
     def execute(self, context):
-        no_processed_count = _real_flatten_uv(bpy.context.active_object.data, self.reference_edge, self.get_scale_correction())
+        # construct scale data
+        scale_data: ScaleDataUnion = ScaleDataUnion()
+        if self.scale_mode == 'NUM':
+            scale_data.SetAsScale(self.scale_number)
+        else:
+            scale_data.SetAsRefPoint(self.reference_point, self.reference_uv)
+
+        # do flatten uv and report
+        no_processed_count = _real_flatten_uv(bpy.context.active_object.data, self.reference_edge, scale_data)
         if no_processed_count != 0:
             print("[Flatten UV] {} faces may not be processed correctly because they have problem.".format(no_processed_count))
         return {'FINISHED'}
 
     def draw(self, context):
         layout = self.layout
-        layout.prop(self, "scale_correction")
+        layout.emboss = 'NORMAL'
         layout.prop(self, "reference_edge")
 
-def _real_flatten_uv(mesh, reference_edge, scale_correction):
+        layout.separator()
+        layout.label(text="Scale Mode")
+        layout.prop(self, "scale_mode", expand=True)
+        
+        layout.separator()
+        layout.label(text="Scale Config")
+        if self.scale_mode == 'NUM':
+            layout.prop(self, "scale_number")
+        else:
+            layout.prop(self, "reference_point")
+            layout.prop(self, "reference_uv")
+
+def _real_flatten_uv(mesh, reference_edge, scale_data: ScaleDataUnion):
     no_processed_count = 0
 
     if mesh.uv_layers.active is None:
@@ -71,16 +112,25 @@ def _real_flatten_uv(mesh, reference_edge, scale_correction):
     bm = bmesh.from_edit_mesh(mesh)
     uv_lay = bm.loops.layers.uv.active
     for face in bm.faces:
+        # ========== only process selected face ==========
         if not face.select:
             continue
 
-        # check whether ref edge is legal
+        # ========== resolve reference edge and point ==========
+        # check reference validation
         allPoint = len(face.loops)
-        if allPoint <= reference_edge:
+        if reference_edge >= allPoint:  # reference edge overflow
-            no_processed_count+=1
+            no_processed_count += 1
             continue
 
-        # get correct new corrdinate system
+        # check scale validation
+        if scale_data.UseRefPoint:
+            if ((scale_data.ReferencePoint <= 1)    # reference point too low
+                or (scale_data.ReferencePoint >= allPoint)):    # reference point overflow
+                no_processed_count += 1
+                continue
+
+        # ========== get correct new corrdinate system ==========
         # yyc mark:
         # we use 3 points located in this face to calc 
         # the base of this local uv corredinate system.
@@ -90,7 +140,7 @@ def _real_flatten_uv(mesh, reference_edge, scale_correction):
         # if z axis is zero vector, we will try using face normal instead 
         # to try getting correct data.
         # 
-        # zero base is not important. because it will not raise any math exceptio
+        # zero base is not important. because it will not raise any math exception
         # just a weird uv. user will notice this problem.
 
         # get point
@@ -102,9 +152,9 @@ def _real_flatten_uv(mesh, reference_edge, scale_correction):
         if p3Relative >= allPoint:
             p3Relative -= allPoint
 
-        p1=mathutils.Vector(tuple(face.loops[p1Relative].vert.co[x] for x in range(3)))
+        p1 = mathutils.Vector(tuple(face.loops[p1Relative].vert.co[x] for x in range(3)))
-        p2=mathutils.Vector(tuple(face.loops[p2Relative].vert.co[x] for x in range(3)))
+        p2 = mathutils.Vector(tuple(face.loops[p2Relative].vert.co[x] for x in range(3)))
-        p3=mathutils.Vector(tuple(face.loops[p3Relative].vert.co[x] for x in range(3)))
+        p3 = mathutils.Vector(tuple(face.loops[p3Relative].vert.co[x] for x in range(3)))
 
         # get y axis
         new_y_axis = p2 - p1
@@ -115,7 +165,7 @@ def _real_flatten_uv(mesh, reference_edge, scale_correction):
         # get z axis
         new_z_axis = new_y_axis.cross(vec1)
         new_z_axis.normalize()
-        if not any(round(v, 7) for v in new_z_axis):
+        if not any(round(v, 7) for v in new_z_axis):    # if z is a zero vector, use face normal instead
             new_z_axis = face.normal.normalized()
 
         # get x axis
@@ -137,21 +187,50 @@ def _real_flatten_uv(mesh, reference_edge, scale_correction):
         transition_matrix = origin_base @ new_base
         transition_matrix.invert_safe()
 
-        # process each face
+        # ========== rescale correction ==========
+        if scale_data.UseRefPoint:
+            # ref point method
+            # get reference point from loop
+            refpRelative = p1Relative + scale_data.ReferencePoint
+            if refpRelative >= allPoint:
+                refpRelative -= allPoint
+            pRef = mathutils.Vector(tuple(face.loops[refpRelative].vert.co[x] for x in range(3))) - p1
+
+            # calc its U component
+            vec_u = abs((transition_matrix @ pRef).x)
+            if round(vec_u, 7) == 0.0:
+                rescale = 1 # fallback. rescale = 1 will not affect anything
+            else:
+                rescale = scale_data.ReferenceUV / vec_u
+        else:
+            # scale size method
+            # apply rescale directly
+            rescale = 1.0 / scale_data.ScaleSize
+            
+        # construct matrix
+        # we only rescale U component (X component)
+        # and 5.0 scale for V component (Y component)
+        scale_matrix = mathutils.Matrix((
+            (rescale, 0, 0),
+            (0, 1.0 / 5.0, 0),
+            (0, 0, 1.0)
+        ))
+        # order can not be changed. we order do transition first, then scale it.
+        rescale_transition_matrix = scale_matrix @ transition_matrix
+
+        # ========== process each face ==========
         for loop_index in range(allPoint):
-            pp = mathutils.Vector(tuple(face.loops[loop_index].vert.co[x] for x in range(3)))
+            pp = mathutils.Vector(tuple(face.loops[loop_index].vert.co[x] for x in range(3))) - p1
-            vec = pp-p1
+            ppuv = rescale_transition_matrix @ pp
-            new_vec = transition_matrix @ vec
 
             # y axis always use 5.0 to scale
-            # however, x need use custom scale correction.
+            # however, x need use custom scale correction which has been calculated by our matrix.
             face.loops[loop_index][uv_lay].uv = (
-                (new_vec.x if new_vec.x >=0 else -new_vec.x) / scale_correction,
+                abs(ppuv.x),
-                (new_vec.y) / 5.0
+                ppuv.y
             )
 
     # Show the updates in the viewport
     bmesh.update_edit_mesh(mesh)
-
     return no_processed_count