Documented 'clips_array' and renamed 'cols_widths' argument by 'cols_heights'

CHANGELOG.md

@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Lots of method and parameter names have been changed. This will be explained better in the documentation soon. See https://github.com/Zulko/moviepy/pull/1170 for more information. [\#1170](https://github.com/Zulko/moviepy/pull/1170)
 - Changed recommended import from `import moviepy.editor` to `import moviepy`. This change is fully backwards compatible [\#1340](https://github.com/Zulko/moviepy/pull/1340)
 - Renamed `audio.fx.volumex` to `audio.fx.multiply_volume` [\#1424](https://github.com/Zulko/moviepy/pull/1424)
+- Renamed `cols_widths` argument of `clips_array` function by `cols_heights` [\#1465](https://github.com/Zulko/moviepy/pull/1465)
 
 ### Deprecated <!-- for soon-to-be removed features -->
 - `moviepy.video.fx.all` and `moviepy.audio.fx.all`. Use the fx method directly from the clip instance or import the fx function from `moviepy.video.fx` and `moviepy.audio.fx`. [\#1105](https://github.com/Zulko/moviepy/pull/1105)

moviepy/video/compositing/CompositeVideoClip.py

@@ -148,42 +148,68 @@ def close(self):
             self.audio = None
 
 
-def clips_array(array, rows_widths=None, cols_widths=None, bg_color=None):
-    """
+def clips_array(array, rows_widths=None, cols_heights=None, bg_color=None):
+    """Given a matrix whose rows are clips, creates a CompositeVideoClip where
+    all clips are placed side by side horizontally for each clip in each row
+    and one row on top of the other for each row. So given next matrix of clips
+    with same size:
+
+    ```python
+    clips_array([[clip1, clip2, clip3], [clip4, clip5, clip6]])
+    ```
+
+    the result will be a CompositeVideoClip with a layout displayed like:
+
+    ```
+    ┏━━━━━━━┳━━━━━━━┳━━━━━━━┓
+    ┃       ┃       ┃       ┃
+    ┃ clip1 ┃ clip2 ┃ clip3 ┃
+    ┃       ┃       ┃       ┃
+    ┣━━━━━━━╋━━━━━━━╋━━━━━━━┫
+    ┃       ┃       ┃       ┃
+    ┃ clip4 ┃ clip5 ┃ clip6 ┃
+    ┃       ┃       ┃       ┃
+    ┗━━━━━━━┻━━━━━━━┻━━━━━━━┛
+    ```
+
+    If some clips doesn't fulfill the space required by the rows or columns
+    in which are placed, that space will be filled by the color defined in
+    ``bg_color``.
+
+    array
+      Matrix of clips included in the returned composited video clip.
 
     rows_widths
-      widths of the different rows in pixels. If None, is set automatically.
-
-    cols_widths
-      widths of the different colums in pixels. If None, is set automatically.
+      Widths of the different rows in pixels. If ``None``, is set automatically.
 
-    cols_widths
+    cols_heights
+      Heights of the different colums in pixels. If ``None``, is set automatically.
 
     bg_color
-       Fill color for the masked and unfilled regions. Set to None for these
-       regions to be transparent (will be slower).
-
+       Fill color for the masked and unfilled regions. Set to ``None`` for these
+       regions to be transparent (processing will be slower).
     """
-
     array = np.array(array)
     sizes_array = np.array([[clip.size for clip in line] for line in array])
 
     # find row width and col_widths automatically if not provided
     if rows_widths is None:
         rows_widths = sizes_array[:, :, 1].max(axis=1)
-    if cols_widths is None:
-        cols_widths = sizes_array[:, :, 0].max(axis=0)
+    if cols_heights is None:
+        cols_heights = sizes_array[:, :, 0].max(axis=0)
 
-    xs = np.cumsum([0] + list(cols_widths))
+    # compute start positions of X for rows and Y for columns
+    xs = np.cumsum([0] + list(cols_heights))
     ys = np.cumsum([0] + list(rows_widths))
 
-    for j, (x, cw) in enumerate(zip(xs[:-1], cols_widths)):
+    for j, (x, ch) in enumerate(zip(xs[:-1], cols_heights)):
         for i, (y, rw) in enumerate(zip(ys[:-1], rows_widths)):
             clip = array[i, j]
             w, h = clip.size
-            if (w < cw) or (h < rw):
+            # if clip not fulfill row width or column height
+            if (w < ch) or (h < rw):
                 clip = CompositeVideoClip(
-                    [clip.with_position("center")], size=(cw, rw), bg_color=bg_color
+                    [clip.with_position("center")], size=(ch, rw), bg_color=bg_color
                 ).with_duration(clip.duration)
 
             array[i, j] = clip.with_position((x, y))