vsketch.shape#

Overview#

Classes#
`Shape`	Reusable and drawable shape with support for boolean operations.

Attributes#
`BooleanOperation`	Specify how to combine two shapes.

Classes#

class vsketch.shape.Shape(vsk: vsketch.Vsketch)#

Reusable and drawable shape with support for boolean operations.

A shape is a reusable graphical element made of polygons, lines and points. Shapes are built using primitives in a very similar way to how Vsketch works with the added capability of using boolean drawing operation (union, difference, intersection, or exclusive union).

Shapes must be created using a Vsketch instance:

shape = vsk.createShape()

Shapes consist of an area (which may be disjoint and have holes), a set of lines, and a set of points (both of which may be empty). Lines and points are added to the shape using the line(), bezier(), and point() methods.

The shape’s area can be built with primitives similar to that of Vsketch:

shape.square(0, 0, 1, mode="radius")
shape.square(0.5, 0.5, 1, mode="radius")

By default, an union operation applied when new primitives are added. Other boolean operations are available. For example, a hole can be punched in the shape as follows:

shape.circle(0, 0, 0.5, mode="radius", op="difference")

Finally, a shape can be drawn to a sketch with the Vsketch.shape() method:

vsk.stroke(1)
vsk.fill(2)
vsk.shape(shape)

Vsketch.shape() can control whether the lines and points which intersects with the shape’s area are masked. For example, it’s best to enable masking when the shape’s area is to be hatched. See Vsketch.shape()’s documentation for details.

Note

It is helpful to understand the fundamental difference between a Vsketch and Shape instance.

At any point in time, Vsketch instances contains a set of paths which correspond exactly to what the plotter will draw and is considered read-only (One of the reason for that is that scaling existing geometries would invalidate any hatching).

On the other hand, a Shape instance is an abstract geometrical representation which can, at any point in time, be further modified, for example using the difference mode (which subtracts a primitive from the existing shape). This abstract representation is turned into actual plotter line work (including hatching if enabled with Vsketch.fill()) only when it is drawn in a sketch using Vsketch.shape(). At this point, the final scaling is applied (based on the current transformation matrix), the hatching (if any) is computed, points are transformed into small circles (see Vsketch.point()), and the resulting, ready-to-be-plotted paths are added to the sketch.

Overview

Methods#
`point`(x, y)	Add a point to the shape.
`line`(x1, y1, x2, y2)	Add a line to the shape.
`circle`(x, y, diameter, radius, mode, op)	Add a circle to the shape.
`ellipse`(x, y, w, h, mode, op)	Add an ellipse to the shape.
`arc`(x, y, w, h, start, stop, degrees, close, mode, op)	Add an arc to the shape.
`rect`(x, y, w, h, *radii, tl, tr, br, bl, mode, op)	Add a rectangle to the shape.
`square`(x, y, extent, mode, op)	Add a square to the shape.
`quad`(x1, y1, x2, y2, x3, y3, x4, y4, op)	Add a quadrilateral to the shape.
`triangle`(x1, y1, x2, y2, x3, y3, op)	Add a triangle to the shape.
`polygon`(x, y, holes, close, op)	Add a polygon to the shape.
`geometry`(shape, op)	Add a Shapely geometry to the shape.
`bezier`(x1, y1, x2, y2, x3, y3, x4, y4)	Add a Bezier curve to the shape.
`shape`(shape, op)	Combine the shape with another shape.

Members

point(x: float, y: float) → None#: Add a point to the shape. :param x: X coordinate of the point :param y: Y coordinate of the point

line(x1: float, y1: float, x2: float, y2: float) → None#

Add a line to the shape.

Parameters:

x1 -- X coordinate of starting point
y1 -- Y coordinate of starting point
x2 -- X coordinate of ending point
y2 -- Y coordinate of ending point

circle(x: float, y: float, diameter: float | None = None, radius: float | None = None, mode: str | None = None, op: BooleanOperation = 'union') → None#

Add a circle to the shape.

The level of detail used to approximate the circle is controlled by Vsketch.detail(). As for the ellipse() function, the way arguments are interpreted is influenced by the mode argument or the mode set with Vsketch.ellipseMode() of the Vsketch instance used to create the shape.

This function support multiple boolean mode with the op argument: union (default, the circle is added to the shape), difference (the circle is cut off the shape), intersection (only the overlapping part of the circle is kept in the shape), or symmetric_difference (only the none overlapping parts of the shape and circle are kept).

See also

Vsketch.circle()
ellipse()
Vsketch.ellipseMode()

Example

>>> import vsketch
>>> vsk = vsketch.Vsketch()
>>> vsk.circle(0, 0, 10)  # by default, diameter is used
>>> vsk.circle(0, 0, radius=5)  # radius can be specified instead

Parameters:

x -- x coordinate of the center
y -- y coordinate of the center
diameter -- circle diameter (or None if using radius)
radius -- circle radius (or None if using diameter
mode -- one of ‘center’, ‘radius’, ‘corner’, ‘corners’
op -- one of ‘union’, ‘difference’, ‘intersection’, or ‘symmetric_difference’

ellipse(x: float, y: float, w: float, h: float, mode: str | None = None, op: BooleanOperation = 'union') → None#

Add an ellipse to the shape.

The way x, y, w, and h parameters are interpreted depends on the current ellipse mode of the Vsketch instance used to create the shape.

By default, x and y set the location of the ellipse center, w sets its width, and h sets its height. The way these parameters are interpreted can be changed with the mode argument or the Vsketch.ellipseMode() function of the Vsketch instance used to create the shape.

This function support multiple boolean mode with the op argument: union (default, the ellipse is added to the shape), difference (the ellipse is cut off the shape), intersection (only the overlapping part of the ellipse is kept in the shape), or symmetric_difference (only the none overlapping parts of the shape and ellipse are kept).

See also

Vsketch.ellipse()
Vsketch.ellipseMode()

Examples

By default, the argument are interpreted as the center coordinates as well as the width and height:

>>> import vsketch
>>> vsk = vsketch.Vsketch()
>>> vsk.ellipse(2, 2, 1, 4)

Alternative ellipse mode can be set as the default for subsequence calls with ellipseMode():

>>> vsk.ellipseMode(mode="radius")
>>> vsk.ellipse(3, 3, 2, 1)
>>> vsk.ellipse(8, 8, 2, 1)  # both of these call are in "radius" mode

Or they can be set for a single call only:

>>> vsk.ellipse(2, 2, 10, 12, mode="corners")

Parameters:

x -- by default, x coordinate of the ellipse center
y -- by default, y coordinate of the ellipse center
w -- by default, the ellipse width
h -- by default, the ellipse height
mode -- “corner”, “corners”, “radius”, or “center” (see ellipseMode())
op -- one of ‘union’, ‘difference’, ‘intersection’, or ‘symmetric_difference’

arc(x: float, y: float, w: float, h: float, start: float, stop: float, degrees: bool | None = False, close: str | None = 'no', mode: str | None = None, op: BooleanOperation = 'union') → None#

Add an arc to the shape.

The way x, y, w, and h parameters are interpreted depends on the current ellipse mode (see ellipse() for a detailed explanation) and refer to the arc’s underlying ellipse.

The close parameter controls the arc’s closure: no keeps it open, chord closes it with a straight line, and pie connects the two endings with the arc center.

This function support multiple boolean mode with the op argument: union (default, the arc is added to the shape), difference (the arc is cut off the shape), intersection (only the overlapping part of the arc is kept in the shape), or symmetric_difference (only the none overlapping parts of the shape and arc are kept).

See also

Vsketch.arc()
Vsketch.ellipseMode()
ellipse()

Example

>>> import vsketch
>>> vsk = vsketch.Vsketch()
>>> vsk.arc(2, 3, 5, 4, 0, np.pi / 2)
>>> vsk.arc(6, 6, 1, 2, np.pi / 2, np.pi, mode="corner", close="pie")

Parameters:

x -- by default, X coordinate of the associated ellipse center
y -- by default, Y coordinate of the associated ellipse center
w -- by default, width of the associated ellipse
h -- by default, height of the associated ellipse
start -- angle to start the arc (in radians)
stop -- angle to stop the arc (in radians)
degrees -- set to True to use degrees for start and stop angles (default: False)
close -- “no”, “chord” or “pie” (default: “no”)
mode -- “corner”, “corners”, “radius”, or “center” (see ellipseMode())
op -- one of ‘union’, ‘difference’, ‘intersection’, or ‘symmetric_difference’

Add a rectangle to the shape.

The way x, y, w, and h parameters are interpreted depends on the current rect mode of the Vsketch instance used to create the shape.

By default, x and y set the location of the upper-left corner, w sets the width, and h sets the height. The way these parameters are interpreted can be changed with the mode argument or the rectMode() function of the Vsketch instance used to create this shape.

The optional parameters tl, tr, br and bl define the radius used for each corner (default: 0). If some corner radius is not specified, it will be set equal to the previous corner radius. If the sum of two consecutive corner radii are greater than their associated edge lenght, their values will be rescaled to fit the rectangle.

This function support multiple boolean mode with the op argument: union (default, the rectangle is added to the shape), difference (the rectangle is cut off the shape), intersection (only the overlapping part of the rectangle is kept in the shape), or symmetric_difference (only the none overlapping parts of the shape and rectangle are kept).

See also

Vsketch.rect()
Vsketch.rectMode()

Examples

By default, the argument are interpreted as the top left corner as well as the width and height:

>>> import vsketch
>>> vsk = vsketch.Vsketch()
>>> vsk.rect(0, 0, 2, 4)  # 2x4 rectangle with top-left corner at (0, 0)

Alternative rect mode can be set as the default for subsequence calls with rectMode():

>>> vsk.rectMode(mode="radius")
>>> vsk.rect(3, 3, 2, 1)
>>> vsk.rect(8, 8, 2, 1)  # both of these call are in "radius" mode

Or they can be set for a single call only:

>>> vsk.rect(2, 2, 10, 12, mode="corners")

Drawing rectangles with rounded corners:

>>> vsk.rect(0, 0, 5, 5, 5)  # all corners are rounded with a radius of 5
>>> vsk.rect(0, 0, 4, 4, 1.5, 0.5, 1.5, 1)  # all corner radii specified
>>> vsk.rect(5, 5, 20, 20, tr=3, bl=5)  # specified corners rounded, others
                                        # default to 0

Parameters:

x -- by default, x coordinate of the top-left corner
y -- by default, y coordinate of the top-left corner
w -- by default, the rectangle width
h -- by default, the rectangle height (same as width if not provided)
tl -- top-left corner radius (0 if not provided)
tr -- top-right corner radius (same as tl if not provided)
br -- bottom-right corner radius (same as tr if not provided)
bl -- bottom-left corner radius (same as br if not provided)
mode -- “corner”, “corners”, “radius”, or “center” (see rectMode())
op -- one of ‘union’, ‘difference’, ‘intersection’, or ‘symmetric_difference’

square(x: float, y: float, extent: float, mode: str | None = None, op: BooleanOperation = 'union') → None#

Add a square to the shape.

As for the rect() function, the way arguments are interpreted is influenced by the mode set with the mode argument or the Vsketch.rectMode() of the Vsketch instance used to create the shape.

This function support multiple boolean mode with the op argument: union (default, the square is added to the shape), difference (the square is cut off the shape), intersection (only the overlapping part of the square is kept in the shape), or symmetric_difference (only the none overlapping parts of the shape and square are kept).

See also

Vsketch.square()
rect()
Vsketch.rectMode()

Example

>>> import vsketch
>>> vsk = vsketch.Vsketch()
>>> vsk.square(2, 2, 2.5)

Parameters:

x -- X coordinate of top-left corner
y -- Y coordinate of top-left corner
extent -- width and height of the square
mode -- “corner”, “radius”, or “center” (see rectMode()) — note that the “corners” mode is meaningless for this function, and is interpreted as the “corner” mode
op -- one of ‘union’, ‘difference’, ‘intersection’, or ‘symmetric_difference’

quad(x1: float, y1: float, x2: float, y2: float, x3: float, y3: float, x4: float, y4: float, op: BooleanOperation = 'union') → None#

Add a quadrilateral to the shape.

This function support multiple boolean mode with the op argument: union (default, the quad is added to the shape), difference (the quad is cut off the shape), intersection (only the overlapping part of the quad is kept in the shape), or symmetric_difference (only the none overlapping parts of the shape and quad are kept).

See also

Vsketch.quad()

Example

>>> import vsketch
>>> vsk = vsketch.Vsketch()
>>> vsk.quad(0, 0, 1, 3.5, 4.5, 4.5, 3.5, 1)

Parameters:

x1 -- X coordinate of the first vertex
y1 -- Y coordinate of the first vertex
x2 -- X coordinate of the second vertex
y2 -- Y coordinate of the second vertex
x3 -- X coordinate of the third vertex
y3 -- Y coordinate of the third vertex
x4 -- X coordinate of the last vertex
y4 -- Y coordinate of the last vertex
op -- one of ‘union’, ‘difference’, ‘intersection’, or ‘symmetric_difference’

triangle(x1: float, y1: float, x2: float, y2: float, x3: float, y3: float, op: BooleanOperation = 'union') → None#

Add a triangle to the shape.

This function support multiple boolean mode with the op argument: union (default, the triangle is added to the shape), difference (the triangle is cut off the shape), intersection (only the overlapping part of the triangle is kept in the shape), or symmetric_difference (only the none overlapping parts of the shape and triangle are kept).

See also

Vsketch.triangle()

Example

>>> import vsketch
>>> vsk = vsketch.Vsketch()
>>> vsk.triangle(2, 2, 2, 3, 3, 2.5)

Parameters:

x1 -- X coordinate of the first corner
y1 -- Y coordinate of the first corner
x2 -- X coordinate of the second corner
y2 -- Y coordinate of the second corner
x3 -- X coordinate of the third corner
y3 -- Y coordinate of the third corner
op -- one of ‘union’, ‘difference’, ‘intersection’, or ‘symmetric_difference’

polygon(x: Iterable[float] | Iterable[Sequence[float]] | Iterable[complex], y: Iterable[float] | None = None, holes: Iterable[Iterable[Sequence[float]]] = (), close: bool = False, op: BooleanOperation = 'union') → None#

Add a polygon to the shape.

This function support multiple boolean mode with the op argument: union (default, the polygon is added to the shape), difference (the polygon is cut off the shape), intersection (only the overlapping part of the polygon is kept in the shape), or symmetric_difference (only the none overlapping parts of the shape and polygon are kept).

See also

Vsketch.polygon()

Examples

A single iterable of size-2 sequence can be used:

>>> import vsketch
>>> vsk = vsketch.Vsketch()
>>> vsk.polygon([(0, 0), (2, 3), (3, 2)])

A 1-dimension iterable of complex can also be used:

>>> vsk.polygon([3 + 3j, 2 + 5j, 4 + 7j])

Alternatively, two iterables of float can be passed:

>>> vsk.polygon([0, 2, 3], [0, 3, 2])

The polygon can be automatically closed if needed:

>>> vsk.polygon([0, 2, 3], [0, 3, 2], close=True)

Finally, polygons can have holes, which is useful when using fill():

>>> vsk.polygon([0, 1, 1, 0], [0, 0, 1, 1],
...             holes=[[(0.3, 0.3), (0.3, 0.6), (0.6, 0.6)]])

Parameters:

x -- X coordinates or iterable of size-2 points (if y is omitted)
y -- Y coordinates
holes -- list of holes inside the polygon
close -- the polygon is closed if True
op -- one of ‘union’, ‘difference’, ‘intersection’, or ‘symmetric_difference’

Add a Shapely geometry to the shape.

This function should accept any of LineString, LinearRing, MultiPoint, MultiPolygon, MultiLineString, Point, or Polygon.

This function support multiple boolean modes with the op argument: union (default, the geometry is added to the shape), difference (the geometry is cut off the shape), intersection (only the overlapping part of the geometry is kept in the shape), or symmetric_difference (only the none overlapping parts of the shape and geometry are kept). The op argument is ignored if shape is a MultiPoint or Point object.

See also

Vsketch.geometry()

Parameters:

shape (Shapely geometry) -- a supported shapely geometry object
op -- one of ‘union’, ‘difference’, ‘intersection’, or ‘symmetric_difference’

bezier(x1: float, y1: float, x2: float, y2: float, x3: float, y3: float, x4: float, y4: float) → None#

Add a Bezier curve to the shape.

Bezier curves are defined by a series of anchor and control points. The first two arguments specify the first anchor point and the last two arguments specify the other anchor point. The middle arguments specify the control points which define the shape of the curve.

The level of detail of the bezier curve is controlled using the Vsketch.detail() method on the Vsketch instance used to create the shape.

See also

Vsketch.bezierPoint()
Vsketch.bezierTangent()
Vsketch.detail()
Vsketch.bezier()

Parameters:

x1 -- X coordinate of the first anchor point
y1 -- Y coordinate of the first anchor point
x2 -- X coordinate of the first control point
y2 -- Y coordinate of the first control point
x3 -- X coordinate of the second control point
y3 -- Y coordinate of the second control point
x4 -- X coordinate of the second anchor point
y4 -- Y coordinate of the second anchor point

shape(shape: Shape, op: BooleanOperation = 'union') → None#

Combine the shape with another shape.

This function can combine another shape with this shape, using various boolean mode. When op is set to "union", the shape’s polygons, lines and points are merged into this instance. When using other operations ("difference", "intersection", or "symmetric_difference"), the corresponding operation is applied with shape’s polygon, but its lines and points are ignored.

Parameters:

shape -- the shape to combine
op -- one of ‘union’, ‘difference’, ‘intersection’, or ‘symmetric_difference’

Attributes#

vsketch.shape.BooleanOperation#

Specify how to combine two shapes.

Options: one of ‘union’, ‘difference’, ‘intersection’, or ‘symmetric_difference’