Gui API¶

Describes API entities for creating, querying, and manipulating GUI elements.

Signatures¶

Create

`add_button`	Adds a clickable button to a palette or sub-palette.
`add_note_button`	Adds a clickable button to the next note dialog which is shown.
`add_note_switch`	Adds a switch button to the next note dialog which is shown.
`add_palette`	Adds a new palette to the menu.
`add_slider`	Adds a draggable slider to a palette or sub-palette.
`add_subpalette`	Adds a sub-palette to a palette or another sub-palette.
`add_switch`	Adds a switch to a palette or sub-palette.
`close`	Closes a palette or sub-palette.
`delete_interface_item`	Deletes an interface item that has been added by a script.
`show_note`	Displays a custom note dialog with the controls defined before the call to this function.

Dialogs

`ask_filename`	Opens a file loading or saving dialog and returns the selected file name.
`ask_string`	Displays a text input dialog and returns the string typed by user.
`message_ok`	Displays a message dialog with a button to accept the message.
`message_ok_cancel`	Displays a message dialog with buttons to accept or cancel the dialog.
`message_yes_no`	Displays a message dialog with buttons to accept or reject the dialog.
`message_yes_no_cancel`	Displays a message dialog with buttons to accept, reject, or cancel the dialog.

Getters

`exists`	Verifies that the specified interface item exists.
`get`	Returns the current numeric value of an interface item.
`get_canvas_pan`	Returns the offset of the for drawing used canvas area in relation to the visible canvas area on the screen.
`get_canvas_zoom`	Returns the zoom of the for drawing used canvas area in relation to the visible canvas area on the screen.
`get_flags`	[Private] Returns the status flags of the specified interface item.
`get_from_note`	Returns the value of a note gadget shown in the last displayed note.
`get_height`	Returns the height in pixels of the specified interface item.
`get_hotkey`	Returns the shortcut of the specified interface item.
`get_id`	Returns the ID of the specified interface item.
`get_info`	Returns the bubble help text of the specified interface item.
`get_left_mouse_button_state`	Returns the current state of the left mouse button.
`get_max`	Returns the maximum possible numeric value the given interface item can take.
`get_min`	Returns the minimum possible numeric value the given interface item can take.
`get_mod`	Returns the current modifiers state of the given interface item.
`get_mouse_pos`	Returns the current mouse position in canvas or global world space coordinates.
`get_pos`	Returns the horizontal position of the given interface item in canvas or global coordinates.
`get_secondary`	Returns the the secondary numeric value of an interface item.
`get_status`	Returns the if an interface item is currently enabled or disabled, i.e., if it is greyed out or not.
`get_title`	Returns the title of the specified interface item.
`get_width`	Returns the width in pixels of the specified interface item.
`is_disabled`	Tests if the specified interface item is disabled, i.e., not greyed out and not interactable.
`is_enabled`	Tests if the specified interface item is enabled, i.e., not greyed out and interactable.
`is_locked`	Tests if the specified interface item is locked, i.e., not interactable.
`is_unlocked`	Tests if the specified interface item is unlocked, i.e., interactable.

Setters

`set`	Sets the current numeric values of an interface item.
`set_canvas_pan`	Sets the offset of the for drawing used canvas area in relation to the visible canvas area on the screen.
`set_canvas_zoom`	Sets the zoom factor of the canvas, scaling the visible canvas area in relation to the actual canvas size.
`set_color`	Sets the primary color picker used for the brush color in drawing mode and the mesh color in edit mode.
`set_hotkey`	Sets the hotkey of the specified interface item.
`set_max`	Sets the maximum possible numeric the given script generated interface item can take.
`set_min`	Sets the minimum possible numeric the given script generated interface item can take.
`set_mod`	Sets the modifiers state of the given script generated interface item.
`set_notebar_text`	Displays a message and optionally progress indicator in the top section of the ZBrush UI.
`set_status`	Sets a script-generated interface item as either being responsive or unresponsive to user interactions.

Interaction

`canvas_click`	Emulates a click within the canvas area.
`click`	Clicks the interface item at the given path.
`disable`	Makes a script-generated interface item unresponsive to user interactions.
`enable`	Makes a script-generated interface item responsive for user interactions.
`freeze`	Disables interface updates to avoid slowdowns while heavy operations are performed.
`hide`	Removes an interface item from the UI without deleting it.
`lock`	Makes an interface item unresponsive to user interactions.
`maximize`	Expands an interface item to its maximum size.
`minimize`	Collapses an interface item to its minimum size.
`press`	Brings a button into its pressed state.
`reset`	Brings the ZBrush into a default state associated with a particular version.
`show`	Scrolls to or shows the given palette or script generated interface item.
`show_actions`	Enables or disables script interface actions being drawn in the UI.
`stroke`	Emulates a brush stroke within an interface item.
`toggle`	Toggles the state of a switch.
`un_press`	Removes the pressed state of a button.
`unlock`	Makes an interface item responsive to user interactions.
`update`	Forces ZBrush to update its internal state and optionally redraw the UI.

Descriptions¶

Create¶

zbrush.commands.add_button(item_path: str, info: str = '', fn: Callable = None, initially_disabled: bool = False, width: float = 0.0, hotkey: str = '', icon_path: str = '', height: float = 0.0) → bool¶

Adds a clickable button to a palette or sub-palette.

Parameters:

item_path (str) – The item path for the button, whose last element will become the button’s text.
info (str, optional) – The bubble help of the button. Defaults to the empty string.
fn (Callable, optional) – The callback which is invoked when the button is pressed. Must follow the signature f(sender: str) -> None.
initially_disabled (bool, optional) – If the button should be initially not clickable. Defaults to False.
width (float, optional) – The width of the button in pixels. Setting the width to 0 will make it auto-width, positive values will set a specific width for the button. Defaults to 0.
hotkey (str, optional) –
An optional hotkey for the button. If specified, the button can be activated by pressing the hotkey.

Shortcut Details

ZBrush has a simple shortcut system which allows for defining shortcuts as strings. A shortcut consists out of a single lowercase character, optionally prefixed by a singular modifier key. So, the shortcut combination ALT + A would be represented as the string ALT+a, and the shortcut CMD + Z would be represented as CMD+z. Whitespace characters between the modifier and the character are not allowed. The following modifier keys are supported:

Modifier

Description

CTRL

Control key (Windows only)

CMD

Command key (macOS only)

ALT

Alternate key (Windows only)

OPT

Option key (macOS only)

TAB

Tab key

ENTER

Enter key

ESC

Escape key
icon_path (str, optional) – The path to an optional icon for the button. The icon should be a BMP or PSD file.
height (float, optional) – The height of the button in pixels. Setting the height to 0 will make it auto-height, positive values will set a specific height for the button. Defaults to 0.

Returns:

True if the button was successfully added, False otherwise.

Return type:

bool

Example

from zbrush import commands as zbc

# A callback functions for multiple buttons which checks the item path of the raised item.
def on_button_pressed(sender: str) -> None:
    if str(sender).endswith("Bar"):
        print("A button named 'Bar' was pressed.")
    else:
        print(f"Button pressed: {sender = }")

# Add a 'Foo' subpalette to the 'ZScript' palette if it doesn't exist.
if not zbc.exists("ZScript:Foo"):
    zbc.add_subpalette("ZScript:Foo")

# Adds a button labeled 'Bar' to the 'ZScript:Foo' subpalette with the tooltip "Hello World!" 
# which invokes the callback #on_button_pressed when clicked.
zbc.add_button("ZScript:Foo:Bar", "Hello World!", on_button_pressed)

zbrush.commands.add_note_button(name: str, icon_path: str = '', initially_pressed: bool = False, initially_disabled: bool = False, h_rel_position: float = 0.0, v_rel_position: float = 0.0, width: float = 0.0, height: float = 0.0, bg_color: int = -1, text_color: int = -1, bg_opacity: float = 1.0, text_opacity: float = 1.0, img_opacity: float = 1.0) → bool¶

Adds a clickable button to the next note dialog which is shown.

Parameters:

name (str) – The string item path and text for the button.
icon_path (str, optional) – The path to an icon for the button. Must be a BMP or PSD file. Defaults to an empty string (no icon).
initially_pressed (bool, optional) – Specifies if the button is initially pressed. Default to False.
initially_disabled (bool, optional) – Specifies if the button is initially not clickable. Default to False.
h_rel_position (float, optional) – The horizontal relative position of the button. 0 means automatic positioning, positive values offset from the left, and negative values offset from the right. Defaults to 0.0.
v_rel_position (float, optional) – The vertical relative position of the button. 0 means automatic positioning, positive values offset from the top, and negative values offset from the bottom. Defaults to 0.0.
width (float, optional) – The width of the button in pixels. Setting the width to 0 will make it auto-width, positive values will set a specific width for the button. Defaults to 0.0.
height (float, optional) – The height of the button in pixels. Setting the height to 0 will make it auto-height, positive values will set a specific height for the button. Defaults to 0.0.
bg_color (int, optional) – The background color of the button, computed with the formula (blue + (green * 256) + (red * 65536)). Defaults to -1 (no color).
text_color (int, optional) – The text color of the button, computed with the formula (blue + (green * 256) + (red * 65536)). Defaults to -1 (no color).
bg_opacity (float, optional) – The background opacity of the button. Defaults to 1.0.
text_opacity (float, optional) – The text opacity of the button. Defaults to 1.0.
img_opacity (float, optional) – The image opacity of the button. Defaults to 1.0.

Returns:

True if the button was successfully added, False otherwise.

Return type:

bool

Example

from zbrush import commands as zbc

# The IDs of the buttons we are going to add to our note. ZBrush assigns implicitly IDs starting with 
# 1 in the order the buttons are added.
ID_BTN_COLOR: int = 2
ID_BTN_CLOSE: int = 3

def run_note(title: str) -> str:
    '''Runs a simple note interface and returns a message when the user made a choice.
    '''
    # Notes are a bit weird in that they do not really have numeric inputs apart from switches. The
    # common workflow is to use buttons and then either use them as checks which switch out their
    # text for the empty string or an "x" or to cycle through a set of strings to emulate a value 
    # range.

    # The states of a dropdown/cycle we want to emulate.
    states: list[str] = ["Red", "Green", "Blue"]
    # The currently selected state.
    current_state: int = states[0]

    # Now comes the big trick, notes are often implemented in a loop to emulate interactivity, 
    # because out of the box, note controls do not have callback functions. So, we build a note,
    # poll its output, loop around, and build it again with the new state.
    while True:
        # Add three buttons to the note which is opened next. The first button is just a label
        # emulated by a disabled button. The second button shows the current state and the third 
        # button is a close button.
        zbc.add_note_button(name="Color:", initially_disabled=True, bg_opacity=0) # ID: 1
        zbc.add_note_button(name=str(current_state))                              # ID: 2
        zbc.add_note_button(name="Close")                                         # ID: 3

        # Now show the note which will return the ID of the first control clicked by the user, i.e.,
        # the next line runs from the note being opened until the user clicks something.
        result: int = zbc.show_note(title)

        # Bases on the clicked element, we either cycle the state or close the dialog. When we close
        # the dialog, we return the current state and with that exit the loop. Otherwise, we loop
        # around, rebuild the dialog with the new state, and show it again. Inputs smaller than one
        # are keyboard events like ESC or Enter, we also treat them as close events.
        if result == ID_BTN_COLOR:
            current_index: int = states.index(current_state)
            next_index: int = (current_index + 1) % len(states)
            current_state = states[next_index]
        elif result == ID_BTN_CLOSE or result <= 0: 
            return current_state

if __name__ == "__main__":
    result: str = run_note("Hello World!")
    zbc.message_ok(f"The chosen color is: {result}")

zbrush.commands.add_note_switch(name: str, icon_path: str = '', initially_pressed: bool = False, initially_disabled: bool = False, h_rel_position: float = 0.0, v_rel_position: float = 0.0, width: float = 0.0, height: float = 0.0, bg_color: int = -1, text_color: int = -1, bg_opacity: float = 1.0, text_opacity: float = 1.0, img_opacity: float = 1.0) → bool¶

Adds a switch button to the next note dialog which is shown.

Parameters:

name (str) – The string item path and text for the switch.
icon_path (str, optional) – The path to an icon for the switch button. Must be a BMP or PSD file. Defaults to an empty string (no icon).
initially_pressed (bool, optional) – Specifies if the switch button is initially pressed. Defaults to False.
initially_disabled (bool, optional) – Specifies if the switch button is initially not clickable. Defaults to False.
h_rel_position (float, optional) – The horizontal relative position of the button. 0 means automatic positioning, positive values offset from the left, and negative values offset from the right. Defaults to 0.0.
v_rel_position (float, optional) – The vertical relative position of the button. 0 means automatic positioning, positive values offset from the top, and negative values offset from the bottom. Defaults to 0.0.
width (float, optional) – The width of the button in pixels. Setting the width to 0 will make it auto-width, positive values will set a specific width for the button. Defaults to 0.0.
height (float, optional) – The height of the button in pixels. Setting the height to 0 will make it auto-height, positive values will set a specific height for the button. Defaults to 0.0.
bg_color (int, optional) – The background color of the button, computed with the formula (blue + (green * 256) + (red * 65536)). Defaults to -1 (no color).
text_color (int, optional) – The text color of the button, computed with the formula (blue + (green * 256) + (red * 65536)). Defaults to -1 (no color).
bg_opacity (float, optional) – The background opacity of the button. Defaults to 1.0.
text_opacity (float, optional) – The text opacity of the button. Defaults to 1.0.
img_opacity (float, optional) – The image opacity of the button. Defaults to 1.0.

Returns:

True if the switch button was successfully added, False otherwise.

Return type:

bool

Example

from zbrush import commands as zbc

# Add two switch buttons to the next note which is shown, one initially off and one initially on.
zbc.add_note_switch(name="Switch A", initially_pressed=False)
zbc.add_note_switch(name="Switch B", initially_pressed=True)
zbc.add_note_button(name="Close")
zbc.show_note("Note with Switch")

# Query the state of the two switches after the user has closed the note.
state_a: bool = zbc.get_from_note("Switch A")
state_b: bool = zbc.get_from_note("Switch B")
print(f"Switch A is {'ON' if state_a else 'OFF'}")
print(f"Switch B is {'ON' if state_b else 'OFF'}")

zbrush.commands.add_palette(item_path: str, docking_bar: int, shortcut: str = '') → bool¶

Adds a new palette to the menu.

Note

A palette is a top-level menu in ZBrush, and it can contain sub-palettes, buttons, sliders, and switches. To add an area in an existing palette, use add_subpalette instead.

Parameters:

item_path (str) – The item path for the palette, whose last element will become the palette’s name.
docking_bar (int, optional) – Specifies the docking behavior. 0 means the palette will be docked in the left menu bar, 1 means it will be docked in the right menu bar. Defaults to 0.
shortcut (str, optional) – An optional shortcut for the palette. If specified, the palette can be opened by pressing the shortcut key. Defaults to an empty string (no shortcut).

Returns:

True if the palette was successfully added, False otherwise.

Return type:

bool

Example

from zbrush import commands as zbc

def on_interact(*args, **kwargs) -> None:
    """A callback function that is called when an item is interacted with.
    """
    print("on_interact", args, kwargs)

# Close the "Palette" palette if it already exists, so that we start fresh.
if zbc.exists("Palette"):
    zbc.close("Palette")

# Adds a new palette named "Palette" to the ZBrush interface which will auto doc to the right.
zbc.add_palette("Palette", docking_bar=1)

# Adds a subpalette named "Subpalette" to the "Palette" palette which has no title bar and is
# always open.
zbc.add_subpalette("Palette:Subpalette", title_mode=2)

# Adds two buttons to the "Subpalette" subpalette.
zbc.add_button(f"Palette:Subpalette:Button A", "", on_interact)
zbc.add_button(f"Palette:Subpalette:Button B", "", on_interact)

# Adds a subpalette named "Subpalette (Togglable)" to the "Palette" palette which has a title bar
# and a minimize button, and is togglable.
zbc.add_subpalette("Palette:Subpalette (Togglable)")

# Adds a slider and a switch to the "Subpalette (Togglable)" subpalette.
zbc.add_slider(f"Palette:Subpalette (Togglable):Slider", 2, 1, 0, 10, "some help", on_interact, width=1.0)
zbc.add_switch(f"Palette:Subpalette (Togglable):Switch", True, "some help", on_interact, width=1.0)

zbrush.commands.add_slider(item_path: str, cur_value: float, resolution: int, min_value: float, max_value: float, info: str = '', fn: Callable = None, initially_disabled: bool = False, width: float = 0.0, height: float = 0.0) → bool¶

Adds a draggable slider to a palette or sub-palette.

A slider is a gadget that allows the user to select a value from a range by dragging a handle along a track.

Parameters:

item_path (str) – The item path for the slider, whose last element will become the slider’s name.
cur_value (float) – The initial value of the slider.
resolution (int) – The step size of the slider. When the slider has a range of [0, 10] for example, and you set the resolution to 2, the slider will snap to the values 0, 2, 4, 6, 8, 10. Setting the resolution to 0 means the slider will not snap to ticks.
min_value (float) – The minimum value of the slider.
max_value (float) – The maximum value of the slider.
info (str, optional) – The bubble help of the slider. Defaults to an empty string.
fn (Callable, optional) – The callback of the slider which is invoked when the slider’s value changes. Must conform to the signature f(sender: str, value: float) -> None, where sender is the slider’s item path and value is the current value of the slider. The callback of a slider is only called at the end of a drag operation and not during it.
initially_disabled (bool, optional) – Specifies if the slider is initially disabled. Defaults to False.
width (float, optional) – The width of the slider in pixels. Setting the width to 0 will make it auto-width, positive values will set a specific width for the button. Defaults to 0.0.
height (float, optional) – The height of the slider in pixels. Setting the height to 0 will make it auto-height, positive values will set a specific height for the button. Defaults to 0.0.

Returns:

True if the slider was successfully added, False otherwise.

Return type:

bool

Example

from zbrush import commands as zbc

def on_slider_change(sender: str, value: float) -> None:
    print(f"{sender}'s value changed to: {value}")

# Add a 'Foo' subpalette to the 'ZScript' palette if it doesn't exist.
if not zbc.exists("ZScript:Foo"):
    zbc.add_subpalette("ZScript:Foo")

# Adds a slider named 'MySlider' to 'ZScript:Foo' with a range from 0 to 100, the initial value of 
# 12, a step size of 1, and the callback function `on_slider_change`.
zbc.add_slider("ZScript:Foo:MySlider", 12, 1, 0, 100, "", on_slider_change)

zbrush.commands.add_subpalette(item_path: str, title_mode: int, icon_path: str = '', left_inset: float = 0.0, right_inset: float = 0.0, top_inset: float = 0.0, bottom_inset: float = 0.0) → bool¶

Adds a sub-palette to a palette or another sub-palette.

Note

Insets will require manually sized elements or will result in auto-sized elements being cut off.

Parameters:

item_path (str) – The item path for the sub-palette, whose last element will become the sub-palette’s name.
title_mode (int, optional) – The title bar style of the sub-palette. 0 will show the title and minimize button, 1 will show the title without the minimize button, and 2 will hide the title bar completely. Defaults to 0.
icon_path (str, optional) – The path to an optional gray-scale (8-bits) icon for the sub-palette. The icon should be a BMP or PSD file and have the standard size of 20 pixels squared. Defaults to the empty string (no icon).
left_inset (float, optional) – The left margin of elements in the sub-palette to its border. 0 means no inset, positive values will add an inset from the left, and negative values will add an inset from the right. Defaults to 0.0.
right_inset (float, optional) – The right margin of elements in the sub-palette to its border. 0 means no inset, positive values will add an inset from the right, and negative values will add an inset from the left. Defaults to 0.0.
top_inset (float, optional) – The top margin of elements in the sub-palette to its border. 0 means no inset, positive values will add an inset from the top, and negative values will add an inset from the bottom. Defaults to 0.0.
bottom_inset (float, optional) – The bottom margin of elements in the sub-palette to its border. 0 means no inset, positive values will add an inset from the bottom, and negative values will add an inset from the top. Defaults to 0.0.

Returns:

True if the sub-palette was successfully added, False otherwise.

Return type:

bool

Example

from zbrush import commands as zbc

# A callback function that fits different callback function signatures (by using *args and **kwargs).
# We use this because buttons, sliders, and switches have different callback signatures.
def on_change(*args, **kwargs) -> None:
    print("on_change", args, kwargs)

# Adds a new palette named "Palette" to the ZBrush interface which will auto doc to the right.
zbc.add_palette("Palette", docking_bar=1)

# Adds a subpalette named "Subpalette" to the "Palette" palette which has no title bar and is
# always open.
zbc.add_subpalette("Palette:Subpalette", title_mode=2)

# Adds two buttons to the "Subpalette" subpalette.
zbc.add_button(f"Palette:Subpalette:Button A", "", on_change)
zbc.add_button(f"Palette:Subpalette:Button B", "", on_change)

# Adds a subpalette named "Subpalette (Togglable)" to the "Palette" palette which has a title bar
# and a minimize button, and is togglable.
zbc.add_subpalette("Palette:Subpalette (Togglable)")

# Adds a slider and a switch to the "Subpalette (Togglable)" subpalette.
zbc.add_slider(f"Palette:Subpalette (Togglable):Slider", 2, 1, 0, 10, "some help", on_change)
zbc.add_switch(f"Palette:Subpalette (Togglable):Switch", True, "some help", on_change)

zbrush.commands.add_switch(item_path: str, initial_state: bool, info: str = '', fn: Callable = None, initially_disabled: bool = False, width: float = 0.0, height: float = 0.0, icon_path: str = '') → bool¶

Adds a switch to a palette or sub-palette.

A switch is a gadget that allows the user to toggle a state on or off.

Parameters:

item_path (str) – The item path for the switch, whose last element will become the switch’s name.
initial_state (bool) – The initial state of the switch. True means the switch is on, False means it is off. Defaults to False.
info (str, optional) – The bubble help of the switch. Defaults to an empty string.
fn (Callable, optional) – The callback function which is invoked when the switch’s state changes. Must conform to the signature fn(sender: str, value: bool) -> None, where sender is the switch’s item path and value is the current state of the switch.
initially_disabled (bool, optional) – Specifies if the switch is initially disabled. Defaults to False.
width (float, optional) – The width of the switch in pixels. Setting the width to 0 will make it auto-width, positive values will set a specific width for the button. Defaults to 0.0.
height (float, optional) – The height of the switch in pixels. Setting the height to 0 will make it auto-height, positive values will set a specific height for the button. Defaults to 0.0.
icon_path (str, optional) – The path to an optional icon for the switch. The icon should be a BMP or PSD file. Defaults to an empty string (no icon).

Returns:

True if the switch was successfully added, False otherwise.

Return type:

bool

Example

from zbrush import commands as zbc

def on_value_changed(sender: str, value: float) -> None:
    print(f"{sender}'s value changed to: {value}")

# Make sure there is no existing "ZScript:Foo" palette and create a new one.
if zbc.exists("ZScript:Foo"):
    zbc.close("ZScript:Foo")

zbc.add_subpalette("ZScript:Foo")

# Create a switch ladled 'ClickMe' in the 'Foo' subpalette which invokes `on_value_changed` when toggled.
zbc.add_switch("ZScript:Foo:ClickMe", True, "", on_value_changed)

zbrush.commands.close(item_path: str, show_zoom_rects: bool = False, parent_window: bool = False) → None¶

Closes a palette or sub-palette.

Parameters:

item_path (str) – The interface path of the item to close.
show_zoom_rects (bool, optional) – If to show the zoom rectangle. Defaults to False.
parent_window (bool, optional) – If to target the parent of the specified item instead. Defaults to False.

Example

from zbrush import commands as zbc

# Close ZScript:Python Scripting palette.
zbc.close("ZScript:Python Scripting")

# Close ZScript:Python Scripting palette by passing the button 'Load' as the item path.
zbc.close("ZScript:Python Scripting:Load", False, True)

zbrush.commands.delete_interface_item(item_path: str) → bool¶

Deletes an interface item that has been added by a script.

Can only be used for script-generated interface items and can only be applied to gadgets.
Does not work for palettes or sub-palettes, use close for these.

Parameters:: item_path (str) – The path of item to delete.
Returns:: True if the item was deleted successfully, False otherwise.
Return type:: bool

Example

from zbrush import commands as zbc

# Deletes the item "Button" in the "Zscript:Foo" sub-palette if it exists.
if zbc.exists("Zscript:Foo:Button"):
    zbc.delete_interface_item("Zscript:Foo:Button")

zbrush.commands.show_note(text: str, item_path: str = '', display_duration: float = 0.0, bg_color: int = -1, distance_to_ui_item: int = 48, preferred_width: int = 400, fill_color: int = -1, frame_h_size: float = 1.0, frame_v_size: float = 1.0, frame_left_side: float = 0.0, frame_top_side: float = 0.0, icon_path: str = '') → int¶

Displays a custom note dialog with the controls defined before the call to this function.

Note

Notes are ZBrush terminology for modal dialogs.

Parameters:

text (str) – The title of the dialog.
item_path (str, optional) – Has no effect.

display_duration (float, optional) –

The manner in which the note is displayed. Defaults to 0.

0	The note is shown immediately and will stay on screen until the user clicks a button.
-1	The note is not shown but instead combined with the next show_note call that does not use -1 as the display duration. Multiple notes can be staged like this.
>0	Values greater than zero will show the note for the specified number of seconds. After that time the note will disappear automatically.

bg_color (int, optional) – Popup background color. ( 0x000000<->0xffffff, default=0x606060, 0=NoBackground )
distance_to_ui_item (int, optional) – Has no effect.
preferred_width (int, optional) – Has no effect.
fill_color (int, optional) – Has no effect.
frame_h_size (float, optional) – Has no effect.
frame_v_size (float, optional) – Has no effect.
frame_left_side (float, optional) – Has no effect.
frame_top_side (float, optional) – Has no effect.
icon_path (str, optional) – Displays an icon next to the dialog title (text). Will display no icon when an empty string is passed. Defaults to the empty string.

Returns:

The index of the button that was pressed by the user to close the dialog.

Return type:

int

Example

from zbrush import commands as zbc

def show_note_delayed(title: str) -> None:
    '''Display a note that will not open on its own but will be included with the next note which 
    is shown.
    '''
    zbc.add_note_button("Delayed Button")
    zbc.show_note(title, display_duration=-1)

def show_note(title: str) -> None:
    '''Display a note that will open immediately and close when the user clicks a button.
    '''
    zbc.add_note_button("Button")
    zbc.show_note(title, display_duration=0)

def show_note_timed(title: str, message: str, duration: float):
    '''Display a note that will open immediately and close after a specified duration.
    '''
    zbc.add_note_button(message, initially_disabled=True, bg_opacity=0)
    # Also customize the note background color and icon of the note.
    blue: int = zbc.rgb(0, 125, 255)
    path: str = r"D:\\git\\zbrush-sdk\\examples\\gui\\images\\cappuccino.jpg"
    zbc.show_note(title, bg_color=blue, icon_path=path, display_duration=duration)

# First show two delayed notes and then a normal note (i.e., three notes at once) and after the user
# closes the normal note, show a timed note that will close automatically after 3 seconds.
show_note_delayed("Delayed Note")
show_note_delayed("Another Delayed Note")
show_note("User Terminated Note")
show_note_timed("Timed Note", "This note will close in 3 seconds", 3.0)

Dialogs¶

zbrush.commands.ask_filename(extensions: str, default_file_name: str = '', title: str = '') → str¶

Opens a file loading or saving dialog and returns the selected file name.

The function does not carry out the actual loading or saving of the file, it only provides a dialog for the user to select a file name. The actual file operations must be handled separately.

Warning

It is a known issue that the Python console of ZBrush does not render backward slashes in strings correctly. Your strings are correct, but the console renders them incorrectly. This is not an escaping issue, and double escaping strings or using raw strings does not resolve the issue. This also impacts the ability to correctly render special characters such as \n and \t.

Parameters:

extensions (str) – A string containing the file extensions and their descriptions. Up to three extensions can be specified, following the format “Label A (*.ext1)|*.ext1|Label B (*.ext2)|*.ext2|Label A C (*.ext3)|*.ext3”.
default_file_name (str, optional) – Default fileName for SaveDialog, will open OpenDialog if empty.
title (str, optional) – The title of the file dialog. Defaults to an empty string.

Returns:

The full path of the selected file, or an empty string if the dialog was canceled.

Return type:

str

Example

from zbrush import commands as zbc

# Opens a dialog to load a `dxf` or `obj` file.
file: str = zbc.ask_filename("DXF (*.dxf)|*.dxf|OBJ (*.obj)|*.obj||", "","Please select a file to load...")
print(f"Selected file: {file}")
# Opens a dialog to save a file with the `*.zvr` extension and a default name of `tempFile`.
file: str = zbc.ask_filename("*.zvr", "tempFile")
print(f"Selected file: {file}")

zbrush.commands.ask_string(initial_string: str = '', title: str = '') → str¶

Displays a text input dialog and returns the string typed by user.

Parameters:

initial_string (str, optional) – The initial string to display in the input dialog. Defaults to an empty string.
title (str, optional) – The title of the input dialog. Defaults to an empty string.

Returns:

The string entered by the user, or an empty string if the dialog was canceled

Return type:

str

Example

from zbrush import commands as zbc

# Displays a text input dialog and returns the string typed by user.
result: str = zbc.ask_string("Your name here", "Please enter your name:")
print(f"The entered name is: {result}")

zbrush.commands.message_ok(message: str = '', title: str = '') → None¶

Displays a message dialog with a button to accept the message.

Parameters:

message (str, optional) – The message that will be shown. Defaults to the empty string.
title (str, optional) – The title of the message. Defaults to the empty string.

Example

from zbrush import commands as zbc

zbc.message_ok("This is my message", "This is the title")

zbrush.commands.message_ok_cancel(message: str = '', title: str = '') → bool¶

Displays a message dialog with buttons to accept or cancel the dialog.

Parameters:

message (str, optional) – The message that will be shown. Defaults to the empty string.
title (str, optional) – The title of the message. Defaults to the empty string.

Returns:

True if the user clicked ‘OK’, False if the user clicked ‘CANCEL’.

Return type:

bool

Example

from zbrush import commands as zbc

result: bool = zbc.message_ok_cancel("Delete all images?", "Please confirm")
print(f"User clicked {'OK' if result else 'CANCEL'}")

zbrush.commands.message_yes_no(message: str = '', title: str = '') → bool¶

Displays a message dialog with buttons to accept or reject the dialog.

Parameters:

message (str, optional) – The message that will be shown. Defaults to the empty string.
title (str, optional) – The title of the message. Defaults to the empty string.

Returns:

True if the user clicked ‘YES’, False if the user clicked ‘NO’.

Return type:

bool

Example

from zbrush import commands as zbc

result: bool = zbc.message_ok_cancel("Delete all images?", "Please confirm")
print(f"User clicked {'YES' if result else 'NO'}")

zbrush.commands.message_yes_no_cancel(message: str = '', title: str = '') → int¶

Displays a message dialog with buttons to accept, reject, or cancel the dialog.

Parameters:

message (str, optional) – The message that will be shown. Defaults to the empty string.
title (str, optional) – The title of the message. Defaults to the empty string.

Returns:

1 if the user clicked ‘YES’, 0 if the user clicked ‘NO’, -1 if the user clicked ‘CANCEL’.

Return type:

int

Example

from zbrush import commands as zbc

result: int = zbc.message_yes_no_cancel("Delete all images?", "Please confirm")
print(f"User clicked {'YES' if result == 1 else 'NO' if result == 0 else 'CANCEL'}")

Getters¶

zbrush.commands.exists(item_path: str) → bool¶

Verifies that the specified interface item exists.

Parameters:: item_path (str) – The path of the item to check.
Returns:: True if the item exists, False otherwise.
Return type:: bool

Example

from zbrush import commands as zbc

# Disables the item 'Button' in the 'ZScript:Foo' sub-palette only when it exists.
if zbc.exists("ZScript:Foo:Button"):
    zbc.disable("ZScript:Foo:Button")

zbrush.commands.get(item_path: str) → float¶

Returns the current numeric value of an interface item.

Note

See secondary for getting the secondary value of an item, e.g., the y-component of a 2D gadget.

Parameters:: item_path (str) – The path of the item to get the value for.
Returns:: The current value of the item. All values (integers, booleans) are expressed as floats. Items such as buttons or sub-palettes which do not have any value will return 0.0.
Return type:: float

Example

from zbrush import commands as zbc

# A slider, #a will hold the current value of the slider.
a: float = zbc.get("Draw:Width")

# A toggle button, #b will hold the current value of the button where 0.0 means 
# off and 1.0 means on.
b: float = zbc.get("Tool:UV Map:Create (Unwrap):Auto Seams")

# Getting the value of a button and a subpalette. Neither of these has a value which 
# could be retrieved, but these calls will not raise an error, and instead just return 
# 0.0.
c: float = zbc.get("Tool:Displacement Map:Create DispMap")
d: float = zbc.get("Tool:Displacement Map")

zbrush.commands.get_canvas_pan() → tuple[float, float]¶

Returns the offset of the for drawing used canvas area in relation to the visible canvas area on the screen.

This function is only useful when a canvas zoom has been set via set_canvas_zoom and the canvas is therefore larger than the visible canvas area.

Warning

This does not return the camera offset, use get_transform for that.

Returns:: The X and Y offset of the canvas area used for drawing in relation to the visible canvas area on the screen.
Return type:: tuple[float, float]

Example

from zbrush import commands as zbc

result: tuple[float, float] = zbc.get_canvas_pan()
print(f"Canvas pan: {result}")

zbrush.commands.get_canvas_zoom() → float¶

Returns the zoom of the for drawing used canvas area in relation to the visible canvas area on the screen.

This function is only useful when a canvas zoom has been set via set_canvas_zoom and the canvas is therefore larger than the visible canvas area.

Warning

This does not return the camera zoom, use get_transform for that.

Returns:: The zoom factor of the canvas area used for drawing in relation to the visible canvas area on the screen.
Return type:: float

Example

from zbrush import commands as zbc

result: float = zbc.get_canvas_zoom()
print(f"Canvas zoom: {result}")

zbrush.commands.get_flags(item_path: str) → int¶

[Private] Returns the status flags of the specified interface item.

The status flags are a bitwise combination of other values already expressed by the API, such as an item being enabled/disabled, visible/invisible, or pressed. But they also include other information such as if an item is a button, slider, or toggle button. The only sensible public use is to check if two items have the same flags.

Warning

The meaning of the individual item flag bits is intentionally not documented and may change without notice.

Parameters:: item_path (str) – The item path of the item to get the flags for.
Returns:: The bitwise combination of the status flags of the item.
Return type:: int

Example

from zbrush import commands as zbc

flags: int = zbc.get_flags("Light:Light Placement")

zbrush.commands.get_from_note(index: int | str) → Any¶

Returns the value of a note gadget shown in the last displayed note.

This mostly makes sense in the context of a add_note_switch to retrieve the value of a switch.

Parameters:: index (int or str) – The one-based index of name of the note gadget to get the value for.
Returns:: The value of the note gadget.
Return type:: Any

Example

from zbrush import commands as zbc

# Add two switch buttons to the next note which is shown, one initially off and one initially on.
zbc.add_note_switch(name="Switch A", initially_pressed=False)
zbc.add_note_switch(name="Switch B", initially_pressed=True)
zbc.add_note_button(name="Close")
zbc.show_note("Note with Switch")

# Query the state of the two switches after the user has closed the note.
state_a: bool = zbc.get_from_note("Switch A")
state_b: bool = zbc.get_from_note("Switch B")
print(f"Switch A is {'ON' if state_a else 'OFF'}")
print(f"Switch B is {'ON' if state_b else 'OFF'}")

zbrush.commands.get_height(item_path: str) → int¶

Returns the height in pixels of the specified interface item.

Parameters:: item_path (str) – The item path of the item to get the height for.
Returns:: Height in pixels of specified interface item.
Return type:: int

Example

from zbrush import commands as zbc

light_place: str = "Light:Light Placement"
light_amb: str = "Light:Ambient"
print(f"Height of '{light_place}' is {zbc.get_height(light_place)} pixels.")
print(f"Height of '{light_amb}' is {zbc.get_height(light_amb)} pixels.")

zbrush.commands.get_hotkey(item_path: str) → str¶

Returns the shortcut of the specified interface item.

Shortcut Details

ZBrush has a simple shortcut system which allows for defining shortcuts as strings. A shortcut consists out of a single lowercase character, optionally prefixed by a singular modifier key. So, the shortcut combination ALT + A would be represented as the string ALT+a, and the shortcut CMD + Z would be represented as CMD+z. Whitespace characters between the modifier and the character are not allowed. The following modifier keys are supported:

Modifier	Description
CTRL	Control key (Windows only)
CMD	Command key (macOS only)
ALT	Alternate key (Windows only)
OPT	Option key (macOS only)
TAB	Tab key
ENTER	Enter key
ESC	Escape key

Parameters:: item_path (str) – Interface item path
Returns:: Shortcut of specified windowID interface item.
Return type:: str

Example

from zbrush import commands as zbc

value: str = zbc.get_hotkey("Transform:Move")
print(f"Hotkey for 'Transform:Move' is '{value}'.")

zbrush.commands.get_id(item_path: str) → int¶

Returns the ID of the specified interface item.

Functions which both accept an int or str for identifying an interface item, can take a value returned by this function as the int argument.

Parameters:: item_path (str) – The interface item path to get the ID for.
Returns:: The id code of the specified interface item.
Return type:: int

Example

from zbrush import commands as zbc

value: str = zbc.get_id("Transform:Move")
print(f"ID for 'Transform:Move' is '{value}'.")

zbrush.commands.get_info(item_path: str) → str¶

Returns the bubble help text of the specified interface item.

Parameters:: item_path (str) – The item path of the item to get the bubble help text for.
Returns:: The bubble help text of specified interface item.
Return type:: str

Example

from zbrush import commands as zbc

value: str = zbc.get_info("Transform:Move")
print(f"The bubble help text for 'Transform:Move' is: '{value}'.")

zbrush.commands.get_left_mouse_button_state() → bool¶

Returns the current state of the left mouse button.

Returns:: True if the left mouse button is currently pressed, False otherwise.
Return type:: bool

Example

from zbrush import commands as zbc
import time

# Poll the left mouse button state for three seconds and print its state every 0.25 
# seconds. The output of the script will only be shown after the script has finished,
# because the script is blocking.

t_start: float = time.time()
t_delta: float = 3.0
while (time.time() - t_start) < t_delta:
    state: bool = zbc.get_left_mouse_button_state()
    print(f"Current left mouse button pressed state: {state}.")
    time.sleep(0.25)

zbrush.commands.get_max(item_path: str) → float¶

Returns the maximum possible numeric value the given interface item can take.

Parameters:: item_path (str) – The item path of the item to get the maximum possible value for.
Returns:: The maximum possible value of the specified interface item.
Return type:: float

Example

from zbrush import commands as zbc

value: str = zbc.get_max("Draw:Draw Size")
print(f"The maximum value for 'Draw:Draw Size' is: {value}.")

zbrush.commands.get_min(item_path: str) → float¶

Returns the minimum possible numeric value the given interface item can take.

Parameters:: item_path (str) – The item path of the item to get the minimum possible value for.
Returns:: The minimum possible value of the specified interface item.
Return type:: float

Example

from zbrush import commands as zbc

value: str = zbc.get_min("Draw:Draw Size")
print(f"The minimum value for 'Draw:Draw Size' is: {value}.")   

zbrush.commands.get_mod(item_path: str) → int¶

Returns the current modifiers state of the given interface item.

Modifiers are used to annotate an interface item, e.g., a slider which additional states. This is commonly used for deformation sliders in the Tool palette, where each modifier represents a different axis or plane of deformation. A modifier always expresses a toggle state, i.e., if it is active or not. Numeric values can not be represented by modifiers.

The modifiers are represented as a bit flags in an integer value. There exist no public defined values for modifier flags, and instead the modifier bit values must be deduced from the GUI. The values are always increasing powers of two as they appear from left to right in the GUI. For example, the Tool:Deformation:Unify slider has the three modifiers x, y, and z. In its upper right corner. x is the first modifier and therefore has the value 1 << 0 = 1 (1 << 0 means 2^0), y the second and has the value 1 << 1 = 2, and z the third has the value 1 << 2 = 4.

Parameters:: item_path (str) – The item path of the item to get the modifiers for.

Example

from zbrush import commands as zbc

value: str = zbc.get_mod("Tool:Deformation:Unify")
print(f"The current modifier value for 'Tool:Deformation:Unify' is: {value}.")
if value & 1:
    print("The X modifier is active.")
if value & 2:
    print("The Y modifier is active.")
if value & 4:
    print("The Z modifier is active.")

zbrush.commands.get_mouse_pos(global_coordinates: bool = False) → tuple[float, float]¶

Returns the current mouse position in canvas or global world space coordinates.

Parameters:: global_coordinates (bool, optional) – When set to True, the mouse position is returned in global window space. When set to False, the mouse position is returned in canvas space. Defaults to False.
Returns:: The current mouse position as an (X, Y) tuple.
Return type:: tuple[float, float]

Example

from zbrush import commands as zbc

# Get the current mouse position in canvas space.
pos_canvas: tuple[float, float] = zbc.get_mouse_pos(global_coordinates=False)
print(f"Current mouse position in canvas space: {pos_canvas}")

# Get the current mouse position in global window space.
pos_global: tuple[float, float] = zbc.get_mouse_pos(global_coordinates=True)
print(f"Current mouse position in global window space: {pos_global}")

zbrush.commands.get_pos(item_path: str, global_coordinates: bool = False) → float¶

Returns the horizontal position of the given interface item in canvas or global coordinates.

Parameters:

item_path (str) – The item path of the item to get the horizontal position for.
global_coordinates (bool, optional) – When set to True, the position is returned in global window space. When set to False, the position is returned in canvas space. Defaults to False.

Returns:

The horizontal position of the item.

Return type:

float

Example

from zbrush import commands as zbc

# Returns the horizontal position of the 'Draw:Width' interface item in canvas coordinates.
pos_canvas: float = zbc.get_pos("Draw:Width", global_coordinates=False)
print(f"Canvas position: {pos_canvas}")

# Returns the horizontal position of the 'Draw:Width' interface item in global coordinates.
pos_global: float = zbc.get_pos("Draw:Width", global_coordinates=True)
print(f"Global position: {pos_global}")

zbrush.commands.get_secondary(item_path: str) → float¶

Returns the the secondary numeric value of an interface item.

Some interface items have two numeric values, e.g., the 2D control for a light. This function returns the secondary value, e.g., the y-component of a 2D control. This function cannot to be used to get modifier states.

Note

The get_mod function returns the modifier state of an item, e.g., if the x, y, or z modifier of a deformation slider is active.

Parameters:: item_path (str) – The item path of the item to get the secondary value for.
Returns:: The secondary value of the item.
Return type:: float

Example

from zbrush import commands as zbc

x: float = zbc.get("Light:Light Placement")
y: float = zbc.get_secondary("Light:Light Placement")
print(f"Light position: ({x}, {y})")

zbrush.commands.get_status(item_path: str) → bool¶

Returns the if an interface item is currently enabled or disabled, i.e., if it is greyed out or not.

Note

To get the value of an item, e.g., if a toggle button is pressed or not, use get.

Parameters:: item_path (str) – The item path of the item to get the status for.
Returns:: True if the item is enabled, False if it is disabled.
Return type:: bool

Example

from zbrush import commands as zbc

status: bool = zbc.get_status("Transform:Move")
print(f"Transform:Move status is: {status}")

zbrush.commands.get_title(item_path: str, full_path: bool = False) → str¶

Returns the title of the specified interface item.

This effectively just returns the last component of an item path.

Parameters:

item_path (str) – The item path of the item to get the title for.
full_path (bool, optional) – If set to True, item_path is treated as a full path to the item, otherwise it is treated as a relative path. Defaults to False.

Returns:

The title of the specified interface item.

Return type:

str

Example

from zbrush import commands as zbc

title: str = zbc.get_title("Transform:Move") # Will return 'Move'
print(f"The title of 'Transform:Move' is: '{title}'.")

zbrush.commands.get_width(item_path: str) → float¶

Returns the width in pixels of the specified interface item.

Parameters:: item_path (str) – The item path of the item to get the width for.
Returns:: Width in pixels of specified interface item.
Return type:: int

Example

from zbrush import commands as zbc

light_place: str = "Light:Light Placement"
light_amb: str = "Light:Ambient"
print(f"Width of '{light_place}' is {zbc.get_width(light_place)} pixels.")
print(f"Width of '{light_amb}' is {zbc.get_width(light_amb)} pixels.")

zbrush.commands.is_disabled(item_path: str) → bool¶

Tests if the specified interface item is disabled, i.e., not greyed out and not interactable.

Parameters:: item_path (str) – The item path of the interface item to test for being disabled.
Returns:: True if the specified interface item is currently disabled, False otherwise.
Return type:: bool

Example

from zbrush import commands as zbc

is_disabled: bool = zbc.is_disabled("Transform:Move")
print(f"'Transform:Move' is disabled: {is_disabled}")

zbrush.commands.is_enabled(item_path: str) → bool¶

Tests if the specified interface item is enabled, i.e., not greyed out and interactable.

Parameters:: item_path (str) – The item path of the interface item to test for being enabled.
Returns:: True if the specified interface item is currently enabled, False otherwise.
Return type:: bool

Example

from zbrush import commands as zbc

is_enabled: bool = zbc.is_enabled("Transform:Move")
print(f"'Transform:Move' is enabled: {is_enabled}")

zbrush.commands.is_locked(item_path: str) → bool¶

Tests if the specified interface item is locked, i.e., not interactable.

Parameters:: item_path (str) – The item path of the interface item to test for being locked.
Returns:: True if the specified interface item is currently locked, False otherwise.
Return type:: bool

Example

from zbrush import commands as zbc

is_locked: bool = zbc.is_locked("Transform:Move")
print(f"'Transform:Move' is locked: {is_locked}")

zbrush.commands.is_unlocked(item_path: str) → bool¶

Tests if the specified interface item is unlocked, i.e., interactable.

Parameters:: item_path (str) – The item path of the interface item to test for being unlocked.
Returns:: True if the specified interface item is currently unlocked, False otherwise.
Return type:: bool

Example

from zbrush import commands as zbc

is_unlocked: bool = zbc.is_unlocked("Transform:Move")
print(f"'Transform:Move' is unlocked: {is_unlocked}")

Setters¶

zbrush.commands.set(item_path: str, h_value: float | None = None, v_value: float | None = None) → None¶

Sets the current numeric values of an interface item.

The primary value is the ‘obvious’ value most items have. E.g., the state of a switch button, the value of a slider. But some items also have a secondary value when their state cannot be expressed by a singular numeric value. E.g., a 2D gadget has an x- and a y-component, which can be set via the primary and secondary value.

Parameters:

item_path (str) – The item path of the item to set the values for.
h_value (float, optional) – The primary value to set. If set to None, the value will not be changed. Defaults to None.
v_value (float, optional) – The secondary value to set. If set to None, the value will not be changed. Defaults to None.

Example

from zbrush import commands as zbc

# Set the draw size to 42.
zbc.set("Draw:Draw Size", 42)

# Enable move and edit mode in the transform palette.
zbc.set("Transform:Move", 1)
zbc.set("Transform:Edit", 1)

# Set the light position as an example for an item with a secondary value.
zbc.set("Light:Light Placement", 0.5, 0.5)

# Note that buttons can also be pressed. I.e., this is equivalent to what we did above to set the transform 
# modes. The advantage of using #set is that we do not need to check the current state of the button first, 
# we can just set it to the desired state.
if not zbc.get("Transform:Move"):
    zbc.press("Transform:Move") # Enables move mode
if not zbc.get("Transform:Edit"):
    zbc.press("Transform:Edit") # Enables edit mode

# Somtimes it is also desirable to check the current value before calling #set to avoid unnecessary redraws or
# recomputations. A very defensive way to set a new value would be this, which also takes floating point 
# precision issues into account.

new_value: float = 3.14159 # The new value we want to set.
value_delta: float = 1e-5 # Acceptable difference threshold below which we do not update the value.
if zbc.exists("Foo::Bar") and (abs(zbc.get("Foo::Bar") - new_value) > value_delta):
    zbc.set("Foo::Bar", new_value)

zbrush.commands.set_canvas_pan(h: float, v: float) → None¶

Sets the offset of the for drawing used canvas area in relation to the visible canvas area on the screen.

This function is only useful when a canvas zoom has been set via set_canvas_zoom and the canvas is therefore larger than the visible canvas area.

Warning

This does not set the camera offset, use set_transform for that.

Parameters:

h (float) – The horizontal offset in canvas space. 0 is the left edge of the document.
v (float) – The vertical offset in canvas space. 0 is the top edge of the document.

Example

from zbrush import commands as zbc

# Centers a 640x480 canvas in the document view, i.e., the visible area of the canvas. This only has an
# effect when the canvas is larger than the document view.
result: tuple[float, float] = zbc.set_canvas_pan(320, 240)

zbrush.commands.set_canvas_zoom(zoom_factor: float) → None¶

Sets the zoom factor of the canvas, scaling the visible canvas area in relation to the actual canvas size.

Warning

This does not set the camera zoom, use set_transform for that.

Parameters:: zoom_factor (float) – The new canvas zoom factor, either making the drawn canvas and each pixol in it smaller than the actual canvas (values below 1.0) or larger than the actual canvas (values above 1.0). The value 1.0 means that each pixol is shown at its actual size.

Example

from zbrush import commands as zbc

# Set the canvas zoom to 2 (each Pixol is shown twice as large) and pan center of the the canvas to 
# the top left corner.
zbc.set_canvas_zoom(2)
zbc.set_canvas_pan(0, 0)

zbrush.commands.set_color(r: int, g: int, b: int) → None¶

Sets the primary color picker used for the brush color in drawing mode and the mesh color in edit mode.

This is the color that is usually shown in the color picker in the left sidebar of the canvas.

Parameters:

r (int) – The new red component of the color in the interval [0, 255].
g (int) – The new green component of the color in the interval [0, 255].
b (int) – The new blue component of the color in the interval [0, 255].

Example

from zbrush import commands as zbc

# Set the drawing color to a dark blue.
zbc.set_color(20, 40, 80)

zbrush.commands.set_hotkey(item_path: str, hotkey: str) → None¶

Sets the hotkey of the specified interface item.

Parameters:

item_path (str) – The item path of the interface item to set the hotkey for.
hotkey (str) –
The hotkey to set.

Shortcut Details

ZBrush has a simple shortcut system which allows for defining shortcuts as strings. A shortcut consists out of a single lowercase character, optionally prefixed by a singular modifier key. So, the shortcut combination ALT + A would be represented as the string ALT+a, and the shortcut CMD + Z would be represented as CMD+z. Whitespace characters between the modifier and the character are not allowed. The following modifier keys are supported:

Modifier

Description

CTRL

Control key (Windows only)

CMD

Command key (macOS only)

ALT

Alternate key (Windows only)

OPT

Option key (macOS only)

TAB

Tab key

ENTER

Enter key

ESC

Escape key

Example

from zbrush import commands as zbc

# Define a simple event handler.
def on_event(sender: str) -> None:
    print(f"Event: {sender}")

# Make sure there is no existing "ZScript:Foo" palette.
if zbc.exists("ZScript:Foo"):
    zbc.close("ZScript:Foo")

# Create a new palette with a button and after that set a hotkey for the button.
zbc.add_subpalette("ZScript:Foo")
zbc.add_button("ZScript:Foo:A", "A", on_event)
zbc.set_hotkey("ZScript:Foo:A", "ALT+a")

zbrush.commands.set_max(item_path: str, value: float) → None¶

Sets the maximum possible numeric the given script generated interface item can take.

Warning

This function only works for interface items created via scripting, natively created interface items cannot be modified.

Parameters:

item_path (str) – The item path of the item to set the maximum possible value for.
value (float) – The new maximum value the item can take.

Example

from zbrush import commands as zbc

def on_change(sender: str, value: float) -> None:
    print(f"Slider changed: {sender} to {value}")

# Make sure there is no existing "ZScript:Foo" palette.
if zbc.exists("ZScript:Foo"):
    zbc.close("ZScript:Foo")

# Create a new palette with a slider with the current value of 50, and a min of 0 and max of 100. 
# Then sets the new max value to 200.
zbc.add_subpalette("ZScript:Foo")
zbc.add_slider("ZScript:Foo:A", 50, 1, 0, 100, "", on_change, width=1.0)
zbc.set_max("ZScript:Foo:A", 200)

zbrush.commands.set_min(item_path: str, value: float) → None¶

Sets the minimum possible numeric the given script generated interface item can take.

Warning

This function only works for interface items created via scripting, natively created interface items cannot be modified.

Parameters:

item_path (str) – The item path of the item to set the minimum possible value for.
value (float) – The new minimum value the item can take.

Example

from zbrush import commands as zbc

def on_change(sender: str, value: float) -> None:
    print(f"Slider changed: {sender} to {value}")

# Make sure there is no existing "ZScript:Foo" palette.
if zbc.exists("ZScript:Foo"):
    zbc.close("ZScript:Foo")

# Create a new palette with a slider with the current value of 50, and a min of 0 and max of 100. 
# Then sets the new min value to 10.
zbc.add_subpalette("ZScript:Foo")
zbc.add_slider("ZScript:Foo:A", 50, 1, 0, 100, "", on_change, width=1.0)
zbc.set_min("ZScript:Foo:A", 10)

zbrush.commands.set_mod(item_path: str, value: float) → None¶

Sets the modifiers state of the given script generated interface item.

Modifiers are used to annotate an interface item, e.g., a slider which additional states. This is commonly used for deformation sliders in the Tool palette, where each modifier represents a different axis or plane of deformation. A modifier always expresses a toggle state, i.e., if it is active or not. Numeric values can not be represented by modifiers.

The modifiers are represented as a bit flags in an integer value. There exist no public defined values for modifier flags, and instead the modifier bit values must be deduced from the GUI. The values are always increasing powers of two as they appear from left to right in the GUI. For example, the Tool:Deformation:Unify slider has the three modifiers x, y, and z. In its upper right corner. x is the first modifier and therefore has the value 1 << 0 = 1 (1 << 0 means 2^0), y the second and has the value 1 << 1 = 2, and z the third has the value 1 << 2 = 4.

Parameters:

item_path (str) – The item path of the item to set the modifiers for.
value (float) – The new modifiers state to set.

Example

from zbrush import commands as zbc

# We define our modifiers as increasing powers of two. We could of course also just write "1 | 4" 
# instead of "ID_X_AXIS | ID_Z_AXIS" below, but this way it is more obvious what we mean. We derive
# the values from the order in which they are shown in the UI.
ID_X_AXIS = 1 << 0  # i.e., 1
ID_Y_AXIS = 1 << 1  # i.e., 2
ID_Z_AXIS = 1 << 2  # i.e., 4

# We now want the X and Z axis modifiers to be active, so we combine them using a bitwise OR.
zbc.set_mod("Tool:Deformation:Unify", ID_X_AXIS | ID_Z_AXIS)

zbrush.commands.set_notebar_text(text: str, progress: float = 0.0) → None¶

Displays a message and optionally progress indicator in the top section of the ZBrush UI.

Note

This is the equivalent of a progress bar in other applications, but it is shown at the top of the UI instead of the bottom.

Parameters:

text (str) – The message that will be shown.
progress (float, optional) – The progress bar value between 0.0 (off) and 1.0 (100%). Defaults to 0.0.

Example

from zbrush import commands as zbc
import time

# A long-running task simulation, where we update the notebar text periodically.
for i in range(1000):
    p: float = i / 1000.0
    zbc.set_notebar_text(f"Script is calculating : {round(100 * p, 2)}%", p)
    time.sleep(0.0025)  # Simulate some work being done

zbc.set_notebar_text("", 0) # Clear the bar once we are done.

zbrush.commands.set_status(item_name: str, value: bool) → None¶

Sets a script-generated interface item as either being responsive or unresponsive to user interactions.

Note

Locking and disabling interface items are conceptually very similar to each other. Here is a brief summary:

set_status, enable, disable: Can only be used on script-generated interface items.
lock, unlock: Can both be used on script-generated and built-in interface items.
Both locking and disabling will make an interface item unresponsive to user interactions and cause it to be drawn in a greyed-out style.
A locked item will show a lock cursor when hovered.

Parameters:

item_path (str) – The item path of the item to set the status for.
value (bool) – True to enable the item, False to disable it.

Example

from zbrush import commands as zbc

# Define a simple event handler.
def on_event(sender: str) -> None:
    print(f"Event: {sender}")

# Make sure there is no existing "ZScript:Foo" palette.
if zbc.exists("ZScript:Foo"):
    zbc.close("ZScript:Foo")

# Create a new palette with a button and after that disable the button.
zbc.add_subpalette("ZScript:Foo")
zbc.add_button("ZScript:Foo:A", "A", on_event)
zbc.set_status("ZScript:Foo:A", False)

Interaction¶

Emulates a click within the canvas area.

Parameters:

X1 (float) – The X coordinate of the click position.
Y1 (float) – The Y coordinate of the click position.
X2 (float, optional) – The X coordinate of the first drag position.
Y2 (float, optional) – The Y coordinate of the first drag position.
X3 (float, optional) – The X coordinate of the second drag position.
Y3 (float, optional) – The Y coordinate of the second drag position.
X4 (float, optional) – The X coordinate of the third drag position.
Y4 (float, optional) – The Y coordinate of the third drag position.
X5 (float, optional) – The X coordinate of the fourth drag position.
Y5 (float, optional) – The Y coordinate of the fourth drag position.
X6 (float, optional) – The X coordinate of the fifth drag position.
Y6 (float, optional) – The Y coordinate of the fifth drag position.
X7 (float, optional) – The X coordinate of the sixth drag position.
Y7 (float, optional) – The Y coordinate of the sixth drag position.
X8 (float, optional) – The X coordinate of the seventh drag position.
Y8 (float, optional) – The Y coordinate of the seventh drag position.

Example

from zbrush import commands as zbc

# Clicks at position (10, 10) in the canvas area.
zbc.canvas_click(10, 10)

# Clicks at position (10, 10) in the canvas area and then drags to (100, 100) and (200, 200).
zbc.canvas_click(10, 10, 100, 100, 200, 200)

Clicks the interface item at the given path.

Parameters:

item_path (str) – The interface path of the item to click.
X1 (float, optional) – The X coordinate of the click position.
Y1 (float, optional) – The Y coordinate of the click position.
X2 (float, optional) – The X coordinate of the first drag position.
Y2 (float, optional) – The Y coordinate of the first drag position.
X3 (float, optional) – The X coordinate of the second drag position.
Y3 (float, optional) – The Y coordinate of the second drag position.
X4 (float, optional) – The X coordinate of the third drag position.
Y4 (float, optional) – The Y coordinate of the third drag position.
X5 (float, optional) – The X coordinate of the fourth drag position.
Y5 (float, optional) – The Y coordinate of the fourth drag position.
X6 (float, optional) – The X coordinate of the fifth drag position.
Y6 (float, optional) – The Y coordinate of the fifth drag position.
X7 (float, optional) – The X coordinate of the sixth drag position.
Y7 (float, optional) – The Y coordinate of the sixth drag position.

Example

from zbrush import commands as zbc

# Emulates a click on the intentisty slider of the Light palette at position (50, 10).
zbc.click("Light:Intensity", 50, 10)

zbrush.commands.disable(item_path: str) → None¶

Makes a script-generated interface item unresponsive to user interactions.

Note

Locking and disabling interface items are conceptually very similar to each other. Here is a brief summary:

set_status, enable, disable: Can only be used on script-generated interface items.
lock, unlock: Can both be used on script-generated and built-in interface items.
Both locking and disabling will make an interface item unresponsive to user interactions and cause it to be drawn in a greyed-out style.
A locked item will show a lock cursor when hovered.

Note

This function is the counterpart to enable and both can be entirely replaced by set_status, see this latter function for code examples, as it is always the better choice.

Parameters:: item_path (str) – The item path of the item to disable.

zbrush.commands.enable(item_path: str) → None¶

Makes a script-generated interface item responsive for user interactions.

Note

Locking and disabling interface items are conceptually very similar to each other. Here is a brief summary:

set_status, enable, disable: Can only be used on script-generated interface items.
lock, unlock: Can both be used on script-generated and built-in interface items.
Both locking and disabling will make an interface item unresponsive to user interactions and cause it to be drawn in a greyed-out style.
A locked item will show a lock cursor when hovered.

Note

This function is the counterpart to disable and both can be entirely replaced by set_status, see this latter function for code examples, as it is always the better choice.

Parameters:: item_path (str) – The item path of the item to enable.

zbrush.commands.freeze(fn: Callable, fade_time: float = 0.0) → None¶

Disables interface updates to avoid slowdowns while heavy operations are performed.

Note

Frozen will be most of the UI, but things like progress bars will still work. So, this is not entierly blocking, only in a sensible manner.

Parameters:

fn (Callable) – The callable to execute which carries out the heavy operations which should not be slowed down.
fade_time (float, optional) – Fade in/out time in secs. Defaults to 0 secs.

Example

from zbrush import commands as zbc

# The payload function.
def payload() -> None:
    '''Subdivides the active tool three times, unwraps it, and then creates a displacement map.
    '''
    for _ in range(3):
        zbc.press("Tool:Geometry:Divide")

    auto_seams: str = "Tool:UV Map:Create (Unwrap):Auto Seams"
    print(f"{zbc.get_status(auto_seams) = }")
    if not zbc.get_status(auto_seams):
        zbc.toggle(auto_seams)

    zbc.press("Tool:UV Map:Create (Unwrap):Unwrap")
    for _ in range(10):
        zbc.press("Tool:Geometry:Lower Res")

    zbc.press("Tool:Displacement Map:Create DispMap")

# Carry out our #payload function while halting UI updates while it is running.
zbc.freeze(payload)

zbrush.commands.hide(item_path: str, show_zoom_rects: bool = False, parent_window: bool = False) → None¶

Removes an interface item from the UI without deleting it.

Parameters:

item_path (str) – The item path of the item to hide.
show_zoom_rects (bool, optional) – if to show zoom rectangles for the hidden item. Defaults to False.
parent_window (bool, optional) – If to also hide the parent window of the item. Defaults to False.

Example

from zbrush import commands as zbc

# Define a simple event handler.
def on_event(sender: str) -> None:
    print(f"Event: {sender}")

# Make sure there is no existing "ZScript:Foo" palette.
if zbc.exists("ZScript:Foo"):
    zbc.close("ZScript:Foo")

# Creates a new palette with two buttons and after that hides one of them.
zbc.add_subpalette("ZScript:Foo")
zbc.add_button("ZScript:Foo:A", "A", on_event)
zbc.add_button("ZScript:Foo:B", "B", on_event)
zbc.hide("ZScript:Foo:B")

zbrush.commands.lock(item_path: str) → None¶

Makes an interface item unresponsive to user interactions.

Note

Locking and disabling interface items are conceptually very similar to each other. Here is a brief summary:

set_status, enable, disable: Can only be used on script-generated interface items.
lock, unlock: Can both be used on script-generated and built-in interface items.
Both locking and disabling will make an interface item unresponsive to user interactions and cause it to be drawn in a greyed-out style.
A locked item will show a lock cursor when hovered.

Parameters:: item_path (str) – The item path of the interface item to lock.

Example

from zbrush import commands as zbc

# Locks the 'Transform:Move' button, making it unresponsive to user interactions.
zbc.lock("Transform:Move")

zbrush.commands.maximize(item_path: str, maximize_all: bool = False) → None¶

Expands an interface item to its maximum size.

This function is primarily applicable to palettes and sub-palettes.

Parameters:

item_path (str) – The item path of the interface item to maximize.
maximize_all (bool, optional) – When set to True, all sub-palettes will also be maximized. Defaults to False.

Example

from zbrush import commands as zbc

# Define a simple event handler.
def on_event(sender: str) -> None:
    print(f"Event: {sender}")

# Make sure there is no existing "ZScript:Foo" palette.
if zbc.exists("ZScript:Foo"):
    zbc.close("ZScript:Foo")

# Creates a new palette with two buttons and then makes sure that the subpalette is unfolded.
zbc.add_subpalette("ZScript:Foo")
zbc.add_button("ZScript:Foo:A", "A", on_event)
zbc.add_button("ZScript:Foo:B", "B", on_event)
zbc.maximize("ZScript:Foo")

zbrush.commands.minimize(item_path: str, minimize_all: bool = False) → None¶

Collapses an interface item to its minimum size.

This function is primarily applicable to palettes and sub-palettes.

Parameters:

item_path (str) – The item path of the interface item to minimize.
minimize_all (bool, optional) – When set to True, all sub-palettes will also be minimized. Defaults to False.

Example

from zbrush import commands as zbc

# Define a simple event handler.
def on_event(sender: str) -> None:
    print(f"Event: {sender}")

# Make sure there is no existing "ZScript:Foo" palette.
if zbc.exists("ZScript:Foo"):
    zbc.close("ZScript:Foo")

# Creates a new palette with two buttons and then makes sure that the subpalette is folded.
zbc.add_subpalette("ZScript:Foo")
zbc.add_button("ZScript:Foo:A", "A", on_event)
zbc.add_button("ZScript:Foo:B", "B", on_event)
zbc.minimize("ZScript:Foo")

zbrush.commands.press(item_path: str) → None¶

Brings a button into its pressed state.

Note

This functions is only applicable to buttons. Switches must be toggled. All UI elements can also be set via set.

Parameters:: item_path (str) – The item path of the interface item to press.

Example

from zbrush import commands as zbc

# Press the "Move" button in the "Transform" palette.
zbc.press("Transform:Move")

zbrush.commands.reset(item: int = 0, version: float = 1.5) → int¶

Brings the ZBrush into a default state associated with a particular version.

This function can be useful to ensure a known state of the interface before running a script. As useful as this function is, it is better not to rely on an implicit interface state and instead explicitly set all relevant interface items to the desired state via set, press, toggle, etc. Recording a macro will implicitly call this function at the start of the macro to ensure a known state.

0	Resets everything.
1	Resets the interface into the default state.
2	Resets the document into a default state.
3	Resets the tools into their default state.
4	Resets the lights into their default state.
5	Resets the materials into their default state.
6	Resets the stencils into their default state.

Category	Option	Description
Query		The search does not support special search operators. Terms are joined by default with OR unless the AND join mode is enabled. Queries can contain search literals denoted by double quotes. E.g., `foo bar` would search for documents that contain `foo` and/or `bar` (depending on the selected join option). But `"foo bar"` would search for the exact phrase "foo bar". The search is case-insensitive. Note that search literals will always implicitly enable strict search mode, even when the user has selected fuzzy mode.
	/	Toggles the visibility of the facet selection panel.
	/	Toggles the visibility of this help panel.
	OR / AND	Toggles between joining search terms with a logical OR or AND. In OR mode, the search will return results that match any of the search terms, while in AND mode, it will only return results that match all of the search terms.
	/	Toggles between fuzzy and strict mode when searching. In fuzzy mode, the search is more lenient and may return more results, while in strict mode, the search is more exacting. Switching modes may affect the relevance of the results.
	/	Toggles between detailed and compact result views. The detailed view shows more information per search hit.
	/	Toggles sorting the search results by relevance only or by a combination of classification and relevance. When sorting by classification and relevance, results are grouped by their type (e.g., pages, classes, methods) and then sorted by relevance within each group.
Facets		Facets restrict the search to specific content types. You must have at least one facet enabled per facet group to see any results. Domain is the largest facet group, enabling or disabling whole groups of content types. Entities are the next level down, allowing you to search within specific types of content such as generic pages or a function definition. Contexts are the most granular level, allowing you to search within specific contexts of the selected entity such as a code block ot the name of an entity.
Domain	API	Enable matches within API documentation pages.
	Manuals	Enable matches within general documentation pages.
	Examples	Enable matches within example pages.
Entity	Page	Enable matches within a page body that are not one of the following entities.
	Classes	Enable matches within class definitions.
	Methods	Enable matches within class method definitions.
	Functions	Enable matches within module function definitions.
	Attributes	Enable matches within class or module attribute definitions.
Context	Paragraphs	Enable matches within normal text paragraphs of a page.
	Headings	Enable matches within the headings of a page.
	Code	Enable matches within code blocks of a page (e.g., in the Examples domain or code blocks embed elsewhere).
	Names	Enable matches within the names of API entities. This searches the plain names (`func`), not the qualified names (`foo.bar.func`).
	Signatures	Enable matches within the signatures of API entities. The signature is what is shown on top of the entity description, e.g., `foo.bar.func(a: int, b: str = "Hello") -> bool`. When you want to search for fully qualified names, you should enable this option and disable the "Names" option.
	Metadata	Enable matches within the metadata of entities.

Gui API¶

Signatures¶

Descriptions¶

Create¶

Dialogs¶

Getters¶

Setters¶

Interaction¶

Search