Allow create_text to accept multiple texts and materials fixes #1012

fury/actor/core.py

@@ -262,35 +262,101 @@ def create_point(geometry, material):
 
 
 def create_text(text, material, **kwargs):
-    """Create a text object.
+    """Create a text object or a group of text objects.
 
     Parameters
     ----------
-    text : str
-        The text content.
-    material : TextMaterial
-        The material object.
+    text : str or list of str
+        The text content or list of text contents.
+    material : TextMaterial or list of TextMaterial
+        The material object or list of material objects.
     **kwargs : dict
-        Additional properties like font_size, anchor, etc.
+        Additional properties like font_size, anchor, position, etc.
+        When ``text`` is a list, each kwarg can be either:
+        - A single value applied to all text objects, or
+        - A list of values (one per text) for per-text customization.
 
     Returns
     -------
-    Text
-        The text object.
+    Text or Group
+        A single Text object if text is a string, or a Group of Text
+        objects if text is a list.
 
     Raises
     ------
     TypeError
-        If text is not a string or material is not an instance of TextMaterial.
+        If text is not a string or list of strings, or material is not
+        an instance of TextMaterial or list of TextMaterial.
+    ValueError
+        If the length of material list or any kwarg list does not match
+        the length of the text list.
+
+    Examples
+    --------
+    >>> mat = TextMaterial()
+    >>> # Single text (unchanged behavior)
+    >>> t = create_text("Hello", mat)
+
+    >>> # Multiple texts, shared material and kwargs
+    >>> t = create_text(["Hello", "World", "FURY"], mat)
+
+    >>> # Multiple texts with individual materials and per-text positions
+    >>> t = create_text(
+    ...     ["Hello", "World"],
+    ...     [TextMaterial(), TextMaterial()],
+    ...     position=[(0, 0, 0), (1, 0, 0)],
+    ... )
     """
+    if isinstance(text, list):
+        if not all(isinstance(t, str) for t in text):
+            raise TypeError("All items in text list must be strings.")
+
+        n = len(text)
+
+        if isinstance(material, list):
+            if len(material) != n:
+                raise ValueError(
+                    "Length of material list must match length of text list."
+                )
+            if not all(isinstance(m, TextMaterial) for m in material):
+                raise TypeError(
+                    "All items in material list must be instances of TextMaterial."
+                )
+            materials = material
+        else:
+            if not isinstance(material, TextMaterial):
+                raise TypeError("material must be an instance of TextMaterial.")
+            materials = [material] * n
+
+        # Normalize kwargs: expand scalars to per-text lists
+        norm_kwargs = {}
+        for k, v in kwargs.items():
+            if isinstance(v, list):
+                if len(v) != n:
+                    raise ValueError(
+                        f"Length of kwarg '{k}' list must match length of text list."
+                    )
+                norm_kwargs[k] = v
+            else:
+                norm_kwargs[k] = [v] * n
+
+        group = Group()
+        for i, (t, m) in enumerate(zip(text, materials, strict=True)):
+            per_text_kwargs = {k: norm_kwargs[k][i] for k in norm_kwargs}
+            position = per_text_kwargs.pop("position", None)
+            actor = Text(text=t, material=m, **per_text_kwargs)
+            if position is not None:
+                actor.local.position = position
+            group.add(actor)
+        return group
+
     if not isinstance(text, str):
         raise TypeError("text must be a string.")
 
     if not isinstance(material, TextMaterial):
         raise TypeError("material must be an instance of TextMaterial.")
 
-    text = Text(text=text, material=material, **kwargs)
-    return text
+    return Text(text=text, material=material, **kwargs)
 
 
 def create_image(image_input, material, **kwargs):