<!-- # hard line break macro for HTML -->

# fiftyone.operators.panel

FiftyOne panels.

Copyright 2017-2026, Voxel51, Inc.
<br/>
[voxel51.com](https://voxel51.com/)
<br/>
<br/>

**Classes:**

| [`PanelConfig`](#fiftyone.operators.panel.PanelConfig)(name, label[, help_markdown, ...])   | Configuration for a panel.               |
|---------------------------------------------------------------------------------------------|------------------------------------------|
| [`Panel`](#fiftyone.operators.panel.Panel)([_builtin])                                      | A panel.                                 |
| [`PanelRefBase`](#fiftyone.operators.panel.PanelRefBase)(ctx)                               | Base class for panel state and data.     |
| [`PanelRefState`](#fiftyone.operators.panel.PanelRefState)(ctx)                             | Class representing the state of a panel. |
| [`PanelRefData`](#fiftyone.operators.panel.PanelRefData)(ctx)                               | Class representing the data of a panel.  |
| [`PanelRef`](#fiftyone.operators.panel.PanelRef)(ctx)                                       | Class representing a panel.              |

**Exceptions:**

| [`WriteOnlyError`](#fiftyone.operators.panel.WriteOnlyError)   | Error raised when trying to read a write-only property.   |
|----------------------------------------------------------------|-----------------------------------------------------------|

### *class* fiftyone.operators.panel.PanelConfig(name, label, help_markdown=None, alpha=False, beta=False, is_new=False, category=None, icon=None, light_icon=None, dark_icon=None, allow_multiple=False, surfaces: Literal['grid', 'modal', 'grid modal'] = 'grid', priority=None, \*\*kwargs)

Bases: [`OperatorConfig`](fiftyone.operators.operator.md#fiftyone.operators.operator.OperatorConfig)

Configuration for a panel.

* **Parameters:**
  * **name** – the name of the panel
  * **label** – the display name for the panel
  * **icon** (*None*) – the icon to show in the panel’s tab
  * **light_icon** (*None*) – the icon to show in the panel’s tab when the App is
    in light mode
  * **dark_icon** (*None*) – the icon to show in the panel’s tab when the App is
    in dark mode
  * **allow_multiple** (*False*) – whether to allow multiple instances of the
    panel to be opened
  * **surfaces** ( *"grid"*) – the surfaces on which the panel can be displayed
  * **help_markdown** (*None*) – a markdown string to display in the panel’s help
    tooltip
  * **category** (*Category*) – the category id of the panel
  * **priority** (*None*) – the priority of the panel for sorting in the UI

**Methods:**

| [`to_json`](#fiftyone.operators.panel.PanelConfig.to_json)()   |    |
|----------------------------------------------------------------|----|

**Attributes:**

| [`risk_level`](#fiftyone.operators.panel.PanelConfig.risk_level)   | The declared `RiskLevel` for this operator.   |
|--------------------------------------------------------------------|-----------------------------------------------|

#### to_json()

#### *property* risk_level

The declared `RiskLevel` for this operator.

### *class* fiftyone.operators.panel.Panel(\_builtin=False)

Bases: [`Operator`](fiftyone.operators.operator.md#fiftyone.operators.operator.Operator)

A panel.

**Methods:**

| [`render`](#fiftyone.operators.panel.Panel.render)(ctx)                                       | Defines the panel's layout and events.          |
|-----------------------------------------------------------------------------------------------|-------------------------------------------------|
| [`resolve_input`](#fiftyone.operators.panel.Panel.resolve_input)(ctx)                         | Returns the resolved input property.            |
| [`resolve_panel_config`](#fiftyone.operators.panel.Panel.resolve_panel_config)()              | Returns the registration config for this panel. |
| [`on_startup`](#fiftyone.operators.panel.Panel.on_startup)(ctx)                               |                                                 |
| [`on_load`](#fiftyone.operators.panel.Panel.on_load)(ctx)                                     |                                                 |
| [`execute`](#fiftyone.operators.panel.Panel.execute)(ctx)                                     | Executes the operator.                          |
| [`add_secrets`](#fiftyone.operators.panel.Panel.add_secrets)(secrets)                         | Adds secrets to the operator.                   |
| [`method_to_uri`](#fiftyone.operators.panel.Panel.method_to_uri)(method_name)                 | Converts a method name to a URI.                |
| [`resolve_delegation`](#fiftyone.operators.panel.Panel.resolve_delegation)(ctx)               | Returns the resolved *forced* delegation flag.  |
| [`resolve_execution_options`](#fiftyone.operators.panel.Panel.resolve_execution_options)(ctx) | Returns the resolved execution options.         |
| [`resolve_output`](#fiftyone.operators.panel.Panel.resolve_output)(ctx)                       | Returns the resolved output property.           |
| [`resolve_placement`](#fiftyone.operators.panel.Panel.resolve_placement)(ctx)                 | Returns the resolved placement of the operator. |
| [`resolve_run_name`](#fiftyone.operators.panel.Panel.resolve_run_name)(ctx)                   | Returns the resolved run name of the operator.  |
| [`resolve_type`](#fiftyone.operators.panel.Panel.resolve_type)(ctx, type)                     | Returns the resolved input or output property.  |
| [`to_json`](#fiftyone.operators.panel.Panel.to_json)()                                        | Returns a JSON representation of the operator.  |

**Attributes:**

| [`builtin`](#fiftyone.operators.panel.Panel.builtin)       | Whether the operator is builtin.                                                                                 |
|------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
| [`config`](#fiftyone.operators.panel.Panel.config)         | The `OperatorConfig` for the operator.                                                                           |
| [`name`](#fiftyone.operators.panel.Panel.name)             |                                                                                                                  |
| [`risk_level`](#fiftyone.operators.panel.Panel.risk_level) | The effective risk level of the operator, which is used by guardrail systems of an agent to classify tool calls. |
| [`uri`](#fiftyone.operators.panel.Panel.uri)               | The unique identifier of the operator: `plugin_name/operator_name`.                                              |

#### render(ctx)

Defines the panel’s layout and events.

This method is called after every panel event is called (on load,
button callback, context change event, etc).

* **Parameters:**
  **ctx** – the [`fiftyone.operators.executor.ExecutionContext`](fiftyone.operators.executor.md#fiftyone.operators.executor.ExecutionContext)
* **Returns:**
  a [`fiftyone.operators.types.Property`](fiftyone.operators.types.md#fiftyone.operators.types.Property)

#### resolve_input(ctx)

Returns the resolved input property.

Subclasses can implement this method to define the inputs to the
operator. This method should never be called directly. Instead
use [`resolve_type()`](#fiftyone.operators.panel.Panel.resolve_type).

By default, this method is called once when the operator is created.
If the operator is dynamic, this method is called each time the input
changes.

* **Parameters:**
  **ctx** – the [`fiftyone.operators.executor.ExecutionContext`](fiftyone.operators.executor.md#fiftyone.operators.executor.ExecutionContext)
* **Returns:**
  a [`fiftyone.operators.types.Property`](fiftyone.operators.types.md#fiftyone.operators.types.Property), or None

#### resolve_panel_config()

Returns the registration config for this panel.

#### on_startup(ctx)

#### on_load(ctx)

#### execute(ctx)

Executes the operator.

Subclasses must implement this method.

* **Parameters:**
  **ctx** – the [`fiftyone.operators.executor.ExecutionContext`](fiftyone.operators.executor.md#fiftyone.operators.executor.ExecutionContext)
* **Returns:**
  JSON serializable data, or None

#### add_secrets(secrets)

Adds secrets to the operator.

* **Parameters:**
  **secrets** – a list of secrets

#### *property* builtin

Whether the operator is builtin.

#### *property* config

The `OperatorConfig` for the operator.

#### method_to_uri(method_name)

Converts a method name to a URI.

* **Parameters:**
  **method_name** – the method name
* **Returns:**
  a URI

#### *property* name

#### resolve_delegation(ctx) → [bool](fiftyone.core.stages.md#fiftyone.core.stages.Exists.bool) | None

Returns the resolved *forced* delegation flag.

Subclasses can implement this method to decide if delegated execution
should be *forced* for the given operation.

* **Parameters:**
  **ctx** – the [`fiftyone.operators.executor.ExecutionContext`](fiftyone.operators.executor.md#fiftyone.operators.executor.ExecutionContext)
* **Returns:**
  whether the operation should be delegated (True), run immediately
  (False), or None to defer to [`resolve_execution_options()`](#fiftyone.operators.panel.Panel.resolve_execution_options) to
  specify the available options

#### resolve_execution_options(ctx)

Returns the resolved execution options.

Subclasses can implement this method to define the execution options
available for the operation.

* **Parameters:**
  **ctx** – the [`fiftyone.operators.executor.ExecutionContext`](fiftyone.operators.executor.md#fiftyone.operators.executor.ExecutionContext)
* **Returns:**
  a [`fiftyone.operators.executor.ExecutionOptions`](fiftyone.operators.executor.md#fiftyone.operators.executor.ExecutionOptions) instance

#### resolve_output(ctx)

Returns the resolved output property.

Subclasses can implement this method to define the outputs of the
operator.

By default, this method is called once when the operator is created.
If the operator is dynamic, this method is called after the operator is
executed.

* **Parameters:**
  **ctx** – the [`fiftyone.operators.executor.ExecutionContext`](fiftyone.operators.executor.md#fiftyone.operators.executor.ExecutionContext)
* **Returns:**
  a [`fiftyone.operators.types.Property`](fiftyone.operators.types.md#fiftyone.operators.types.Property), or None

#### resolve_placement(ctx)

Returns the resolved placement of the operator.

Subclasses can implement this method to define the placement of the
operator.

* **Parameters:**
  **ctx** – the [`fiftyone.operators.executor.ExecutionContext`](fiftyone.operators.executor.md#fiftyone.operators.executor.ExecutionContext)
* **Returns:**
  a [`fiftyone.operators.types.Placement`](fiftyone.operators.types.md#fiftyone.operators.types.Placement), or None

#### resolve_run_name(ctx)

Returns the resolved run name of the operator.

Subclasses can implement this method to define the run name of the
operator.

* **Parameters:**
  **ctx** – the [`fiftyone.operators.executor.ExecutionContext`](fiftyone.operators.executor.md#fiftyone.operators.executor.ExecutionContext)
* **Returns:**
  a string, or None

#### resolve_type(ctx, type)

Returns the resolved input or output property.

* **Parameters:**
  * **ctx** – the [`fiftyone.operators.executor.ExecutionContext`](fiftyone.operators.executor.md#fiftyone.operators.executor.ExecutionContext)
  * **type** – the type of property to resolve, either `"inputs"` or
    `"outputs"`
* **Returns:**
  a [`fiftyone.operators.types.Property`](fiftyone.operators.types.md#fiftyone.operators.types.Property), or None

#### *property* risk_level

The effective risk level of the operator, which is used by guardrail
systems of an agent to classify tool calls.

#### to_json()

Returns a JSON representation of the operator.

* **Returns:**
  a JSON dict

#### *property* uri

The unique identifier of the operator:
`plugin_name/operator_name`.

### *exception* fiftyone.operators.panel.WriteOnlyError

Bases: `Exception`

Error raised when trying to read a write-only property.

**Methods:**

| [`add_note`](#fiftyone.operators.panel.WriteOnlyError.add_note)(object, /)             | Exception.add_note(note) -- add a note to the exception                         |
|----------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| [`with_traceback`](#fiftyone.operators.panel.WriteOnlyError.with_traceback)(object, /) | Exception.with_traceback(tb) -- set self._\_traceback_\_ to tb and return self. |

**Attributes:**

| [`args`](#fiftyone.operators.panel.WriteOnlyError.args)   |    |
|-----------------------------------------------------------|----|

#### add_note(object,)

Exception.add_note(note) –
add a note to the exception

#### args

#### with_traceback(object,)

Exception.with_traceback(tb) –
set self._\_traceback_\_ to tb and return self.

### *class* fiftyone.operators.panel.PanelRefBase(ctx)

Bases: `object`

Base class for panel state and data.

* **Parameters:**
  **ctx** – an [`fiftyone.operators.executor.ExecutionContext`](fiftyone.operators.executor.md#fiftyone.operators.executor.ExecutionContext)

**Methods:**

| [`set`](#fiftyone.operators.panel.PanelRefBase.set)(key[, value])   | Sets some value(s) in the dictionary.   |
|---------------------------------------------------------------------|-----------------------------------------|
| [`get`](#fiftyone.operators.panel.PanelRefBase.get)(key[, default]) | Gets a value from the dictionary.       |
| [`clear`](#fiftyone.operators.panel.PanelRefBase.clear)()           | Clears the dictionary.                  |

#### set(key, value=None)

Sets some value(s) in the dictionary.

* **Parameters:**
  * **key** – a key, `"nested.key.path"`, or dict mapping multiple
    possibly-nested keys to values
  * **value** (*None*) – the value, if key is a string

#### get(key, default=None)

Gets a value from the dictionary.

* **Parameters:**
  * **key** – a key or `"nested.key.path"`
  * **default** (*None*) – a default value if the key is not found
* **Returns:**
  the value

#### clear()

Clears the dictionary.

### *class* fiftyone.operators.panel.PanelRefState(ctx)

Bases: [`PanelRefBase`](#fiftyone.operators.panel.PanelRefBase)

Class representing the state of a panel.

* **Parameters:**
  **ctx** – an [`fiftyone.operators.executor.ExecutionContext`](fiftyone.operators.executor.md#fiftyone.operators.executor.ExecutionContext)

**Methods:**

| [`set`](#fiftyone.operators.panel.PanelRefState.set)(key[, value])   | Sets some panel state.            |
|----------------------------------------------------------------------|-----------------------------------|
| [`clear`](#fiftyone.operators.panel.PanelRefState.clear)()           | Clears the panel state.           |
| [`apply`](#fiftyone.operators.panel.PanelRefState.apply)(path)       | Applies the state to the panel.   |
| [`get`](#fiftyone.operators.panel.PanelRefState.get)(key[, default]) | Gets a value from the dictionary. |

#### set(key, value=None)

Sets some panel state.

* **Parameters:**
  * **key** – a key, `"nested.key.path"`, or dict mapping multiple
    possibly-nested keys to values
  * **value** (*None*) – the value, if key is a string

#### clear()

Clears the panel state.

#### apply(path)

Applies the state to the panel.

* **Parameters:**
  **path** (*str*) – The path to the state.

#### get(key, default=None)

Gets a value from the dictionary.

* **Parameters:**
  * **key** – a key or `"nested.key.path"`
  * **default** (*None*) – a default value if the key is not found
* **Returns:**
  the value

### *class* fiftyone.operators.panel.PanelRefData(ctx)

Bases: [`PanelRefBase`](#fiftyone.operators.panel.PanelRefBase)

Class representing the data of a panel.

* **Parameters:**
  **ctx** – an [`fiftyone.operators.executor.ExecutionContext`](fiftyone.operators.executor.md#fiftyone.operators.executor.ExecutionContext)

**Methods:**

| [`set`](#fiftyone.operators.panel.PanelRefData.set)(key[, value])   | Sets some panel data.             |
|---------------------------------------------------------------------|-----------------------------------|
| [`get`](#fiftyone.operators.panel.PanelRefData.get)(key[, default]) | Gets a value from the dictionary. |
| [`clear`](#fiftyone.operators.panel.PanelRefData.clear)()           | Clears the panel data.            |

#### set(key, value=None)

Sets some panel data.

* **Parameters:**
  * **key** – a key, `"nested.key.path"`, or dict mapping multiple
    possibly-nested keys to values
  * **value** (*None*) – the value, if key is a string

#### get(key, default=None)

Gets a value from the dictionary.

* **Parameters:**
  * **key** – a key or `"nested.key.path"`
  * **default** (*None*) – a default value if the key is not found
* **Returns:**
  the value

#### clear()

Clears the panel data.

### *class* fiftyone.operators.panel.PanelRef(ctx)

Bases: `object`

Class representing a panel.

* **Parameters:**
  **ctx** – an [`fiftyone.operators.executor.ExecutionContext`](fiftyone.operators.executor.md#fiftyone.operators.executor.ExecutionContext)

**Attributes:**

| [`data`](#fiftyone.operators.panel.PanelRef.data)   | Panel data.   |
|-----------------------------------------------------|---------------|
| [`state`](#fiftyone.operators.panel.PanelRef.state) | Panel state.  |
| [`id`](#fiftyone.operators.panel.PanelRef.id)       | Panel ID.     |

**Methods:**

| [`close`](#fiftyone.operators.panel.PanelRef.close)()                       | Closes the panel.            |
|-----------------------------------------------------------------------------|------------------------------|
| [`set_state`](#fiftyone.operators.panel.PanelRef.set_state)(key[, value])   | Sets some panel state.       |
| [`get_state`](#fiftyone.operators.panel.PanelRef.get_state)(key[, default]) | Gets some panel state.       |
| [`set_data`](#fiftyone.operators.panel.PanelRef.set_data)(key[, value])     | Sets some panel data.        |
| [`set_title`](#fiftyone.operators.panel.PanelRef.set_title)(title)          | Sets the title of the panel. |

#### *property* data

Panel data.

#### *property* state

Panel state.

#### *property* id

Panel ID.

#### close()

Closes the panel.

#### set_state(key, value=None)

Sets some panel state.

* **Parameters:**
  * **key** – a key, `"nested.key.path"`, or dict mapping multiple
    possibly-nested keys to values
  * **value** (*None*) – the value, if key is a string

#### get_state(key, default=None)

Gets some panel state.

* **Parameters:**
  * **key** – the key or `"nested.key.path"`
  * **default** (*None*) – a default value if the key is not found
* **Returns:**
  the state value

#### set_data(key, value=None)

Sets some panel data.

* **Parameters:**
  * **key** – a key, `"nested.key.path"`, or dict mapping multiple
    possibly-nested keys to values
  * **value** (*None*) – the value, if key is a string

#### set_title(title)

Sets the title of the panel.

* **Parameters:**
  **title** – a title string