Example `mod_subtool_array`¶

Demonstrates how to construct an array of sub tools within a tool.

Code¶

"""Demonstrates how to construct an array of sub tools within a tool.

Primarily highlights how to select a tool by name and automate getting its PolyMesh3D derivate. Also
discusses (but does not show) some alternative routes. The script will create a 3x3x2 array of 
colorized Cube3D sub tools. You can change the generated sub-tool with the module attribute 
#TOOL_NAME.

You must draw into the canvas after the script ran to see its tool result.
"""
__author__ = "Ferdinand Hoppe, Jan Wesbuer"
__date__ = "22/08/2025"
__copyright__ = "Maxon Computer"

import itertools
import re

TOOL_NAME: str = "Cube3D" # The name of the tool to create an array of.

import zbrush.commands as zbc

def make_poly_mesh_from_tool(tool_name: str) -> None:
    """Creates an an editable PolyMesh3D from the specified tool #tool_name.
    """
    # One of the main "tricks" when working with tools and brushes is to ignore most of the 
    # specialized API functions such as #get_tool_count or #get_tool_path and instead work with item
    # paths. Every loaded tool will have an item path such as "Tool:Cube3D" or "Tool:Sphere3D". So, 
    # we can simply check if such item exists and then click it.

    # Check if there is already an existing PolyMesh3D tool with the given name, and if so, 
    # select it.
    tool_path: str = f"Tool:{tool_name}"
    poly_tool_path: str = f"Tools:PM3D_{tool_name}"
    if zbc.exists(poly_tool_path):
        zbc.press(poly_tool_path)
        return

    if zbc.exists(tool_path):
        zbc.press(tool_path)
        zbc.press("Tool:Make PolyMesh3D")
    else:
        raise RuntimeError(f"There is no tool named '{tool_name}' in the current ZBrush session.")

def create_tool_array(tool_name: str, shape: tuple[int], offsets: tuple[float], 
                      colorize: bool) -> None:
    """Clones the tool with the given #tool_name in an array with the given #shape and #offsets.

    Args:
        tool_name (str): The tool name of the tool to clone.
        shape (tuple[int]): The shape of the array (x, y, z).
        offsets (tuple[float]): The offsets for each axis (x, y, z).
        colorize (bool): Whether to colorize the duplicated tools.
    """
    # Enable Mrgb draw mode when we should colorize the clones and then activate the given tool.
    if colorize: 
        zbc.press("Draw:Mrgb")

    # Create a PolyMesh 3D for the given #tool_name.
    make_poly_mesh_from_tool(tool_name)

    # Now iterate over the shape of the array. itertools.product yields the cartesian product for
    # its inputs, i.e., their combinations. It is the same as three nested loops.
    for ix, iy, iz in itertools.product(range(shape[0]), range(shape[1]), range(shape[2])):

        # Compute the position and color for this clone. The position is just the product of the
        # current index (ix, iy, iz) and the offsets. The color is just a makeshift gradient based
        # on the current index.
        x: float = offsets[0] * ix
        y: float = offsets[1] * iy
        z: float = offsets[2] * iz
        r: int = int(((ix + 1) / (shape[0])) * 255)
        g: int = int(((iy + 1) / (shape[1])) * 255)
        b: int = int(((iz + 1) / (shape[2])) * 255)

        # Create a new sub tool for the tool, and then set its position and color.
        zbc.press("Tool:SubTool:Duplicate")
        zbc.set("Tool:Geometry:X Position", x)
        zbc.set("Tool:Geometry:Y Position", y)
        zbc.set("Tool:Geometry:Z Position", z)
        zbc.set_color(r, g, b)
        zbc.press("Color:FillObject")

def main() -> None:
    """Executed when ZBrush runs this script.
    """
    # Create a 3x3x2 array of #TOOL_NAME tools with a spacing of 3 units on each axis between 
    # each sub tool.
    create_tool_array(tool_name=TOOL_NAME,
                      shape=(3, 3, 2),
                      offsets=(3.0, 3.0, 3.0),
                      colorize=True)

if __name__ == "__main__":
    main()

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.

Example mod_subtool_array¶

Code¶

Search

Example `mod_subtool_array`¶