# Shape

- Shape.Composite

A 2D geometric primitive. A Shape can be one of the geometric types Line, LineSegment, Polyline, Rectangle, Circle, Ellipse, Arc, Annulus or Sector. The Shape object is represented in mathematical analytical form. Operations such as finding intersection points, distances and transforming the Shape are for this reason efficiently computed.

Note when used in context of images: The Shapes are defined in the image world coordinate system, i.e., in world scale (typically millimeters) and not in pixel coordinates. The image world coordinate system is left handed, with the x-axis pointing rightwards and the y-axis pointing downwards, and the origin centered at the upper left pixel. In this coordinate system, positive translations along the y-axis will shift the shape downwards, and positive rotations are clockwise. Thus, this is different compared to usage in a right-handed coordinate system context.

Shape.appendPoint(shape, point)
  Arguments:

    - shape (`Shape`)

    - point (`Point`)

  Append a point to a polyline shape.

Shape.clone(inputShape)
  Argument:

    - inputShape (`Shape`)

  Return type:

    `Shape`

  Create an independent copy of this shape. If the input is a vector of shapes, the output is a vector of shapes.

Shape.contains(shape, point)
  Arguments:

    - shape (`Shape`)

    - point (`Point`)

  Return type:

    `boolean`

  Check if the input point is contained within the enclosed area of the given shape. Always returns false if the shape is not closed. If more than one shape is provided true is returned if the point is inside any of the shapes. If more than one point is provided a vector is returned with one value for each input point.

Shape.createAnnulus(center, outerRadius, thickness)
  Arguments:

    - center (`Point`)

    - outerRadius (`float`)

    - thickness (`float`)

  Return type:

    `Shape`

  Create an annulus with an outer diameter and a thickness. The parameters can also be vectors, of equal length, to create several annuli.

Shape.createArc(center, radius, angle, deltaAngle)
  Arguments:

    - center (`Point`)

    - radius (`float`)

    - angle (`float`)

    - deltaAngle (`float`)

  Return type:

    `Shape`

  Create an arc shape (part of a circle). Radius and deltaAngle must be non-negative. By providing vectors of centers, radii, angles and delta angle several arcs can be created. All vectors must be of equal length.

Shape.createCircle(center, radius)
  Arguments:

    - center (`Point`)

    - radius (`float`)

  Return type:

    `Shape`

  Create circle shape(s). By providing vectors of centers and radii, several circles can be created. Center can be a single point or a vector. If it is a vector, radius must either be a vector of the same size or a singular value.

Shape.createEllipse(center, radiusX, radiusY, rotation)
  Arguments:

    - center (`Point`)

    - radiusX (`float`)

    - radiusY (`float`)

    - rotation (`float`)

  Return type:

    `Shape`

  Create an ellipse shape. Radii must be non-negative. By providing vectors of centers, radiusX, radiusY and rotation, several ellipses can be created. All vectors must be of equal length.

Shape.createLine(point1, point2)
  Arguments:

    - point1 (`Point`)

    - point2 (`Point`)

  Return type:

    `Shape`

  Create an infinite line shape that connects (and extends beyond) two given points. The points must not be the same. By providing vectors of end-points, several infinite lines can be created. The vectors must be of equal length.

Shape.createLineSegment(point1, point2)
  Arguments:

    - point1 (`Point`)

    - point2 (`Point`)

  Return type:

    `Shape`

  Create a finite length line segment between two given endpoints. By providing vectors of end-points, several line segments can be created.

Shape.createPolyline(points, closed)
  Arguments:

    - points (`Point`)

    - closed (`boolean`)

  Return type:

    `Shape`

  Create a polyline shape (sequence of line segments connected to an open contour or closed polygon).

Shape.createRectangle(center, width, height, rotation)
  Arguments:

    - center (`Point`)

    - width (`float`)

    - height (`float`)

    - rotation (`float`)

  Return type:

    `Shape`

  Create a rectangle shape. Width and height must be non-negative. By providing vectors of centers, width, height and rotation, several rectangles can be created. All vectors must be of equal length.

Shape.createSector(center, innerRadius, outerRadius, angle, deltaAngle)
  Arguments:

    - center (`Point`)

    - innerRadius (`float`)

    - outerRadius (`float`)

    - angle (`float`)

    - deltaAngle (`float`)

  Return type:

    `Shape`

  Create a circular sector defining a region contained within two angles, an inner and an outer radius. Radii and deltaAngle must be non-negative, outerRadius must be larger than innerRadius. By providing vectors of centers, innerRadius, outerRadius, angle and deltaAngle several sectors can be created. All vectors must be of equal length.

Shape.cropLine(line, rectangle)
  Arguments:

    - line (`Shape`)

    - rectangle (`Shape`)

  Return type:

    `Shape`

  Returns the part of a line/line segment within a rectangle as a new line segment. If the line/line segment does not intersect the rectangle, nil is returned. Several lines/line segments in a vector can be cropped at once, in which case all lines/line segemnts must be within the box for the call to succeed.

Shape.getAnnulusParameters(annulus)
  Argument:

    - annulus (`Shape`)

  Return type:

    `Point`

  Get the parameters defining the annulus. Can only be called for annulus shapes (returns nil otherwise). A vector of annulus shapes can be provided, in which case vectors of parameters are returned.

Shape.getArcParameters(arc)
  Argument:

    - arc (`Shape`)

  Return type:

    `Point`

  Get the parameters defining the arc. Can only be called for arc shapes (returns nil otherwise). A vector of arc shapes can be provided, in which case vectors of parameters are returned.

Shape.getArea(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `float`

  Get the area of the region enclosed by a 2D Shape. A vector of shapes can be provided, in which case a vector of areas is returned.

Shape.getBoundingBox(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `Shape`

  Get a rectangular axis-aligned bounding box of the shape (minimum box that contains the shape). The returned box is another Shape object. To get the actual bounds as float values, call getBounds.

Shape.getBoundingBoxOriented(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `Shape`

  Gets a rectangular rotated bounding box of the given shape. This is the minimum area rectangle that still contains the shape. The return box is another Shape object.

Shape.getBounds(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `float`

  Get the bounds of the shape as float values. Fails for invalid and unbounded shapes.

Shape.getCenterOfGravity(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `Point`

  Get the center of gravity of the region enclosed within the shape for closed shapes. For open shapes, the center of gravity of the contour is returned. Returns nil for infinite or invalid shapes.

Shape.getCircleParameters(circle)
  Argument:

    - circle (`Shape`)

  Return type:

    `Point`

  Get the parameters defining the circle. Can only be called for circle shapes (returns nil otherwise). A vector of circle shapes can be provided, in which case vectors of parameters are returned.

Shape.getClosestContourPoint(shape, point)
  Arguments:

    - shape (`Shape`)

    - point (`Point`)

  Return type:

    `Point`

  Get the closest point on a shape contour to a given external point. Fails if the point is not a 2D point. If there are more than one shape provided the closest point on any shape countour is returned. If there are more than one point provided one point is returned for each input point.

Shape.getCompactness(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `float`

  Gets a measure of how compact a shape is, as a number between 0.0 and 1.0. A circle has compactness 1.0. The measure is calculated as (4*pi*Area)/perimeter^2. Degenerate shapes has compactness zero.

Shape.getContourPoints(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `Point`

  Get the points defining the shape contour. Only supported for shapes consisting of a finite number of points (line segments, rectangles and polylines). To get a polygon approximation of a circle or ellipse, use toPolyline.

Shape.getConvexHull(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `Shape`

  Gets the convex hull of a given shape. Currently fails if the shape is something other than a polyline. Convert general shapes to polylines using Shape.toPolyline.

Shape.getConvexity(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `float`

  Returns a measure of how convex a given shape is, as a number between 0.0 and 1.0. It is given as a quotient between the area of the shape and its convex hull. A convex object has convexity 1.0. All open shapes such as lines, arcs and open polylines return 0.

Shape.getEllipseParameters(ellipse)
  Argument:

    - ellipse (`Shape`)

  Return type:

    `Point`

  Get the parameters defining the ellipse. Can only be called for ellipse shapes (returns nil otherwise). A vector of ellipse shapes can be provided, in which case vectors of parameters are returned.

Shape.getElongation(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `float`

  Get the a measure of elongation of a shape. It is calculated as lengthAlongMajorAxis/lengthAlongMinorAxis and is therefore a number between 1.0 (e.g., a circle) and infinity (e.g., a line). For some shapes, i.e, Polyline, Arc and Sector, the elongation of the shape bounding box is returned.

Shape.getIntersectionAngle(line1, line2)
  Arguments:

    - line1 (`Shape`)

    - line2 (`Shape`)

  Return type:

    `float`

  Get angle of the intersection between two lines or line segments. If the line segments do not intersect the lines are extrapolated to calculate the intersection angle.

Shape.getIntersectionPoints(shape1, shape2)
  Arguments:

    - shape1 (`Shape`)

    - shape2 (`Shape`)

  Return type:

    `Point`

  Get points on the intersection between two shape contours.

Shape.getLineDistance(shape, referenceLine)
  Arguments:

    - shape (`Shape`)

    - referenceLine (`Shape`)

  Return type:

    `float`

  Returns the minimum and maximum distance from all points on the shape to the reference line. Distances are measured orthogonal to the reference line. The query shape should have finite size.

Shape.getLineParameters(line)
  Argument:

    - line (`Shape`)

  Return type:

    `Point`

  Get the parameters defining the line or line segment. Can only be called for line or line segment shapes (returns nil otherwise). For line segments, the two endpoints are returned. For lines, the first point used to define the line is returned, the second point is one unit distance away from the first point along the line. A vector of line or line segment shapes can be provided, in which case two vectors of parameters are returned.

Shape.getPerimeterLength(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `float`

  Get the length of the perimeter of a shape.

Shape.getPolylineParameters(polyline)
  Argument:

    - polyline (`Shape`)

  Return type:

    `Point`

  Get the points defining the polyline and a flag indicating if the polyline is closed.

Shape.getRadius(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `float`

  Get the radius of the shape. This function is deprecated. Use specific functions for getting the parameters of each Shape instead, for example Shape.getCircleParameters, or the bounding box functions.

Shape.getRectangleParameters(rectangle)
  Argument:

    - rectangle (`Shape`)

  Return type:

    `Point`

  Get the parameters defining the rectangle. Can only be called for rectangle shapes (returns nil otherwise). A vector of rectangle shapes can be provided, in which case three vectors of parameters are returned.

Shape.getSectorParameters(sector)
  Argument:

    - sector (`Shape`)

  Return type:

    `Point`

  Get the parameters defining the sector. Can only be called for sector shapes (returns nil otherwise). A vector of sector shapes can be provided, in which case vectors of parameters are returned.

Shape.getType(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `enum`

  Return the geometric type the Shape represents.

Shape.isClosed(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `boolean`

  Check if this is a closed shape. A contour is closed if it has no endpoints and encloses an area. For example, a circle is closed while a line segment is not.

Shape.rotate(shape, rotationAngle, rotationCenter)
  Arguments:

    - shape (`Shape`)

    - rotationAngle (`float`)

    - rotationCenter (`Point`)

  Return type:

    `Shape`

  Rotate the shape. The rotation center is optional. If not provided, the nominal center of the shape is used. For most shapes, this is the same point as the center of gravity. For arcs and sectors, the nominal center is the center of the base circle. Note on rotation direction: When a shape is used for defining a region in an image, it is interpreted in the left handed coordinate system of the image. In a left-handed system, a positive rotation is in the clockwise direction.

Shape.toImage(shape, referenceImage, worldValue)
  Arguments:

    - shape (`Shape`)

    - referenceImage (`Image`)

    - worldValue (`float`)

  Return type:

    `Image`

  Convert the shape into an image, setting pixels within the shape contour to a specific value. The value is in world coordinates and is cropped to the representable range. Pixels outside are set to pixel value zero. Only closed shapes are supported. If several shapes are given, they are all drawn in the same image. Invalid shapes in a list of shapes are ignored.

Shape.toLine(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `Shape`

  Convert a line segment or a vector of line segments to infinite lines. Only supports line segment input.

Shape.toPixelRegion(shape, referenceImage, fill)
  Arguments:

    - shape (`Shape`)

    - referenceImage (`Image`)

    - fill (`boolean`)

  Return type:

    `Image.PixelRegion`

  Rasterize a Shape object into a PixelRegion object, using a reference image to define the pixel-world mapping. A vector of shape objects generates a vector of PixelRegion objects.

Shape.toPolyline(shape, epsilon, maxPoints)
  Arguments:

    - shape (`Shape`)

    - epsilon (`float`)

    - maxPoints (`int`)

  Return type:

    `Shape`

  Convert this shape to a polyline shape, approximating the true shape if needed (if the true shape is a circle, ellipse or arc). For a shape that is already a polyline, this function can be used to approximate it with a less detailed polyline.

Shape.toShape3D(shape, transform)
  Arguments:

    - shape (`Shape`)

    - transform (`Transform`)

  Return type:

    `Shape3D`

  Convert a 2D Shape into the corresponding 3D shape. An optional rigid Transform object may be provided. Without transform, the 3D shape is created in the z=0 plane. The transform is applied after creation, allowing 3D Shapes in other planes. Nil is returned if the input contains invalid shapes or shapes without a corresponding 3D shape.

Shape.toString(shape)
  Argument:

    - shape (`Shape`)

  Return type:

    `string`

  Get a human-readable string describing the shape.

Shape.transform(shape, transform)
  Arguments:

    - shape (`Shape`)

    - transform (`Transform`)

  Return type:

    `Shape`

  Transform a shape or a vector of shapes. Fails if the transform is not a 2D transform or if the transform would change the underlying shape type.

Shape.translate(shape, translationX, translationY)
  Arguments:

    - shape (`Shape`)

    - translationX (`float`)

    - translationY (`float`)

  Return type:

    `Shape`

  Translate the shape, i.e., shift it along the x,y-axes. Note on translation direction: When a shape is used for defining a region in an image, it is interpreted in the left handed coordinate system of the image in which the y-axis is pointing downwards. A positive translation therefore shifts the shape downwards when overlaid on top of the image.