vsketch.shape#
Overview#
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()
, andpoint()
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. SeeVsketch.shape()
’s documentation for details.Note
It is helpful to understand the fundamental difference between a
Vsketch
andShape
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 thedifference
mode (which subtracts a primitive from the existing shape). This abstract representation is turned into actual plotter line work (including hatching if enabled withVsketch.fill()
) only when it is drawn in a sketch usingVsketch.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 (seeVsketch.point()
), and the resulting, ready-to-be-plotted paths are added to the sketch.Overview
# 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 theellipse()
function, the way arguments are interpreted is influenced by themode
argument or the mode set withVsketch.ellipseMode()
of theVsketch
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), orsymmetric_difference
(only the none overlapping parts of the shape and circle are kept).See also
Vsketch.circle()
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
, andh
parameters are interpreted depends on the current ellipse mode of theVsketch
instance used to create the shape.By default,
x
andy
set the location of the ellipse center,w
sets its width, andh
sets its height. The way these parameters are interpreted can be changed with themode
argument or theVsketch.ellipseMode()
function of theVsketch
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), orsymmetric_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
, andh
parameters are interpreted depends on the current ellipse mode (seeellipse()
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, andpie
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), orsymmetric_difference
(only the none overlapping parts of the shape and arc are kept).See also
Vsketch.arc()
Vsketch.ellipseMode()
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’
- rect(x: float, y: float, w: float, h: float, *radii: float, tl: float | None = None, tr: float | None = None, br: float | None = None, bl: float | None = None, mode: str | None = None, op: BooleanOperation = 'union') None #
Add a rectangle to the shape.
The way
x
,y
,w
, andh
parameters are interpreted depends on the current rect mode of theVsketch
instance used to create the shape.By default,
x
andy
set the location of the upper-left corner,w
sets the width, andh
sets the height. The way these parameters are interpreted can be changed with themode
argument or therectMode()
function of theVsketch
instance used to create this shape.The optional parameters
tl
,tr
,br
andbl
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), orsymmetric_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 themode
argument or theVsketch.rectMode()
of theVsketch
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), orsymmetric_difference
(only the none overlapping parts of the shape and square are kept).See also
Vsketch.square()
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” modeop -- 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), orsymmetric_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), orsymmetric_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), orsymmetric_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’
- geometry(shape: shapely.geometry.LineString | shapely.geometry.LinearRing | shapely.geometry.MultiPoint | shapely.geometry.MultiPolygon | shapely.geometry.MultiLineString | shapely.geometry.Point | shapely.geometry.Polygon, op: BooleanOperation = 'union') None #
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), orsymmetric_difference
(only the none overlapping parts of the shape and geometry are kept). Theop
argument is ignored ifshape
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 theVsketch
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"
, theshape
’s polygons, lines and points are merged into this instance. When using other operations ("difference"
,"intersection"
, or"symmetric_difference"
), the corresponding operation is applied withshape
’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’