Brush Shape Plugins

A Brush Shape plugin adds a new option to the Brush and Select tools for choosing the shape of the tool. A shape plugin must return a Selection object that defines the range of blocks in the shape, and may provide a Widget object to present shape-specific options in the tool’s options panel.

Shape plugins must inherit from mcedit2.editortools.brush.shapes.BrushShape. There are two ways to implement the shape: as a function that returns a boolean array, or as a function that returns a new Selection object.

The BrushShape instance must also have an ID member which is a string that uniquely identifies this brush shape, and must have a displayName member which is the shape’s human-readable name. It may also have an icon member which is an absolute path to an image file to display as the shape’s icon.

As a boolean array

BrushShape.shapeFunc(blockPositions, selectionSize)[source]

Return a 3D boolean array for the blocks selected by this shape in a requested area.

(Note that numpy arrays have a ‘shape’ attribute which gives the length of the array along each dimension. Sorry for the confusion.)

The coordinates of the blocks are given by blockPositions, which is a 4D array where the first axis has size 3 and represents the Y, Z, and X coordinates. The coordinates given are relative to the bounding box for this shape. The remaining 3 axes have the shape of the requested area.

blockPositions may be separated into coordinate arrays by writing y, z, x = blockPositions.

The size and shape of the array to return is given by the shapes of the arrays in blockPositions.

The size of the shape’s bounding box is given by selectionSize.

Parameters:
  • blockPositions (numpy.ndarray[ndims=4,dtype=float32]) – Coordinates of requested blocks relative to Shape’s bounding box.
  • selectionSize ((int, int, int)) – Size of the Shape’s bounding box.
Returns:

mask – Boolean array of the same shape as blockPositions[0] where selected blocks are True

Return type:

numpy.ndarray[ndims=3,dtype=bool]

This is the simpler way of implementing a brush shape. When the shape is used, shapeFunc will be called repeatedly for each section of the selection. It will be passed the coordinates of each block in the selection, relative to the selection’s origin point, along with the full size of the selection. Using these values, you will compute and return a boolean array (of the same shape as the coordinate array) that indicates whether each block in the section should be selected.

blockPositions is a multi-dimensional array where the first axis selects the x, y, or z coordinates; e.g. to access the x coordinate array, write blockPositions[0].

selectionSize is a simple tuple of three positive integers.

For example, this brush shape selects all blocks whose relative Y coordinate is more than 5 - in other words, it is a rectangular selection that excludes the bottom five layers of its bounding box:

class Example(BrushShape):
    ID = "example"
    displayName = "Example Brush Shape"

    def shapeFunc(self, blockPositions, size):
        y = blockPositions[1]
        mask = y > 5
        return mask

Note that shapeFunc does not have access to the world dimension where the selection is made, and cannot inspect the world and react to its contents. shapeFunc is meant for shapes that are purely mathematical in nature and can be made using simple computations on the coordinates and the selection’s size.

As a Selection object

BrushShape.createShapedSelection(box, dimension)[source]

Return a SelectionBox that selects the blocks inside this shape.

The default implementation returns a ShapeFuncSelection using self.shapeFunc. Subclasses may override this to return different types of SelectionBox.

TODO: BitmapSelectionBox

Parameters:
  • box (BoundingBox) – Bounding box of the selection
  • dimension (WorldEditorDimension) – Dimension to create the shaped selection for.
Returns:

box – SelectionBox object that selects all blocks inside this shape

Return type:

SelectionBox

This is the more advanced way of implementing a brush shape. createShapedSelection is given the rectangular bounding box that encloses the shape, and the world dimension where the shape is being used. It must return a SelectionBox instance, which may be one of the existing selection classes or a class of your own design. For details about SelectionBox subclasses, see selection