Improve type annotations and comments

JAG2GLA.py

@@ -287,7 +287,7 @@ def saveToBlender(self, scene_root: bpy.types.Object, skeletonFixes: JAG2Constan
 
 class MdxaFrame:
     def __init__(self):
-        self.boneIndices = []
+        self.boneIndices: List[int] = []
 
     # returns the highest referenced index - not nice from a design standpoint but saves space, which is probably good.
     def loadFromFile(self, file, numBones):
@@ -325,7 +325,7 @@ def saveToFile(self, file: BinaryIO) -> None:
 
 class MdxaAnimation:
     def __init__(self):
-        self.frames = []
+        self.frames: List[MdxaFrame] = []
         self.bonePool = MdxaBonePool()
 
     def loadFromFile(self, file: BinaryIO, header: MdxaHeader, startFrame: int, numFrames: int) -> Tuple[bool, ErrorMessage]:
@@ -391,13 +391,13 @@ def saveToFile(self, file: BinaryIO, header: MdxaHeader):
         assert (file.tell() == header.ofsCompBonePool)
         self.bonePool.saveToFile(file)
 
-    def saveToBlender(self, skeleton, armature, scale):
+    def saveToBlender(self, skeleton: MdxaSkel, armature: bpy.types.Object, scale):
         import time
         startTime = time.time()
         #   Bone Position Set Order
         # bones have to be set in hierarchical order - their position depends on their parent's absolute position, after all.
         # so this is the order in which bones have to be processed.
-        hierarchyOrder = []
+        hierarchyOrder: List[int] = []
         while len(hierarchyOrder) < len(skeleton.bones):
             # make sure we add something each frame (infinite loop otherwise)
             addedSomething = False
@@ -414,11 +414,11 @@ def saveToBlender(self, skeleton, armature, scale):
         # for going leaf to root
 
         #   Blender PoseBones list
-        bones = []
+        bones: List[bpy.types.PoseBone] = []
         for info in skeleton.bones:  # is ordered by index
             bones.append(armature.pose.bones[info.name])
 
-        basePoses = []
+        basePoses: List[mathutils.Matrix] = []
         for bone in skeleton.bones:
             basePoses.append(bone.basePoseMat.toBlender())
 
@@ -465,32 +465,32 @@ def saveToBlender(self, skeleton, armature, scale):
             scene.frame_set(frameNum)
 
             # absolute offset matrices by bone index
-            offsets = {}
+            offsets: Dict[int, mathutils.Matrix] = {}
             for index in hierarchyOrder:
                 bpy.ops.object.mode_set(mode='POSE', toggle=False)
                 mdxaBone = skeleton.bones[index]
                 assert (mdxaBone.index == index)
                 bonePoolIndex = frame.boneIndices[index]
                 # get offset transformation matrix, relative to parent
-                offset = self.bonePool.bones[bonePoolIndex].matrix
+                offset = downcast(List[JAG2Math.CompBone], self.bonePool.bones)[bonePoolIndex].matrix
                 # turn into absolute offset matrix (already is if this is top level bone)
                 if mdxaBone.parent != -1:
-                    offset = offsets[mdxaBone.parent] @ offset
+                    offset = matrix_overload_cast(offsets[mdxaBone.parent] @ offset)
                 # save this absolute offset for use by children
                 offsets[index] = offset
                 # calculate the actual position
-                transformation = offset @ basePoses[index]
+                transformation = matrix_overload_cast(offset @ basePoses[index])
                 # flip axes as required for blender bone
                 JAG2Math.GLABoneRotToBlender(transformation)
 
                 pose_bone = bones[index]
                 # pose_bone.matrix = transformation * scaleMatrix
                 pose_bone.matrix = transformation
-                # in the _humanoid face, the scale gets changed. that messes the re-export up.
+                # in the _humanoid face, the scale gets changed. that messes the re-export up. FIXME: understand why. Is there a problem?
                 pose_bone.scale = [1, 1, 1]
                 pose_bone.keyframe_insert('location')
                 pose_bone.keyframe_insert('rotation_quaternion')
-                # hackish way to force the matrix to update
+                # hackish way to force the matrix to update. FIXME: this seems to slow the process down a lot
                 bpy.ops.object.mode_set(mode='OBJECT', toggle=False)
 
         scene.frame_current = 1

JAG2Math.py

@@ -57,10 +57,11 @@ def fromBlender(self, mat: mathutils.Matrix) -> None:
             self.rows.append(l)
         del self.rows[3]
 
-# changes a GLA bone's rotation matrix (X+ = front) to blender style (Y+ = front)
 
-
-def GLABoneRotToBlender(matrix) -> None:
+def GLABoneRotToBlender(matrix: mathutils.Matrix) -> None:
+    """
+    Changes a GLA bone's rotation matrix (X+ = front) to blender style (Y+ = front)
+    """
     new_x = -matrix.col[1].copy()
     new_y = matrix.col[0].copy()
     matrix.col[0] = new_x
@@ -73,10 +74,11 @@ def GLABoneRotToBlender(matrix) -> None:
         matrix[0][2], -matrix[1][2], - \
         matrix[2][2], matrix[0][0], matrix[1][0], matrix[2][0]
 
-# changes a blender bone's rotation matrix (Y+ = front) to GLA style (X+ = front)
-
 
 def BlenderBoneRotToGLA(matrix: mathutils.Matrix) -> None:
+    """
+    Changes a blender bone's rotation matrix (Y+ = front) to GLA style (X+ = front)
+    """
     # undo roll 90 degrees
     matrix[0][0], matrix[1][0], matrix[2][0], matrix[0][2], matrix[1][2], matrix[2][2] = matrix[0][2], matrix[1][2], matrix[2][2], - \
         matrix[0][0], -matrix[1][0], -matrix[2][0]

casts.py

@@ -59,7 +59,7 @@ def vector_overload_cast(x: Any) -> mathutils.Vector:
     return overload_cast(mathutils.Vector, x)
 
 
-def matrix_overload_cast(x: Any) -> mathutils.Matrix:
+def matrix_overload_cast(x: mathutils.Matrix | mathutils.Vector) -> mathutils.Matrix:
     """
     Shorthand for overload_cast(mathutils.Matrix, x).
     Matrix and Quaternion multiplication currently lacks overloads to distinguish matrix returns.