Renovating this code

intern/generate_adm.py

@@ -1,7 +1,5 @@
 import bpy
 
-from contextlib import contextmanager
-
 import lxml
 import uuid
 from fractions import Fraction
@@ -33,6 +31,17 @@ from .speaker_utils import (all_speakers)
 
 
 def group_speakers(speakers, scene) -> List[List[bpy.types.Object]]:
+    """
+    Accepts a list of speakers and a scene, and returns a list of lists.
+
+    Each list contains a list of speakers which are guaranteed to not have
+    overlapping sounds. Each of the child lists contains a list of speaker
+    objects in ascending order by start time.
+
+    Speakers are allocated to lists on the basis of their minimum distance to
+    the camera according to `speakers_by_min_distance`. Closer sounds will 
+    appear on the earliest list if there is no overlap.
+    """
     def list_can_accept_speaker(speaker_list, speaker_to_test):
         test_range = speaker_active_time_range(speaker_to_test)
 
@@ -62,7 +71,7 @@ def group_speakers(speakers, scene) -> List[List[bpy.types.Object]]:
     return ret_val
 
 
-def adm_for_object(scene, sound_object: ObjectMix, room_size, adm_builder, object_index):
+def adm_for_object(scene: bpy.types.Scene, sound_object: ObjectMix, room_size, adm_builder, object_index):
     fps = scene.render.fps
     frame_start = scene.frame_start
     frame_end = scene.frame_end
@@ -79,7 +88,7 @@ def adm_for_object(scene, sound_object: ObjectMix, room_size, adm_builder, objec
     created.track_uid.bitDepth = sound_object.bits_per_sample
 
 
-def adm_for_scene(scene, sound_objects: List[ObjectMix], room_size):
+def adm_for_scene(scene: bpy.types.Scene, sound_object_mixes: List[ObjectMix], room_size):
     adm_builder = ADMBuilder()
 
     frame_start = scene.frame_start
@@ -92,7 +101,7 @@ def adm_for_scene(scene, sound_objects: List[ObjectMix], room_size):
 
     adm_builder.create_content(audioContentName="Objects")
 
-    for object_index, sound_object in enumerate(sound_objects):
+    for object_index, sound_object in enumerate(sound_object_mixes):
         adm_for_object(scene, sound_object, room_size, adm_builder, object_index)
 
     adm = adm_builder.adm
@@ -178,11 +187,19 @@ def print_partition_results(object_groups, sound_sources, too_far_speakers):
             print(" - %s" % source.name)
 
 
-def partition_sounds_to_objects(scene, max_objects):
+def partition_sounds_to_objects(scene, max_objects) -> \
+        tuple[list[list[bpy.types.Speaker]], list[bpy.types.Speaker]]:
+    """
+    Allocates sounds in the scene into non-overlapping lists of sounds. The
+    second return value is the list of sounds that could not be allocated
+    because the max_objects limit was exceeded.
+
+    Sounds are allocated to lists according to `group_speakers`.
+    """
     sound_sources = all_speakers(scene)
 
     if len(sound_sources) == 0:
-        return []
+        return [], []
 
     object_groups = group_speakers(sound_sources, scene)
     too_far_speakers = []
@@ -196,7 +213,8 @@ def partition_sounds_to_objects(scene, max_objects):
     return object_groups, too_far_speakers
 
 
-def generate_adm(context: bpy.types.Context, filepath: str, room_size: float, max_objects: int):
+def generate_adm(context: bpy.types.Context, filepath: str, room_size: float, 
+                 max_objects: int) -> dict:
     scene = context.scene
 
     object_groups, _ = partition_sounds_to_objects(scene, max_objects)