pixeltable 0.2.13__py3-none-any.whl → 0.2.15__py3-none-any.whl

pixeltable/functions/timestamp.py

@@ -0,0 +1,210 @@
+"""
+Pixeltable [UDFs](https://pixeltable.readme.io/docs/user-defined-functions-udfs) for `TimestampType`.
+
+Usage example:
+```python
+import pixeltable as pxt
+
+t = pxt.get_table(...)
+t.select(t.timestamp_col.year, t.timestamp_col.weekday()).collect()
+```
+"""
+
+from datetime import datetime
+from typing import Optional
+
+import pixeltable.func as func
+from pixeltable.utils.code import local_public_names
+
+
+@func.udf(is_method=True)
+def year(self: datetime) -> int:
+    """
+    Between [`MINYEAR`](https://docs.python.org/3/library/datetime.html#datetime.MINYEAR) and
+    [`MAXYEAR`](https://docs.python.org/3/library/datetime.html#datetime.MAXYEAR) inclusive.
+
+    Equivalent to [`datetime.year`](https://docs.python.org/3/library/datetime.html#datetime.datetime.year).
+    """
+    return self.year
+
+
+@func.udf(is_method=True)
+def month(self: datetime) -> int:
+    """
+    Between 1 and 12 inclusive.
+
+    Equivalent to [`datetime.month`](https://docs.python.org/3/library/datetime.html#datetime.datetime.month).
+    """
+    return self.month
+
+
+@func.udf(is_method=True)
+def day(self: datetime) -> int:
+    """
+    Between 1 and the number of days in the given month of the given year.
+
+    Equivalent to [`datetime.day`](https://docs.python.org/3/library/datetime.html#datetime.datetime.day).
+    """
+    return self.day
+
+
+@func.udf(is_method=True)
+def hour(self: datetime) -> int:
+    """
+    Between 0 and 23 inclusive.
+
+    Equivalent to [`datetime.hour`](https://docs.python.org/3/library/datetime.html#datetime.datetime.hour).
+    """
+    return self.hour
+
+
+@func.udf(is_method=True)
+def minute(self: datetime) -> int:
+    """
+    Between 0 and 59 inclusive.
+
+    Equivalent to [`datetime.minute`](https://docs.python.org/3/library/datetime.html#datetime.datetime.minute).
+    """
+    return self.minute
+
+
+@func.udf(is_method=True)
+def second(self: datetime) -> int:
+    """
+    Between 0 and 59 inclusive.
+
+    Equivalent to [`datetime.second`](https://docs.python.org/3/library/datetime.html#datetime.datetime.second).
+    """
+    return self.second
+
+
+@func.udf(is_method=True)
+def microsecond(self: datetime) -> int:
+    """
+    Between 0 and 999999 inclusive.
+
+    Equivalent to [`datetime.microsecond`](https://docs.python.org/3/library/datetime.html#datetime.datetime.microsecond).
+    """
+    return self.microsecond
+
+
+@func.udf(is_method=True)
+def weekday(self: datetime) -> int:
+    """
+    Between 0 (Monday) and 6 (Sunday) inclusive.
+
+    Equivalent to [`datetime.weekday()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.weekday).
+    """
+    return self.weekday()
+
+@func.udf(is_method=True)
+def isoweekday(self: datetime) -> int:
+    """
+    Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
+
+    Equivalent to [`datetime.isoweekday()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.isoweekday).
+    """
+    return self.isoweekday()
+
+
+@func.udf(is_method=True)
+def isocalendar(self: datetime) -> dict:
+    """
+    Return a dictionary with three entries: `'year'`, `'week'`, and `'weekday'`.
+
+    Equivalent to
+    [`datetime.isocalendar()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.isocalendar).
+    """
+    iso_year, iso_week, iso_weekday = self.isocalendar()
+    return {'year': iso_year, 'week': iso_week, 'weekday': iso_weekday}
+
+
+@func.udf(is_method=True)
+def isoformat(self: datetime, sep: str = 'T', timespec: str = 'auto') -> str:
+    """
+    Return a string representing the date and time in ISO 8601 format.
+
+    Equivalent to [`datetime.isoformat()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.isoformat).
+
+    Args:
+        sep: Separator between date and time.
+        timespec: The number of additional terms in the output. See the [`datetime.isoformat()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.isoformat) documentation for more details.
+    """
+    return self.isoformat(sep=sep, timespec=timespec)
+
+
+@func.udf(is_method=True)
+def strftime(self: datetime, format: str) -> str:
+    """
+    Return a string representing the date and time, controlled by an explicit format string.
+
+    Equivalent to [`datetime.strftime()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.strftime).
+
+    Args:
+        format: The format string to control the output. For a complete list of formatting directives, see [`strftime()` and `strptime()` Behavior](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-behavior).
+    """
+    return self.strftime(format)
+
+
+# @func.udf
+# def date(self: datetime) -> datetime:
+#     """
+#     Return the date part of the datetime.
+#
+#     Equivalent to [`datetime.date()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.date).
+#     """
+#     d = self.date()
+#     return datetime(d.year, d.month, d.day)
+#
+#
+# @func.udf
+# def time(self: datetime) -> datetime:
+#     """
+#     Return the time part of the datetime, with microseconds set to 0.
+#
+#     Equivalent to [`datetime.time()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.time).
+#     """
+#     t = self.time()
+#     return datetime(1, 1, 1, t.hour, t.minute, t.second, t.microsecond)
+
+
+@func.udf(is_method=True)
+def replace(
+        self: datetime, year: Optional[int] = None, month: Optional[int] = None, day: Optional[int] = None,
+        hour: Optional[int] = None, minute: Optional[int] = None, second: Optional[int] = None,
+        microsecond: Optional[int] = None) -> datetime:
+    """
+    Return a datetime with the same attributes, except for those attributes given new values by whichever keyword
+    arguments are specified.
+
+    Equivalent to [`datetime.replace()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.replace).
+    """
+    kwargs = {k: v for k, v in locals().items() if k != 'self' and v is not None}
+    return self.replace(**kwargs)
+
+
+@func.udf(is_method=True)
+def toordinal(self: datetime) -> int:
+    """
+    Return the proleptic Gregorian ordinal of the date, where January 1 of year 1 has ordinal 1.
+
+    Equivalent to [`datetime.toordinal()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.toordinal).
+    """
+    return self.toordinal()
+
+
+@func.udf(is_method=True)
+def posix_timestamp(self: datetime) -> float:
+    """
+    Return POSIX timestamp corresponding to the datetime instance.
+
+    Equivalent to [`datetime.timestamp()`](https://docs.python.org/3/library/datetime.html#datetime.datetime.timestamp).
+    """
+    return self.timestamp()
+
+
+__all__ = local_public_names(__name__)
+
+
+def __dir__():
+    return __all__

pixeltable/functions/together.py

@@ -1,3 +1,10 @@
+"""
+Pixeltable [UDFs](https://pixeltable.readme.io/docs/user-defined-functions-udfs)
+that wrap various endpoints from the Together AI API. In order to use them, you must
+first `pip install together` and configure your Together AI credentials, as described in
+the [Working with Together AI](https://pixeltable.readme.io/docs/together-ai) tutorial.
+"""
+
 import base64
 from typing import Optional, TYPE_CHECKING
 
@@ -41,6 +48,31 @@ def completions(
     n: Optional[int] = None,
     safety_model: Optional[str] = None,
 ) -> dict:
+    """
+    Generate completions based on a given prompt using a specified model.
+
+    Equivalent to the Together AI `completions` API endpoint.
+    For additional details, see: [https://docs.together.ai/reference/completions-1](https://docs.together.ai/reference/completions-1)
+
+    __Requirements:__
+
+    - `pip install together`
+
+    Args:
+        prompt: A string providing context for the model to complete.
+        model: The name of the model to query.
+
+    For details on the other parameters, see: [https://docs.together.ai/reference/completions-1](https://docs.together.ai/reference/completions-1)
+
+    Returns:
+        A dictionary containing the response and other metadata.
+
+    Examples:
+        Add a computed column that applies the model `mistralai/Mixtral-8x7B-v0.1` to an existing Pixeltable column `tbl.prompt`
+        of the table `tbl`:
+
+        >>> tbl['response'] = completions(tbl.prompt, model='mistralai/Mixtral-8x7B-v0.1')
+    """
     return (
         _together_client()
         .completions.create(
@@ -80,6 +112,32 @@ def chat_completions(
     tools: Optional[dict] = None,
     tool_choice: Optional[dict] = None,
 ) -> dict:
+    """
+    Generate chat completions based on a given prompt using a specified model.
+
+    Equivalent to the Together AI `chat/completions` API endpoint.
+    For additional details, see: [https://docs.together.ai/reference/chat-completions-1](https://docs.together.ai/reference/chat-completions-1)
+
+    __Requirements:__
+
+    - `pip install together`
+
+    Args:
+        messages: A list of messages comprising the conversation so far.
+        model: The name of the model to query.
+
+    For details on the other parameters, see: [https://docs.together.ai/reference/chat-completions-1](https://docs.together.ai/reference/chat-completions-1)
+
+    Returns:
+        A dictionary containing the response and other metadata.
+
+    Examples:
+        Add a computed column that applies the model `mistralai/Mixtral-8x7B-v0.1` to an existing Pixeltable column `tbl.prompt`
+        of the table `tbl`:
+
+        >>> messages = [{'role': 'user', 'content': tbl.prompt}]
+        ... tbl['response'] = chat_completions(tbl.prompt, model='mistralai/Mixtral-8x7B-v0.1')
+    """
     return (
         _together_client()
         .chat.completions.create(
@@ -117,6 +175,29 @@ _embedding_dimensions_cache = {
 
 @pxt.udf(batch_size=32, return_type=pxt.ArrayType((None,), dtype=pxt.FloatType()))
 def embeddings(input: Batch[str], *, model: str) -> Batch[np.ndarray]:
+    """
+    Query an embedding model for a given string of text.
+
+    Equivalent to the Together AI `embeddings` API endpoint.
+    For additional details, see: [https://docs.together.ai/reference/embeddings-2](https://docs.together.ai/reference/embeddings-2)
+
+    __Requirements:__
+
+    - `pip install together`
+
+    Args:
+        input: A string providing the text for the model to embed.
+        model: The name of the embedding model to use.
+
+    Returns:
+        An array representing the application of the given embedding to `input`.
+
+    Examples:
+        Add a computed column that applies the model `togethercomputer/m2-bert-80M-8k-retrieval`
+        to an existing Pixeltable column `tbl.text` of the table `tbl`:
+
+        >>> tbl['response'] = embeddings(tbl.text, model='togethercomputer/m2-bert-80M-8k-retrieval')
+    """
     result = _together_client().embeddings.create(input=input, model=model)
     return [np.array(data.embedding, dtype=np.float64) for data in result.data]
 
@@ -141,6 +222,31 @@ def image_generations(
     width: Optional[int] = None,
     negative_prompt: Optional[str] = None,
 ) -> PIL.Image.Image:
+    """
+    Generate images based on a given prompt using a specified model.
+
+    Equivalent to the Together AI `images/generations` API endpoint.
+    For additional details, see: [https://docs.together.ai/reference/post_images-generations](https://docs.together.ai/reference/post_images-generations)
+
+    __Requirements:__
+
+    - `pip install together`
+
+    Args:
+        prompt: A description of the desired images.
+        model: The model to use for image generation.
+
+    For details on the other parameters, see: [https://docs.together.ai/reference/post_images-generations](https://docs.together.ai/reference/post_images-generations)
+
+    Returns:
+        The generated image.
+
+    Examples:
+        Add a computed column that applies the model `runwayml/stable-diffusion-v1-5`
+        to an existing Pixeltable column `tbl.prompt` of the table `tbl`:
+
+        >>> tbl['response'] = image_generations(tbl.prompt, model='runwayml/stable-diffusion-v1-5')
+    """
     # TODO(aaron-siegel): Decompose CPU/GPU ops into separate functions
     result = _together_client().images.generate(
         prompt=prompt, model=model, steps=steps, seed=seed, height=height, width=width, negative_prompt=negative_prompt

pixeltable/functions/video.py

@@ -96,7 +96,7 @@ _extract_audio_param_types = [
 ]
 
 
-@func.udf(return_type=ts.AudioType(nullable=True), param_types=_extract_audio_param_types)
+@func.udf(return_type=ts.AudioType(nullable=True), param_types=_extract_audio_param_types, is_method=True)
 def extract_audio(
     video_path: str, stream_idx: int = 0, format: str = 'wav', codec: Optional[str] = None
 ) -> Optional[str]:
@@ -128,7 +128,7 @@ def extract_audio(
         return output_filename
 
 
-@func.udf(return_type=ts.JsonType(nullable=False), param_types=[ts.VideoType(nullable=False)])
+@func.udf(return_type=ts.JsonType(nullable=False), param_types=[ts.VideoType(nullable=False)], is_method=True)
 def get_metadata(video: str) -> dict:
     """
     Gets various metadata associated with a video file and returns it as a dictionary.

pixeltable/functions/{eval.py → vision.py}

@@ -1,11 +1,29 @@
-from typing import List, Tuple, Dict
+"""
+Pixeltable [UDFs](https://pixeltable.readme.io/docs/user-defined-functions-udfs) for Computer Vision.
+
+Example:
+```python
+import pixeltable as pxt
+from pixeltable.functions import vision as pxtv
+
+t = pxt.get_table(...)
+t.select(pxtv.draw_bounding_boxes(t.img, boxes=t.boxes, label=t.labels)).collect()
+```
+"""
+
+import colorsys
+import hashlib
+import random
 from collections import defaultdict
-import sys
+from typing import Optional, Union, Any
 
+import PIL.Image
+import PIL.Image
 import numpy as np
 
-import pixeltable.type_system as ts
 import pixeltable.func as func
+import pixeltable.type_system as ts
+from pixeltable.utils.code import local_public_names
 
 
 # TODO: figure out a better submodule structure
@@ -14,7 +32,7 @@ import pixeltable.func as func
 # the following function has been adapted from MMEval
 # (sources at https://github.com/open-mmlab/mmeval)
 # Copyright (c) OpenMMLab. All rights reserved.
-def calculate_bboxes_area(bboxes: np.ndarray) -> np.ndarray:
+def __calculate_bboxes_area(bboxes: np.ndarray) -> np.ndarray:
     """Calculate area of bounding boxes.
 
     Args:
@@ -31,7 +49,7 @@ def calculate_bboxes_area(bboxes: np.ndarray) -> np.ndarray:
 # the following function has been adapted from MMEval
 # (sources at https://github.com/open-mmlab/mmeval)
 # Copyright (c) OpenMMLab. All rights reserved.
-def calculate_overlaps(bboxes1: np.ndarray, bboxes2: np.ndarray) -> np.ndarray:
+def __calculate_overlaps(bboxes1: np.ndarray, bboxes2: np.ndarray) -> np.ndarray:
     """Calculate the overlap between each bbox of bboxes1 and bboxes2.
 
     Args:
@@ -58,8 +76,8 @@ def calculate_overlaps(bboxes1: np.ndarray, bboxes2: np.ndarray) -> np.ndarray:
         exchange = False
 
     # Calculate the bboxes area.
-    area1 = calculate_bboxes_area(bboxes1)
-    area2 = calculate_bboxes_area(bboxes2)
+    area1 = __calculate_bboxes_area(bboxes1)
+    area2 = __calculate_bboxes_area(bboxes2)
     eps = np.finfo(np.float32).eps
 
     for i in range(bboxes1.shape[0]):
@@ -80,9 +98,9 @@ def calculate_overlaps(bboxes1: np.ndarray, bboxes2: np.ndarray) -> np.ndarray:
 # the following function has been adapted from MMEval
 # (sources at https://github.com/open-mmlab/mmeval)
 # Copyright (c) OpenMMLab. All rights reserved.
-def calculate_image_tpfp(
+def __calculate_image_tpfp(
     pred_bboxes: np.ndarray, pred_scores: np.ndarray, gt_bboxes: np.ndarray, min_iou: float
-) -> Tuple[np.ndarray, np.ndarray]:
+) -> tuple[np.ndarray, np.ndarray]:
     """Calculate the true positive and false positive on an image.
 
     Args:
@@ -95,11 +113,8 @@ def calculate_image_tpfp(
 
     Returns:
         tuple (tp, fp):
-
-        - tp (numpy.ndarray): Shape (N,),
-          the true positive flag of each predicted bbox on this image.
-        - fp (numpy.ndarray): Shape (N,),
-          the false positive flag of each predicted bbox on this image.
+        tp: Shape (N,), the true positive flag of each predicted bbox on this image.
+        fp: Shape (N,), the false positive flag of each predicted bbox on this image.
     """
     # Step 1. Concatenate `gt_bboxes` and `ignore_gt_bboxes`, then set
     # the `ignore_gt_flags`.
@@ -121,7 +136,7 @@ def calculate_image_tpfp(
 
     # Step 4. Calculate the IoUs between the predicted bboxes and the
     # ground truth bboxes.
-    ious = calculate_overlaps(pred_bboxes, gt_bboxes)
+    ious = __calculate_overlaps(pred_bboxes, gt_bboxes)
     # For each pred bbox, the max iou with all gts.
     ious_max = ious.max(axis=1)
     # For each pred bbox, which gt overlaps most with it.
@@ -160,14 +175,17 @@ def calculate_image_tpfp(
     ],
 )
 def eval_detections(
-    pred_bboxes: List[List[int]],
-    pred_labels: List[int],
-    pred_scores: List[float],
-    gt_bboxes: List[List[int]],
-    gt_labels: List[int],
-) -> Dict:
+    pred_bboxes: list[list[int]],
+    pred_labels: list[int],
+    pred_scores: list[float],
+    gt_bboxes: list[list[int]],
+    gt_labels: list[int],
+) -> dict:
+    """
+    Evaluates the performance of a set of predicted bounding boxes against a set of ground truth bounding boxes.
+    """
     class_idxs = list(set(pred_labels + gt_labels))
-    result: List[Dict] = []
+    result: list[dict] = []
     pred_bboxes_arr = np.asarray(pred_bboxes)
     pred_classes_arr = np.asarray(pred_labels)
     pred_scores_arr = np.asarray(pred_scores)
@@ -177,7 +195,7 @@ def eval_detections(
         pred_filter = pred_classes_arr == class_idx
         gt_filter = gt_classes_arr == class_idx
         class_pred_scores = pred_scores_arr[pred_filter]
-        tp, fp = calculate_image_tpfp(pred_bboxes_arr[pred_filter], class_pred_scores, gt_bboxes_arr[gt_filter], [0.5])
+        tp, fp = __calculate_image_tpfp(pred_bboxes_arr[pred_filter], class_pred_scores, gt_bboxes_arr[gt_filter], [0.5])
         ordered_class_pred_scores = -np.sort(-class_pred_scores)
         result.append(
             {
@@ -194,17 +212,21 @@ def eval_detections(
 
 @func.uda(update_types=[ts.JsonType()], value_type=ts.JsonType(), allows_std_agg=True, allows_window=False)
 class mean_ap(func.Aggregator):
+    """
+    Calculates the mean average precision (mAP) over
+    [`eval_detections()`][pixeltable.functions.vision.eval_detections] results.
+    """
     def __init__(self):
-        self.class_tpfp: Dict[int, List[Dict]] = defaultdict(list)
+        self.class_tpfp: dict[int, list[dict]] = defaultdict(list)
 
-    def update(self, eval_dicts: List[Dict]) -> None:
+    def update(self, eval_dicts: list[dict]) -> None:
         for eval_dict in eval_dicts:
             class_idx = eval_dict['class']
             self.class_tpfp[class_idx].append(eval_dict)
 
-    def value(self) -> Dict:
+    def value(self) -> dict:
         eps = np.finfo(np.float32).eps
-        result: Dict[int, float] = {}
+        result: dict[int, float] = {}
         for class_idx, tpfp in self.class_tpfp.items():
             a1 = [x['tp'] for x in tpfp]
             tp = np.concatenate([x['tp'] for x in tpfp], axis=0)
@@ -225,3 +247,124 @@ class mean_ap(func.Aggregator):
             ap = np.sum((mrec[ind + 1] - mrec[ind]) * mpre[ind + 1])
             result[class_idx] = ap.item()
         return result
+
+
+def _create_label_colors(labels: list[Any]) -> dict[Any, str]:
+    """
+    Create random colors for labels such that a particular label always gets the same color.
+
+    Returns:
+        dict mapping labels to colors
+    """
+    distinct_labels = set(labels)
+    result: dict[Any, str] = {}
+    for label in distinct_labels:
+        # consistent hash for the label
+        label_hash = int(hashlib.md5(str(label).encode()).hexdigest(), 16)
+        hue = (label_hash % 360) / 360.0
+        rgb = colorsys.hsv_to_rgb(hue, 0.7, 0.95)
+        hex_color = '#{:02x}{:02x}{:02x}'.format(int(rgb[0]*255), int(rgb[1]*255), int(rgb[2]*255))
+        result[label] = hex_color
+    return result
+
+
+@func.udf
+def draw_bounding_boxes(
+        img: PIL.Image.Image,
+        boxes: list[list[int]],
+        labels: Optional[list[Any]] = None,
+        color: Optional[str] = None,
+        label_colors: Optional[dict[Union[str, int], str]] = None,
+        box_colors: Optional[list[str]] = None,
+        fill: bool  = False,
+        width: int = 1,
+        font: Optional[str] = None,
+        font_size: Optional[int] = None,
+) -> PIL.Image.Image:
+    """
+    Draws bounding boxes on the given image.
+
+    Labels can be any type that supports `str()` and is hashable (e.g., strings, ints, etc.).
+
+    Colors can be specified as common HTML color names (e.g., 'red') supported by PIL's
+    [`ImageColor`](https://pillow.readthedocs.io/en/stable/reference/ImageColor.html#imagecolor-module) module or as
+    RGB hex codes (e.g., '#FF0000').
+
+    If no colors are specified, this function randomly assigns each label a specific color based on a hash of the label.
+
+    Args:
+        img: The image on which to draw the bounding boxes.
+        boxes: List of bounding boxes, each represented as [xmin, ymin, xmax, ymax].
+        labels: List of labels for each bounding box.
+        color: Single color to be used for all bounding boxes and labels.
+        label_colors: Dictionary mapping labels to colors.
+        box_colors: List of colors, one per bounding box.
+        fill: Whether to fill the bounding boxes with color.
+        width: Width of the bounding box borders.
+        font: Name of a system font or path to a TrueType font file, as required by
+            [`PIL.ImageFont.truetype()`](https://pillow.readthedocs.io/en/stable/reference/ImageFont.html#PIL.ImageFont.truetype).
+            If `None`, uses the default provided by
+            [`PIL.ImageFont.load_default()`](https://pillow.readthedocs.io/en/stable/reference/ImageFont.html#PIL.ImageFont.load_default).
+        font_size: Size of the font used for labels in points. Only used in conjunction with non-`None` `font` argument.
+
+    Returns:
+        The image with bounding boxes drawn on it.
+    """
+    color_params = sum([color is not None, label_colors is not None, box_colors is not None])
+    if color_params > 1:
+        raise ValueError("Only one of 'color', 'label_colors', or 'box_colors' can be set")
+
+    # ensure the number of labels matches the number of boxes
+    num_boxes = len(boxes)
+    if labels is None:
+        labels = [None] * num_boxes
+    elif len(labels) != num_boxes:
+        raise ValueError('Number of boxes and labels must match')
+
+    DEFAULT_COLOR = 'white'
+    if box_colors is not None:
+        if len(box_colors) != num_boxes:
+            raise ValueError('Number of boxes and box colors must match')
+    else:
+        if color is not None:
+            box_colors = [color] * num_boxes
+        elif label_colors is not None:
+            box_colors = [label_colors.get(label, DEFAULT_COLOR) for label in labels]
+        else:
+            label_colors = _create_label_colors(labels)
+            box_colors = [label_colors[label] for label in labels]
+
+    from PIL import ImageDraw, ImageFont, ImageColor
+    # set default font if not provided
+    if font is None:
+        txt_font = ImageFont.load_default()
+    else:
+        txt_font = ImageFont.truetype(font=font, size=font_size or 10)
+
+    img_to_draw = img.copy()
+    draw = ImageDraw.Draw(img_to_draw, 'RGBA' if fill else 'RGB')
+
+    for i, (bbox, label) in enumerate(zip(boxes, labels)):
+        # determine color for the current box and label
+        color = box_colors[i % len(box_colors)]
+
+        if fill:
+            rgb_color = ImageColor.getrgb(color)
+            fill_color = rgb_color + (100,)  # semi-transparent
+            draw.rectangle(bbox, outline=color, width=width, fill=fill_color)
+        else:
+            draw.rectangle(bbox, outline=color, width=width)
+
+        if label is not None:
+            label_str = str(label)
+            margin = width + 1
+            draw.text((bbox[0] + margin, bbox[1] + margin), label_str, fill=color, font=txt_font)
+
+    return img_to_draw
+
+
+__all__ = local_public_names(__name__)
+
+
+def __dir__():
+    return __all__

pixeltable/functions/whisper.py

@@ -1,3 +1,11 @@
+"""
+Pixeltable [UDF](https://pixeltable.readme.io/docs/user-defined-functions-udfs)
+that wraps the OpenAI Whisper library.
+
+This UDF will cause Pixeltable to invoke the relevant model locally. In order to use it, you must
+first `pip install openai-whisper`.
+"""
+
 from typing import TYPE_CHECKING, Optional
 
 import pixeltable as pxt
@@ -39,6 +47,30 @@ def transcribe(
     append_punctuations: str = '"\'.。,，!！?？:：”)]}、',
     decode_options: Optional[dict] = None,
 ) -> dict:
+    """
+    Transcribe an audio file using Whisper.
+
+    This UDF runs a transcription model _locally_ using the Whisper library,
+    equivalent to the Whisper `transcribe` function, as described in the
+    [Whisper library documentation](https://github.com/openai/whisper).
+
+    __Requirements:__
+
+    - `pip install openai-whisper`
+
+    Args:
+        audio: The audio file to transcribe.
+        model: The name of the model to use for transcription.
+
+    Returns:
+        A dictionary containing the transcription and various other metadata.
+
+    Examples:
+        Add a computed column that applies the model `base.en` to an existing Pixeltable column `tbl.audio`
+        of the table `tbl`:
+
+        >>> tbl['result'] = transcribe(tbl.audio, model='base.en')
+    """
     import torch
 
     if decode_options is None:

pixeltable/io/__init__.py

@@ -1,5 +1,5 @@
 from .external_store import ExternalStore, SyncStatus
-from .globals import create_label_studio_project
+from .globals import create_label_studio_project, import_rows, import_json
 from .hf_datasets import import_huggingface_dataset
 from .pandas import import_csv, import_excel, import_pandas
 from .parquet import import_parquet