Gradio 代理 & MCP 黑客马拉松

获奖者
Gradio logo
  1. 组件
  2. ImageEditor

初次接触 Gradio？从这里开始：入门

查看 发布历史

←

图像

图像滑块

→

ImageEditor

gradio.ImageEditor(···)
import gradio as gr with gr.Blocks() as demo: gr.ImageEditor() demo.launch()

描述

创建一个图像组件，作为输入时，可用于上传和编辑图像，使用画笔、笔触、裁剪和图层等简单编辑工具。或者，作为输出时，此组件可用于显示图像。

行为

作为输入组件: 将上传的图像作为 EditorValue 的实例传递，它是一个 dict，包含键：'background'、'layers' 和 'composite'。'background' 和 'composite' 对应的值是图像，而 'layers' 是一个图像 list。根据 type 参数，图像类型可以是 PIL.Image、np.array 或 str 文件路径。

您的函数应接受这些类型之一
def predict(
	value: EditorValue | None
)
	...

作为输出组件: 期望一个 EditorValue，它是一个字典，包含键：'background'、'layers' 和 'composite'。'background' 和 'composite' 对应的值应为图像或 None，而 layers 应为图像列表。图像类型可以是 PIL.Image、np.array 或 str 文件路径/URL。或者，该值可以是一个简单的单张图像（ImageType），在这种情况下它将用作背景。

您的函数应返回这些类型之一
def predict(···) -> EditorValue | ImageType | None
	...	
	return value

初始化

参数
🔗 
value: EditorValue | ImageType | None
默认 = None

用于填充图像编辑器的可选初始图像。应为字典，包含键：`background`、`layers` 和 `composite`。`background` 和 `composite` 对应的值应为图像或 None，而 `layers` 应为图像列表。图像类型可以是 PIL.Image、np.array 或 str 文件路径/URL。或者，该值可以是一个可调用对象，在这种情况下，每当应用加载时，该函数将被调用以设置组件的初始值。

🔗 
height: int | str | None
默认 = None

组件的高度，如果传递数字则以像素为单位，如果传递字符串则以 CSS 单位表示。这不会影响预处理的图像文件或 numpy 数组，但会影响显示的图像。请注意与 `canvas_size` 参数的冲突值。如果 `canvas_size` 大于高度，编辑画布将无法适应组件。

🔗 
width: int | str | None
默认 = None

组件的宽度，如果传递数字则以像素为单位，如果传递字符串则以 CSS 单位表示。这不会影响预处理的图像文件或 numpy 数组，但会影响显示的图像。请注意与 `canvas_size` 参数的冲突值。如果 `canvas_size` 大于高度，编辑画布将无法适应组件。

🔗 
image_mode: Literal['1', 'L', 'P', 'RGB', 'RGBA', 'CMYK', 'YCbCr', 'LAB', 'HSV', 'I', 'F']
默认 = "RGBA"

如果为彩色，则为“RGB”，如果为黑白，则为“L”。有关其他支持的图像模式及其含义，请参阅 https://pillow.ac.cn/en/stable/handbook/concepts.html。

🔗 
sources: Iterable[Literal['upload', 'webcam', 'clipboard']] | Literal['upload', 'webcam', 'clipboard'] | None
默认 = ('upload', 'webcam', 'clipboard')

可用于设置背景图像的源列表。“upload”创建一个用户可以放置图像文件的框，“webcam”允许用户从网络摄像头拍摄快照，“clipboard”允许用户从剪贴板粘贴图像。

🔗 
type: Literal['numpy', 'pil', 'filepath']
默认 = "numpy"

图像在传递到预测函数之前转换的格式。“numpy”将图像转换为形状为 (height, width, 3) 且值范围为 0 到 255 的 numpy 数组，“pil”将图像转换为 PIL 图像对象，“filepath”将图像作为字符串文件路径传递给图像的临时副本。

🔗 
label: str | I18nData | None
默认 = None

此组件的标签。显示在组件上方，如果此组件有示例表格，也用作标题。如果为 None 并在 `gr.Interface` 中使用，则标签将是此组件所分配参数的名称。

🔗 
every: Timer | float | None
默认 = None

如果 `value` 是一个函数（否则无效），则持续调用 `value` 以重新计算它。可以提供一个 Timer，其刻度会重置 `value`，或者一个浮点数，为重置 Timer 提供常规间隔。

🔗 
inputs: Component | list[Component] | set[Component] | None
默认 = None

用作计算 `value` 的输入组件（如果 `value` 是函数，否则无效）。每当输入改变时，`value` 都会重新计算。

🔗 
show_label: bool | None
默认 = None

如果为 True，将显示标签。

🔗 
show_download_button: bool
默认 = True

如果为 True，将显示下载图像按钮。

🔗 
container: bool
默认 = True

如果为 True，将把组件放置在一个容器中——在边框周围提供一些额外填充。

🔗 
scale: int | None
默认 = None

与相邻组件的相对大小。例如，如果组件 A 和 B 在一行中，A 的 scale=2，B 的 scale=1，则 A 的宽度将是 B 的两倍。应为整数。scale 适用于行，以及在 Blocks 中 `fill_height=True` 的顶级组件。

🔗 
min_width: int
默认 = 160

最小像素宽度，如果屏幕空间不足以满足此值，则会换行。如果某个 scale 值导致此组件的宽度小于 `min_width`，则将首先遵循 `min_width` 参数。

🔗 
interactive: bool | None
默认 = None

如果为 True，将允许用户上传和编辑图像；如果为 False，则只能用于显示图像。如果未提供，则根据组件是用作输入还是输出进行推断。

🔗 
visible: bool
默认 = True

如果为 False，组件将隐藏。

🔗 
elem_id: str | None
默认 = None

一个可选字符串，作为此组件在 HTML DOM 中的 id。可用于定位 CSS 样式。

🔗 
elem_classes: list[str] | str | None
默认 = None

一个可选的字符串列表，作为此组件在 HTML DOM 中的类。可用于定位 CSS 样式。

🔗 
render: bool
默认 = True

如果为 False，组件将不会在 Blocks 上下文中渲染。如果目的是现在分配事件监听器但稍后渲染组件，则应使用此选项。

🔗 
key: int | str | tuple[int | str, ...] | None
默认 = None

在 `gr.render` 中，跨重新渲染具有相同 `key` 的组件被视为同一组件，而不是新组件。'preserved_by_key' 中设置的属性不会在重新渲染时重置。

🔗 
preserved_by_key: list[str] | str | None
默认 = "value"

此组件构造函数中的参数列表。在 `gr.render()` 函数中，如果组件使用相同的 `key` 重新渲染，则这些（且仅这些）参数将在 UI 中保留（如果它们已被用户或事件监听器更改），而不是根据构造函数中提供的值重新渲染。

🔗 
placeholder: str | None
默认 = None

上传区域的自定义文本。提供时会覆盖默认的上传消息。接受换行符和 `#` 来指定标题。

🔗 
mirror_webcam: bool | None
默认 = None
🔗 
show_share_button: bool | None
默认 = None

如果为 True，将在组件角落显示一个分享图标，允许用户将输出分享到 Hugging Face Spaces Discussions。如果为 False，则图标不显示。如果设置为 None（默认行为），则当此 Gradio 应用在 Spaces 上启动时，图标才会显示，否则不显示。

🔗 
crop_size: tuple[int | float, int | float] | str | None
默认 = None

已弃用。曾用于设置 `canvas_size` 参数。

🔗 
transforms: Iterable[Literal['crop', 'resize']] | None
默认 = ('crop', 'resize')

可供用户使用的变换工具。“crop”允许用户裁剪图像。

🔗 
eraser: Eraser | None | Literal[False]
默认 = None

图像编辑器中橡皮擦工具的选项。应为 `gr.Eraser` 类的一个实例，或 None 以使用默认设置。也可以设置为 False 以隐藏橡皮擦工具。请参阅 `gr.Eraser` 文档。

🔗 
brush: Brush | None | Literal[False]
默认 = None

图像编辑器中画笔工具的选项。应为 `gr.Brush` 类的一个实例，或 None 以使用默认设置。也可以设置为 False 以隐藏画笔工具，这也会隐藏橡皮擦工具。请参阅 `gr.Brush` 文档。

🔗 
format: str
默认 = "webp"

如果图像尚未具有有效格式（例如，如果图像作为 numpy 数组或 PIL 图像返回到前端），则保存图像的格式。该格式应受 PIL 库支持。此参数对 SVG 文件无效。

🔗 
layers: bool | LayerOptions
默认 = True

图像编辑器中图层工具的选项。可以是布尔值或 `gr.LayerOptions` 类的一个实例。如果为 True，将允许用户向图像添加额外图层。如果为 False，则图层选项将被隐藏。如果是 `gr.LayerOptions` 的实例，它将用于配置图层工具。请参阅 `gr.LayerOptions` 文档。

🔗 
canvas_size: tuple[int, int]
默认 = (800, 800)

画布的初始尺寸（像素）。第一个值是宽度，第二个值是高度。如果 `fixed_canvas` 为 `True`，上传的图像将被重新缩放以适应画布尺寸，同时保持纵横比。否则，画布尺寸将根据上传图像的尺寸进行更改。

🔗 
fixed_canvas: bool
默认 = False

如果为 True，画布尺寸将不会根据背景图像的尺寸而改变，图像将被重新缩放以适应（同时保持纵横比）并放置在画布中心。

🔗 
show_fullscreen_button: bool
默认 = True

如果为 True，将显示按钮以全屏模式查看图像。

🔗 
webcam_options: WebcamOptions | None
默认 = None

图像编辑器中网络摄像头工具的选项。可以是 `gr.WebcamOptions` 类的一个实例，或 None 以使用默认设置。请参阅 `gr.WebcamOptions` 文档。

快捷方式

类 界面字符串快捷方式 初始化

gradio.ImageEditor

"imageeditor"

 使用默认值

gradio.Sketchpad

"sketchpad"

 使用 sources=(), brush=Brush(colors=["#000000"], color_mode="fixed")

gradio.Paint

"paint"

 使用 sources=()

gradio.ImageMask

"imagemask"

 使用 brush=Brush(colors=["#000000"], color_mode="fixed")

演示

import gradio as gr
import time


def sleep(im):
    time.sleep(5)
    return [im["background"], im["layers"][0], im["layers"][1], im["composite"]]


def predict(im):
    return im["composite"]


with gr.Blocks() as demo:
    with gr.Row():
        im = gr.ImageEditor(
            type="numpy",
            crop_size="1:1",
        )
        im_preview = gr.Image()
    n_upload = gr.Number(0, label="Number of upload events", step=1)
    n_change = gr.Number(0, label="Number of change events", step=1)
    n_input = gr.Number(0, label="Number of input events", step=1)

    im.upload(lambda x: x + 1, outputs=n_upload, inputs=n_upload)
    im.change(lambda x: x + 1, outputs=n_change, inputs=n_change)
    im.input(lambda x: x + 1, outputs=n_input, inputs=n_input)
    im.change(predict, outputs=im_preview, inputs=im, show_progress="hidden")

if __name__ == "__main__":
    demo.launch()

事件监听器

描述

事件监听器允许您响应用户与您在 Gradio Blocks 应用中定义的 UI 组件的交互。当用户与某个元素交互时，例如更改滑块值或上传图像，就会调用一个函数。

支持的事件监听器

ImageEditor 组件支持以下事件监听器。每个事件监听器都接受相同的参数，这些参数在下面的事件参数表中列出。

监听器 描述

ImageEditor.clear(fn, ···)

当用户使用组件的清除按钮清除 ImageEditor 时，此监听器被触发。

ImageEditor.change(fn, ···)

当 ImageEditor 的值发生变化时触发，这可能是由于用户输入（例如用户在文本框中输入）或由于函数更新（例如图像从事件触发器的输出接收值）。有关仅由用户输入触发的监听器，请参阅 .input()。

ImageEditor.input(fn, ···)

当用户更改 ImageEditor 的值时，此监听器被触发。

ImageEditor.select(fn, ···)

当用户选择或取消选择 ImageEditor 时触发的事件监听器。使用事件数据 gradio.SelectData 来携带 value，指代 ImageEditor 的标签，以及 selected，指代 ImageEditor 的状态。有关如何使用此事件数据，请参阅 EventData 文档。

ImageEditor.upload(fn, ···)

当用户将文件上传到 ImageEditor 时，此监听器被触发。

ImageEditor.apply(fn, ···)

当用户通过集成 UI 操作对 ImageEditor 应用更改时，此监听器被触发。

事件参数

参数
🔗 
fn: Callable | None | Literal['decorator']
默认 = "decorator"

当此事件触发时要调用的函数。通常是机器学习模型的预测函数。函数的每个参数对应一个输入组件，函数应返回单个值或值的元组，元组中的每个元素对应一个输出组件。

🔗 
inputs: Component | BlockContext | list[Component | BlockContext] | Set[Component | BlockContext] | None
默认 = None

用作输入的 gradio.components 列表。如果函数不接受任何输入，则应为空列表。

🔗 
outputs: Component | BlockContext | list[Component | BlockContext] | Set[Component | BlockContext] | None
默认 = None

用作输出的 gradio.components 列表。如果函数不返回任何输出，则应为空列表。

🔗 
api_name: str | None | Literal[False]
默认 = None

定义端点在 API 文档中如何显示。可以是字符串、None 或 False。如果设置为字符串，端点将以给定名称在 API 文档中公开。如果为 None（默认），则函数名称将用作 API 端点。如果为 False，则端点不会在 API 文档中公开，并且下游应用程序（包括那些 `gr.load` 此应用程序的）将无法使用此事件。

🔗 
scroll_to_output: bool
默认 = False

如果为 True，完成时将滚动到输出组件。

🔗 
show_progress: Literal['full', 'minimal', 'hidden']
默认 = "full"

事件运行时如何显示进度动画：“full”显示一个旋转器，覆盖输出组件区域以及右上角的运行时显示；“minimal”仅显示运行时显示；“hidden”完全不显示进度动画。

🔗 
show_progress_on: Component | list[Component] | None
默认 = None

显示进度动画的组件或组件列表。如果为 None，则会在所有输出组件上显示进度动画。

🔗 
queue: bool
默认 = True

如果为 True，并且队列已启用，则会将请求放入队列。如果为 False，即使队列已启用，也不会将此事件放入队列。如果为 None，将使用 Gradio 应用程序的队列设置。

🔗 
batch: bool
默认 = False

如果为 True，则函数应处理一批输入，这意味着它应接受每个参数的输入值列表。这些列表应具有相同长度（且最大长度为 `max_batch_size`）。然后函数*必须*返回一个列表元组（即使只有一个输出组件），元组中的每个列表对应一个输出组件。

🔗 
max_batch_size: int
默认 = 4

如果从队列调用此事件，最大批处理输入数量（仅当 `batch=True` 时相关）

🔗 
preprocess: bool
默认 = True

如果为 False，在运行 'fn' 之前将不运行组件数据预处理（例如，如果使用 `Image` 组件调用此方法，则将其保留为 base64 字符串）。

🔗 
postprocess: bool
默认 = True

如果为 False，在将 'fn' 输出返回到浏览器之前将不运行组件数据后处理。

🔗 
cancels: dict[str, Any] | list[dict[str, Any]] | None
默认 = None

触发此监听器时要取消的其他事件列表。例如，设置 `cancels=[click_event]` 将取消 `click_event`，其中 `click_event` 是另一个组件 `.click` 方法的返回值。尚未运行的函数（或正在迭代的生成器）将被取消，但当前正在运行的函数将被允许完成。

🔗 
trigger_mode: Literal['once', 'multiple', 'always_last'] | None
默认 = None

如果为“once”（除 `.change()` 之外所有事件的默认值），则在事件待处理期间不允许任何提交。如果设置为“multiple”，则在待处理期间允许无限次提交，“always_last”（`.change()` 和 `.key_up()` 事件的默认值）则允许在待处理事件完成后进行第二次提交。

🔗 
js: str | Literal[True] | None
默认 = None

在运行 'fn' 之前要运行的可选前端 js 方法。js 方法的输入参数是 'inputs' 和 'outputs' 的值，返回值应为输出组件的值列表。

🔗 
concurrency_limit: int | None | Literal['default']
默认 = "default"

如果设置，这是此事件可以同时运行的最大数量。可以设置为 None 表示没有并发限制（此事件可以同时运行任意数量）。设置为“default”以使用默认并发限制（由 `Blocks.queue()` 中的 `default_concurrency_limit` 参数定义，其本身默认为 1）。

🔗 
concurrency_id: str | None
默认 = None

如果设置，这是并发组的 ID。具有相同 `concurrency_id` 的事件将受最低并发限制的限制。

🔗 
show_api: bool
默认 = True

是否在 Gradio 应用的“view API”页面或 Gradio 客户端的“.view_api()”方法中显示此事件。与将 `api_name` 设置为 False 不同，将 `show_api` 设置为 False 仍将允许下游应用和客户端使用此事件。如果 `fn` 为 None，`show_api` 将自动设置为 False。

🔗 
time_limit: int | None
默认 = None
🔗 
stream_every: float
默认 = 0.5
🔗 
like_user_message: bool
默认 = False
🔗 
key: int | str | tuple[int | str, ...] | None
默认 = None

此事件监听器在 @gr.render() 中使用的唯一键。如果设置，当键相同时，此值将标识跨重新渲染的事件是否相同。

辅助类

画笔

gradio.Brush(···)

描述

一个数据类，用于指定 ImageEditor 组件中画笔工具的选项。此类的实例可以传递给 gr.ImageEditor 的 brush 参数。

初始化

参数
🔗 
default_size: int | Literal['auto']
默认 = "auto"

画笔工具的默认半径（像素）。默认为“auto”，在这种情况下，半径会根据图像大小自动确定（通常是较小尺寸的 1/50）。

🔗 
colors: list[str | tuple[str, float]] | str | tuple[str, float] | None
默认 = None

使用画笔时可供用户选择的颜色列表。默认为包含 5 种颜色的列表。

🔗 
default_color: str | tuple[str, float] | None
默认 = None

画笔的默认颜色。默认为 `colors` 列表中的第一个颜色。

🔗 
color_mode: Literal['fixed', 'defaults']
默认 = "defaults"

如果设置为“fixed”，用户只能从 `colors` 中的颜色中选择。如果设置为“defaults”，`colors` 中的颜色将作为默认调色板提供，但用户也可以使用颜色选择器选择任何颜色。

橡皮擦

gradio.Eraser(···)

描述

一个数据类，用于指定 ImageEditor 组件中橡皮擦工具的选项。此类的实例可以传递给 gr.ImageEditor 的 eraser 参数。

初始化

参数
🔗 
default_size: int | Literal['auto']
默认 = "auto"

橡皮擦工具的默认半径（像素）。默认为“auto”，在这种情况下，半径会根据图像大小自动确定（通常是较小尺寸的 1/50）。

图层选项

gradio.LayerOptions(···)

描述

一个数据类，用于指定 ImageEditor 组件中图层工具的选项。此类的实例可以传递给 gr.ImageEditor 的 layers 参数。

初始化

参数
🔗 
allow_additional_layers: bool
默认 = True

如果为 True，用户可以向图像添加额外图层。如果为 False，则不显示添加图层按钮。

🔗 
layers: list[str] | None
默认 = None

使用图层工具时可供用户选择的图层列表。必须提供一个图层，如果列表长度为 0，则会自动生成一个图层。

🔗 
disabled: bool
默认 = False

网络摄像头选项

gradio.WebcamOptions(···)

描述

一个数据类，用于指定 ImageEditor 组件中网络摄像头工具的选项。此类的实例可以传递给 gr.ImageEditor 的 webcam_options 参数。

初始化

参数
🔗 
mirror: bool
默认 = True

如果为 True，网络摄像头将镜像显示。

🔗 
constraints: dict[str, Any] | None
默认 = None

网络摄像头的约束字典。

←

图像

图像滑块

→