Adds docstrings for gr.WaveformOptions, gr.Brush, and gr.Eraser…

…, fixes examples for `ImageEditor`, and allows individual images to be used as the initial `value` for `ImageEditor` (#6799)

* tweaks

* add changeset

* adding image editor

* changes

* add changeset

* docs

* add changeset

* add changeset

* refactor

* format

* example

* add changeset

* image editor

* add changeset

* commit

* added test

---------

Co-authored-by: gradio-pr-bot <gradio-pr-bot@users.noreply.github.com>

.changeset/full-gifts-press.md

@@ -0,0 +1,7 @@
+---
+"@gradio/audio": patch
+"@gradio/imageeditor": patch
+"gradio": patch
+---
+
+fix:Adds docstrings for `gr.WaveformOptions`, `gr.Brush`, and `gr.Eraser`, fixes examples for `ImageEditor`, and allows individual images to be used as the initial `value` for `ImageEditor`

gradio/__init__.py

@@ -57,7 +57,8 @@
     Video,
     component,
 )
-from gradio.components.audio import WaveformOptions  # type: ignore
+from gradio.components.audio import WaveformOptions
+from gradio.components.image_editor import Brush, Eraser
 from gradio.data_classes import FileData
 from gradio.events import EventData, LikeData, SelectData, on
 from gradio.exceptions import Error

gradio/components/audio.py

@@ -22,11 +22,21 @@
 
 @dataclasses.dataclass
 class WaveformOptions:
-    waveform_color: str | None = None
-    waveform_progress_color: str | None = None
-    show_controls: bool = False
-    skip_length: str | None = None
+    """
+    A dataclass for specifying options for the waveform display in the Audio component. An instance of this class can be passed into the `waveform_options` parameter of `gr.Audio`.
+    Parameters:
+        waveform_color: The color (as a hex string or valid CSS color) of the full waveform representing the amplitude of the audio. Defaults to a light gray color.
+        waveform_progress_color: The color (as a hex string or valid CSS color) that the waveform fills with to as the audio plays. Defaults to an orange color.
+        show_recording_waveform: Whether to show the waveform when recording audio. Defaults to True.
+        show_controls: Whether to show the standard HTML audio player below the waveform when recording audio or playing recorded audio. Defaults to False.
+        skip_length: The percentage (between 0 and 100) of the audio to skip when clicking on the skip forward / skip backward buttons. Defaults to 5.
+    """
+
+    waveform_color: str = "#9ca3af"
+    waveform_progress_color: str = "#f97316"
     show_recording_waveform: bool = True
+    show_controls: bool = False
+    skip_length: int | float = 5
 
 
 @document()

gradio/components/image_editor.py

@@ -22,10 +22,19 @@
 _Image.init()  # fixes https://github.com/gradio-app/gradio/issues/2843
 
 
+ImageType = Union[np.ndarray, _Image.Image, str]
+
+
 class EditorValue(TypedDict):
-    background: Optional[Union[np.ndarray, _Image.Image, str]]
-    layers: list[Union[np.ndarray, _Image.Image, str]]
-    composite: Optional[Union[np.ndarray, _Image.Image, str]]
+    background: Optional[ImageType]
+    layers: list[ImageType]
+    composite: Optional[ImageType]
+
+
+class EditorExampleValue(TypedDict):
+    background: Optional[str]
+    layers: Optional[list[str | None]]
+    composite: Optional[str]
 
 
 class EditorData(GradioModel):
@@ -36,11 +45,26 @@ class EditorData(GradioModel):
 
 @dataclasses.dataclass
 class Eraser:
+    """
+    A dataclass for specifying options for the eraser tool in the ImageEditor component. An instance of this class can be passed to the `eraser` parameter of `gr.ImageEditor`.
+    Parameters:
+        default_size: The default radius, in pixels, of the eraser tool. Defaults to "auto" in which case the radius is automatically determined based on the size of the image (generally 1/50th of smaller dimension).
+    """
+
     default_size: int | Literal["auto"] = "auto"
 
 
 @dataclasses.dataclass
 class Brush(Eraser):
+    """
+    A dataclass for specifying options for the brush tool in the ImageEditor component. An instance of this class can be passed to the `brush` parameter of `gr.ImageEditor`.
+    Parameters:
+        default_size: The default radius, in pixels, of the brush tool. Defaults to "auto" in which case the radius is automatically determined based on the size of the image (generally 1/50th of smaller dimension).
+        colors: A list of colors to make available to the user when using the brush. Defaults to a list of 5 colors.
+        default_color: The default color of the brush. Defaults to the first color in the `colors` list.
+        color_mode: If set to "fixed", user can only select from among the colors in `colors`. If "defaults", the colors in `colors` are provided as a default palette, but the user can also select any color using a color picker.
+    """
+
     colors: Union[
         list[str],
         str,
@@ -68,11 +92,10 @@ def __post_init__(self):
 class ImageEditor(Component):
     """
     Creates an image component that can be used to upload and edit images (as an input) or display images (as an output).
-    Preprocessing: passes the uploaded image as a dictionary of {numpy.array}, {PIL.Image} or {str} filepath depending on `type`.
-    Postprocessing: expects a dictionary of {numpy.array}, {PIL.Image} or {str} or {pathlib.Path} filepath to an image and displays the image.
-    Examples-format: a {str} local filepath or URL to an image.
-    Demos: image_mod, image_mod_default_image
-    Guides: image-classification-in-pytorch, image-classification-in-tensorflow, image-classification-with-vision-transformers, building-a-pictionary_app, create-your-own-friends-with-a-gan
+    Preprocessing: passes the uploaded images as a dictionary with keys: `background`, `layers`, and `composite`. The values corresponding to `background` and `composite` are images, while `layers` is a list of images. The images are of type PIL.Image, np.array, or str filepath, depending on the `type` parameter.
+    Postprocessing: expects a dictionary with keys: `background`, `layers`, and `composite`. The values corresponding to `background` and `composite` should be images or None, while `layers` should be a list of images. Images can be of type PIL.Image, np.array, or str filepath/URL. Or, the value can be simply a single image, in which case it will be used as the background.
+    Examples-format: a dictionary with keys: `background`, `layers`, and `composite`. The values corresponding to `background` and `composite` should be strings or None, while `layers` should be a list of strings. The image corresponding to `composite`, if not None, is used as the example image. Otherwise, the image corresonding to `background` is used. The strings should be filepaths or URLs. Or, the value can be simply a single string filepath/URL to an image, which is used directly as the example image.
+    Demos: image_editor
     """
 
     EVENTS = [
@@ -85,7 +108,7 @@ class ImageEditor(Component):
 
     def __init__(
         self,
-        value: str | _Image.Image | np.ndarray | None = None,
+        value: EditorValue | ImageType | None = None,
         *,
         height: int | str | None = None,
         width: int | str | None = None,
@@ -115,17 +138,17 @@ def __init__(
         _selectable: bool = False,
         crop_size: tuple[int | float, int | float] | str | None = None,
         transforms: Iterable[Literal["crop"]] = ("crop",),
-        eraser: Eraser | None | bool = None,
-        brush: Brush | None | bool = None,
+        eraser: Eraser | None | Literal[False] = None,
+        brush: Brush | None | Literal[False] = None,
     ):
         """
         Parameters:
-            value: A PIL Image, numpy array, path or URL for the default value that Image component is going to take. If callable, the function will be called whenever the app loads to set the initial value of the component.
-            height: The height of the displayed image, specified in pixels if a number is passed, or in CSS units if a string is passed.
-            width: The width of the displayed image, specified in pixels if a number is passed, or in CSS units if a string is passed.
+            value: Optional initial image(s) to populate the image editor. Should be a dictionary with keys: `background`, `layers`, and `composite`. The values corresponding to `background` and `composite` should be images or None, while `layers` should be a list of images. Images can be of type PIL.Image, np.array, or str filepath/URL. Or, the value can be a callable, in which case the function will be called whenever the app loads to set the initial value of the component.
+            height: The height of the displayed images, specified in pixels if a number is passed, or in CSS units if a string is passed.
+            width: The width of the displayed images, specified in pixels if a number is passed, or in CSS units if a string is passed.
             image_mode: "RGB" if color, or "L" if black and white. See https://pillow.readthedocs.io/en/stable/handbook/concepts.html for other supported image modes and their meaning.
-            sources: List of sources for the image. "upload" creates a box where user can drop an image file, "webcam" allows user to take snapshot from their webcam, "clipboard" allows users to paste an image from the clipboard.
-            type: The format the image is converted to before being passed into the prediction function. "numpy" converts the image to a numpy array with shape (height, width, 3) and values from 0 to 255, "pil" converts the image to a PIL image object, "filepath" passes a str path to a temporary file containing the image.
+            sources: List of sources that can be used to set the background image. "upload" creates a box where user can drop an image file, "webcam" allows user to take snapshot from their webcam, "clipboard" allows users to paste an image from the clipboard.
+            type: The format the images are converted to before being passed into the prediction function. "numpy" converts the images to numpy arrays with shape (height, width, 3) and values from 0 to 255, "pil" converts the images to PIL image objects, "filepath" passes images as str filepaths to temporary copies of the images.
             label: The label for this component. Appears above the component and is also used as the header if there are a table of examples for this component. If None and used in a `gr.Interface`, the label will be the name of the parameter this component is assigned to.
             every: If `value` is a callable, run the function 'every' number of seconds while the client connection is open. Has no effect otherwise. Queue must be enabled. The event can be accessed (e.g. to cancel it) via this component's .load_event attribute.
             show_label: if True, will display label.
@@ -142,6 +165,8 @@ def __init__(
             show_share_button: If True, will show a share icon in the corner of the component that allows user to share outputs to Hugging Face Spaces Discussions. If False, icon does not appear. If set to None (default behavior), then the icon appears if this Gradio app is launched on Spaces, but not otherwise.
             crop_size: The size of the crop box in pixels. If a tuple, the first value is the width and the second value is the height. If a string, the value must be a ratio in the form `width:height` (e.g. "16:9").
             transforms: The transforms tools to make available to users. "crop" allows the user to crop the image.
+            eraser: The options for the eraser tool in the image editor. Should be an instance of the `gr.Eraser` class, or None to use the default settings. Can also be False to hide the eraser tool.
+            brush: The options for the brush tool in the image editor. Should be an instance of the `gr.Brush` class, or None to use the default settings. Can also be False to hide the brush tool, which will also hide the eraser tool.
         """
         self._selectable = _selectable
         self.mirror_webcam = mirror_webcam
@@ -174,8 +199,8 @@ def __init__(
 
         self.crop_size = crop_size
         self.transforms = transforms
-        self.eraser = eraser if eraser is not None and eraser is not True else Eraser()
-        self.brush = brush if brush is not None and brush is not True else Brush()
+        self.eraser = Eraser() if eraser is None else eraser
+        self.brush = Brush() if brush is None else brush
 
         super().__init__(
             label=label,
@@ -225,38 +250,34 @@ def convert_and_format_image(
             name=name,
         )
 
-    def preprocess(self, x: EditorData | None) -> EditorValue | None:
-        """
-        Parameters:
-            x: FileData containing an image path pointing to the user's image
-        Returns:
-            image in requested format, or (if tool == "sketch") a dict of image and mask in requested format
-        """
-        if x is None:
-            return x
+    def preprocess(self, payload: EditorData | None) -> EditorValue | None:
+        if payload is None:
+            return payload
 
-        bg = self.convert_and_format_image(x.background)
+        bg = self.convert_and_format_image(payload.background)
         layers = (
-            [self.convert_and_format_image(layer) for layer in x.layers]
-            if x.layers
+            [self.convert_and_format_image(layer) for layer in payload.layers]
+            if payload.layers
             else None
         )
-        composite = self.convert_and_format_image(x.composite)
+        composite = self.convert_and_format_image(payload.composite)
         return {
             "background": bg,
             "layers": [x for x in layers if x is not None] if layers else [],
             "composite": composite,
         }
 
-    def postprocess(self, y: EditorValue | None) -> EditorData | None:
-        """
-        Parameters:
-            y: image as a numpy array, PIL Image, string/Path filepath, or string URL
-        Returns:
-            base64 url data
-        """
-        if y is None:
+    def postprocess(self, value: EditorValue | ImageType | None) -> EditorData | None:
+        if value is None:
             return None
+        elif isinstance(value, dict):
+            pass
+        elif isinstance(value, (np.ndarray, _Image.Image, str)):
+            value = {"background": value, "layers": [], "composite": value}
+        else:
+            raise ValueError(
+                "The value to `gr.ImageEditor` must be a dictionary of images or a single image."
+            )
 
         layers = (
             [
@@ -266,37 +287,63 @@ def postprocess(self, y: EditorValue | None) -> EditorData | None:
                         self.GRADIO_CACHE,
                     )
                 )
-                for layer in y["layers"]
+                for layer in value["layers"]
             ]
-            if y["layers"]
+            if value["layers"]
             else []
         )
 
         return EditorData(
             background=FileData(
-                path=image_utils.save_image(y["background"], self.GRADIO_CACHE)
+                path=image_utils.save_image(value["background"], self.GRADIO_CACHE)
             )
-            if y["background"] is not None
+            if value["background"] is not None
             else None,
             layers=layers,
             composite=FileData(
                 path=image_utils.save_image(
-                    cast(Union[np.ndarray, _Image.Image, str], y["composite"]),
+                    cast(Union[np.ndarray, _Image.Image, str], value["composite"]),
                     self.GRADIO_CACHE,
                 )
             )
-            if y["composite"] is not None
+            if value["composite"] is not None
             else None,
         )
 
-    def as_example(self, input_data: str | Path | None) -> str:
+    def as_example(
+        self, input_data: EditorExampleValue | str | None
+    ) -> EditorExampleValue | None:
+        def resolve_path(file_or_url: str | None) -> str | None:
+            if file_or_url is None:
+                return None
+            input_data = str(file_or_url)
+            # If an externally hosted image or a URL, don't convert to absolute path
+            if self.proxy_url or client_utils.is_http_url_like(input_data):
+                return input_data
+            return str(utils.abspath(input_data))
+
         if input_data is None:
-            return ""
-        input_data = str(input_data)
-        # If an externally hosted image or a URL, don't convert to absolute path
-        if self.proxy_url or client_utils.is_http_url_like(input_data):
-            return input_data
-        return str(utils.abspath(input_data))
+            return None
+        elif isinstance(input_data, str):
+            input_data = {
+                "background": input_data,
+                "layers": [],
+                "composite": input_data,
+            }
+
+        input_data["background"] = resolve_path(input_data["background"])
+        input_data["layers"] = (
+            [resolve_path(f) for f in input_data["layers"]]
+            if input_data["layers"]
+            else []
+        )
+        input_data["composite"] = resolve_path(input_data["composite"])
+
+        return input_data
 
     def example_inputs(self) -> Any:
-        return "https://raw.githubusercontent.com/gradio-app/gradio/main/test/test_files/bus.png"
+        return {
+            "background": "https://raw.githubusercontent.com/gradio-app/gradio/main/test/test_files/bus.png",
+            "layers": [],
+            "composite": None,
+        }

js/audio/player/AudioPlayer.svelte

@@ -3,7 +3,7 @@
 	import { Music } from "@gradio/icons";
 	import type { I18nFormatter } from "@gradio/utils";
 	import WaveSurfer from "wavesurfer.js";
-	import { skipAudio, process_audio } from "../shared/utils";
+	import { skip_audio, process_audio } from "../shared/utils";
 	import WaveformControls from "../shared/WaveformControls.svelte";
 	import { Empty } from "@gradio/atoms";
 	import { resolve_wasm_src } from "@gradio/wasm/svelte";
@@ -33,7 +33,7 @@
 
 	let timeRef: HTMLTimeElement;
 	let durationRef: HTMLTimeElement;
-	let audioDuration: number;
+	let audio_duration: number;
 
 	let trimDuration = 0;
 
@@ -74,7 +74,7 @@
 	}
 
 	$: waveform?.on("decode", (duration: any) => {
-		audioDuration = duration;
+		audio_duration = duration;
 		durationRef && (durationRef.textContent = formatTime(duration));
 	});
 
@@ -135,9 +135,9 @@
 		window.addEventListener("keydown", (e) => {
 			if (!waveform || show_volume_slider) return;
 			if (e.key === "ArrowRight" && mode !== "edit") {
-				skipAudio(waveform, 0.1);
+				skip_audio(waveform, 0.1);
 			} else if (e.key === "ArrowLeft" && mode !== "edit") {
-				skipAudio(waveform, -0.1);
+				skip_audio(waveform, -0.1);
 			}
 		});
 	});
@@ -178,7 +178,7 @@
 				{container}
 				{waveform}
 				{playing}
-				{audioDuration}
+				{audio_duration}
 				{i18n}
 				{interactive}
 				{handle_trim_audio}

js/audio/recorder/AudioRecorder.svelte

@@ -3,7 +3,7 @@
 	import type { I18nFormatter } from "@gradio/utils";
 	import { createEventDispatcher } from "svelte";
 	import WaveSurfer from "wavesurfer.js";
-	import { skipAudio, process_audio } from "../shared/utils";
+	import { skip_audio, process_audio } from "../shared/utils";
 	import WSRecord from "wavesurfer.js/dist/plugins/record.js";
 	import WaveformControls from "../shared/WaveformControls.svelte";
 	import WaveformRecordControls from "../shared/WaveformRecordControls.svelte";
@@ -35,7 +35,7 @@
 	// timestamps
 	let timeRef: HTMLTimeElement;
 	let durationRef: HTMLTimeElement;
-	let audioDuration: number;
+	let audio_duration: number;
 	let seconds = 0;
 	let interval: NodeJS.Timeout;
 	let timing = false;
@@ -102,7 +102,7 @@
 	});
 
 	$: recordingWaveform?.on("decode", (duration: any) => {
-		audioDuration = duration;
+		audio_duration = duration;
 		durationRef && (durationRef.textContent = format_time(duration));
 	});
 
@@ -187,9 +187,9 @@
 
 		window.addEventListener("keydown", (e) => {
 			if (e.key === "ArrowRight") {
-				skipAudio(recordingWaveform, 0.1);
+				skip_audio(recordingWaveform, 0.1);
 			} else if (e.key === "ArrowLeft") {
-				skipAudio(recordingWaveform, -0.1);
+				skip_audio(recordingWaveform, -0.1);
 			}
 		});
 	});
@@ -234,7 +234,7 @@
 			bind:waveform={recordingWaveform}
 			container={recordingContainer}
 			{playing}
-			{audioDuration}
+			{audio_duration}
 			{i18n}
 			interactive={true}
 			{handle_trim_audio}