Geometry Overview

This overview describes how to use the Windows Presentation Foundation (WPF) Geometry classes to describe shapes. This topic also contrasts the differences between Geometry objects and Shape elements.

This topic contains the following sections.

• What is a Geometry?
• Geometries vs. Shapes
• Common Properties that Take a Geometry
• Simple Geometry Types
• Path Geometries
• Composite Geometries
• Combined Geometries
• Freezable Features
• Other Geometry Features
• Related Topics

What is a Geometry?

The Geometry class and the classes which derive from it, such as EllipseGeometry, PathGeometry, and CombinedGeometry, enable you to describe the geometry of a 2-D shape. These geometric descriptions have many uses, such defining a shape to paint to the screen or defining hit-test and clip regions. You can even use a geometry to define an animation path.

Geometry objects can be simple, such as rectangles and circles, or composite, created from two or more geometry objects. More complex geometries can be created by using the PathGeometry and StreamGeometry classes, which enable you to describe arcs and curves.

Because a Geometry is a type of Freezable, Geometry objects provide several special features: they can be declared as Resources Overview, shared among multiple objects, made read-only to improve performance, cloned, and made thread-safe. For more information about the different features provided by Freezable objects, see the Freezable Objects Overview.

Geometries vs. Shapes

The Geometry and Shape classes seem similar in that they both describe 2-D shapes (compare EllipseGeometry and Ellipse for example), but there are important differences.

For one, the Geometry class inherits from the Freezable class while the Shape class inherits from FrameworkElement. Because they are elements, Shape objects can render themselves and participate in the layout system, while Geometry objects cannot.

Although Shape objects are more readily usable than Geometry objects, Geometry objects are more versatile. While a Shape object is used to render 2-D graphics, a Geometry object can be used to define the geometric region for 2-D graphics, define a region for clipping, or define a region for hit testing, for example.

The Path Shape

One Shape, the Path class, actually uses a Geometry to describe its contents. By setting the Data property of the Path with a Geometry and setting its Fill and Stroke properties, you can render a Geometry.

Common Properties that Take a Geometry

The preceding sections mentioned that Geometry objects can be used with other objects for a variety of purposes, such as drawing shapes, animating, and clipping. The following table lists several class that have properties that take a Geometry object.

Simple Geometry Types

The base class for all geometries is the abstract class Geometry. The classes which derive from the Geometry class can be roughly grouped into three categories: simple geometries, path geometries, and composite geometries.

Simple geometry classes include LineGeometry, RectangleGeometry, and EllipseGeometry and are used to create basic geometric shapes, such as lines, rectangles, and circles.

• A LineGeometry is defined by specifying the start point of the line and the end point.

• A RectangleGeometry is defined with a Rect structure which specifies its relative position and its height and width. You can create a rounded rectangle by setting the RadiusX and RadiusYproperties.

• An EllipseGeometry is defined by a center point, an x-radius and a y-radius. The following examples show how to create simple geometries for rendering and for clipping.

These same shapes, as well as more complex shapes, can be created using a PathGeometry or by combining geometry objects together, but these classes provide a simpler means for producing these basic geometric shapes.

The following example shows how to create and render a LineGeometry. As noted previously, a Geometry object is unable to draw itself, so the example uses a Path shape to render the line. Because a line has no area, setting the Fill property of the Path would have no effect; instead, only the Stroke and StrokeThickness properties are specified. The following illustration shows the output from the example.

A LineGeometry drawn from (10,20) to (100,130)

<Path Stroke="Black" StrokeThickness="1" >
  <Path.Data>
    <LineGeometry StartPoint="10,20" EndPoint="100,130" />
  </Path.Data>
</Path>

LineGeometry myLineGeometry = new LineGeometry();
myLineGeometry.StartPoint = new Point(10,20);
myLineGeometry.EndPoint = new Point(100,130);

Path myPath = new Path();
myPath.Stroke = Brushes.Black;
myPath.StrokeThickness = 1;
myPath.Data = myLineGeometry;

The next example shows how to create and render an EllipseGeometry. The examples sets the Center of the EllipseGeometry is set to the point 50,50 and the x-radius and the y-radius are both set to 50, which creates a circle with a diameter of 100. The interior of the ellipse is painted by assigning a value to the Path element's Fill property, in this case Gold. The following illustration shows the output from the example.

An EllipseGeometry drawn at (50,50)

<Path Fill="Gold" Stroke="Black" StrokeThickness="1">
  <Path.Data>
    <EllipseGeometry Center="50,50" RadiusX="50" RadiusY="50" />
  </Path.Data>
</Path>

EllipseGeometry myEllipseGeometry = new EllipseGeometry();
myEllipseGeometry.Center = new Point(50, 50);
myEllipseGeometry.RadiusX = 50;
myEllipseGeometry.RadiusY = 50;

Path myPath = new Path();
myPath.Fill = Brushes.Gold;
myPath.Stroke = Brushes.Black;
myPath.StrokeThickness = 1;
myPath.Data = myEllipseGeometry;

The following example shows how to create and render a RectangleGeometry. The position and the dimensions of the rectangle are defined by a Rect structure. The position is 50,50 and the height and width are both 25, which creates a square. The following illustration shows the output from the example.

A RectangleGeometry drawn at 50,50

<Path Fill="LemonChiffon" Stroke="Black" StrokeThickness="1">
  <Path.Data>
    <RectangleGeometry Rect="50,50,25,25" />
  </Path.Data>
</Path>

RectangleGeometry myRectangleGeometry = new RectangleGeometry();    
myRectangleGeometry.Rect = new Rect(50,50,25,25);

Path myPath = new Path();
myPath.Fill = Brushes.LemonChiffon;
myPath.Stroke = Brushes.Black;
myPath.StrokeThickness = 1;
myPath.Data = myRectangleGeometry;

The following example shows how to use an EllipseGeometry as the clip region for an image. An Image object is defined with a Width of 200 and a Height of 150. An EllipseGeometry with a RadiusX value of 100, a RadiusY value of 75, and a Center value of 100,75 is set to the Clip property of the image. Only the part of the image that is within the area of the ellipse will be displayed. The following illustration shows the output from the example.

An EllipseGeometry used to clip an Image control

<Image
  Source="sampleImages\Waterlilies.jpg"
  Width="200" Height="150" HorizontalAlignment="Left">
  <Image.Clip>
    <EllipseGeometry
      RadiusX="100"
      RadiusY="75"
      Center="100,75"/>
  </Image.Clip>
</Image>

// Create the image to clip.
Image myImage = new Image();
Uri imageUri = 
    new Uri(@"C:\\Documents and Settings\\All Users\\Documents\My Pictures\\Sample Pictures\\Water lilies.jpg", UriKind.Relative);
myImage.Source = new BitmapImage(imageUri);
myImage.Width = 200;
myImage.Height = 150;
myImage.HorizontalAlignment = HorizontalAlignment.Left;    

// Use an EllipseGeometry to define the clip region. 
EllipseGeometry myEllipseGeometry = new EllipseGeometry();
myEllipseGeometry.Center = new Point(100, 75);
myEllipseGeometry.RadiusX = 100;
myEllipseGeometry.RadiusY = 75;
myImage.Clip = myEllipseGeometry;

Path Geometries

The PathGeometry class and its light-weight equivalent, the StreamGeometry class, provide the means to describe multiple complex figures composed of arcs, curves, and lines.

At the heart of a PathGeometry is a collection of PathFigure objects, so named because each figure describes a discrete shape in the PathGeometry. Each PathFigure is itself comprised of one or more PathSegment objects, each of which describes a segment of the figure.

There are many types of segments.

The segments within a PathFigure are combined into a single geometric shape with the end point of each segment being the start point of the next segment. The StartPoint property of a PathFigure specifies the point from which the first segment is drawn. Each subsequent segment starts at the end point of the previous segment. For example, a vertical line from 10,50 to 10,150 can be defined by setting the StartPoint property to 10,50 and creating a LineSegment with a Point property setting of 10,150.

The following example creates a simple PathGeometry comprised of a single PathFigure with a LineSegment and displays it using a Path element. The PathFigure object's StartPoint is set to 10,20 and a LineSegment is defined with an end point of 100,130. The following illustration shows the PathGeometry created by this example.

A PathGeometry that contains a single LineSegment

<Path Stroke="Black" StrokeThickness="1">
  <Path.Data>
    <PathGeometry>
      <PathGeometry.Figures>
        <PathFigure StartPoint="10,20">
          <PathFigure.Segments>
            <LineSegment Point="100,130"/>
          </PathFigure.Segments>
        </PathFigure>
      </PathGeometry.Figures>
    </PathGeometry>
  </Path.Data>
</Path>

// Create a figure that describes a 
// line from (10,20) to (100,130).
PathFigure myPathFigure = new PathFigure();
myPathFigure.StartPoint = new Point(10,20);
myPathFigure.Segments.Add(
    new LineSegment(new Point(100,130),
    true /* IsStroked */ ));

/// Create a PathGeometry to contain the figure.
PathGeometry myPathGeometry = new PathGeometry();
myPathGeometry.Figures.Add(myPathFigure);

// Display the PathGeometry. 
Path myPath = new Path();
myPath.Stroke = Brushes.Black;
myPath.StrokeThickness = 1;
myPath.Data = myPathGeometry;

It is worth contrasting this example with the preceding LineGeometry example. The syntax used for a PathGeometry is much more verbose than that used for a simple LineGeometry, and it may make more sense to use the LineGeometry class in this case, but the verbose syntax of the PathGeometry allows for extremely intricate and complex geometric regions.

More complex geometries can be created by using a combination of PathSegment objects.

The next example uses a BezierSegment, a LineSegment, and an ArcSegment to create shape. The example first creates a cubic Bezier curve is by defining four points: a start point, which is the end point of the previous segment, an end point (Point3), and two control points (Point1 and Point2). The two control points of a cubic Bezier curve behave like magnets, attracting portions of what would otherwise be a straight line towards themselves, producing a curve. The first control point, Point1, affects the beginning portion of the curve; the second control point, Point2, affects the ending portion of the curve.

The example then adds a LineSegment, which is drawn between the end point of the preceding BezierSegment that preceded it to the point specified by its LineSegment property.

The example then adds an ArcSegment, which is drawn from the end point of the preceding LineSegment to the point specified by its Point property. The example also specifies the arc's x- and y-radius (Size), a rotation angle (RotationAngle), a flag indicating how large the angle of the resulting arc should be (IsLargeArc), and a value indicating in which direction the arc is drawn (SweepDirection). The following illustration shows the shape created by this example.

A PathGeometry

<Path Stroke="Black" StrokeThickness="1" >
  <Path.Data>
    <PathGeometry>
      <PathGeometry.Figures>
        <PathFigure StartPoint="10,50">
          <PathFigure.Segments>
            <BezierSegment
              Point1="100,0"
              Point2="200,200"
              Point3="300,100"/>
            <LineSegment Point="400,100" />
            <ArcSegment
              Size="50,50" RotationAngle="45"
              IsLargeArc="True" SweepDirection="Clockwise"
              Point="200,100"/>
          </PathFigure.Segments>
        </PathFigure>
      </PathGeometry.Figures>
    </PathGeometry>
  </Path.Data>
</Path>

// Create a figure.
PathFigure myPathFigure = new PathFigure();
myPathFigure.StartPoint = new Point(10,50);
myPathFigure.Segments.Add(
    new BezierSegment(
        new Point(100,0),
        new Point(200,200),
        new Point(300,100),
        true /* IsStroked */  )); 
myPathFigure.Segments.Add(
    new LineSegment(
        new Point(400,100),
        true /* IsStroked */ ));
myPathFigure.Segments.Add(
    new ArcSegment(
        new Point(200,100),
        new Size(50,50),
        45,
        true, /* IsLargeArc */ 
        SweepDirection.Clockwise, 
        true /* IsStroked */ ));                       

/// Create a PathGeometry to contain the figure.
PathGeometry myPathGeometry = new PathGeometry();
myPathGeometry.Figures.Add(myPathFigure);

// Display the PathGeometry. 
Path myPath = new Path();
myPath.Stroke = Brushes.Black;
myPath.StrokeThickness = 1;
myPath.Data = myPathGeometry;

Even more complex geometries can be created by using multiple PathFigure objects within a PathGeometry.

The following example creates a PathGeometry with two PathFigure objects, each of which contains multiple PathSegment objects. The PathFigure from the above example and a PathFigure with a PolyLineSegment and a QuadraticBezierSegment are used. A PolyLineSegment is defined with an array of points and the QuadraticBezierSegment is defined with a control point and an end point. The following illustration shows the shape created by this example.

A PathGeometry with multiple figures

<Path Stroke="Black" StrokeThickness="1" >
  <Path.Data>
    <PathGeometry>
      <PathGeometry.Figures>
        <PathFigure StartPoint="10,50">
          <PathFigure.Segments>
            <BezierSegment
              Point1="100,0"
              Point2="200,200"
              Point3="300,100"/>
            <LineSegment Point="400,100" />
            <ArcSegment
              Size="50,50" RotationAngle="45"
              IsLargeArc="True" SweepDirection="Clockwise"
              Point="200,100"/>
          </PathFigure.Segments>
        </PathFigure>
        
        <PathFigure StartPoint="10,100">
          <PathFigure.Segments>
            <PolyLineSegment Points="50,100 50,150" />
            <QuadraticBezierSegment Point1="200,200" Point2="300,100"/>
          </PathFigure.Segments>
        </PathFigure>                
      </PathGeometry.Figures>
    </PathGeometry>
  </Path.Data>
</Path>

PathGeometry myPathGeometry = new PathGeometry();            

// Create a figure.
PathFigure pathFigure1 = new PathFigure();
pathFigure1.StartPoint = new Point(10,50);
pathFigure1.Segments.Add(
    new BezierSegment(
        new Point(100,0),
        new Point(200,200),
        new Point(300,100),
        true /* IsStroked */ )); 
pathFigure1.Segments.Add(
    new LineSegment(
        new Point(400,100),
        true /* IsStroked */ ));
pathFigure1.Segments.Add(
    new ArcSegment(
        new Point(200,100),
        new Size(50,50),
        45,
        true, /* IsLargeArc */
        SweepDirection.Clockwise, 
        true /* IsStroked */ ));
myPathGeometry.Figures.Add(pathFigure1);    

// Create another figure.
PathFigure pathFigure2 = new PathFigure();
pathFigure2.StartPoint = new Point(10,100);
Point[] polyLinePointArray = 
    new Point[]{ new Point(50, 100), new Point(50, 150)};
PolyLineSegment myPolyLineSegment = new PolyLineSegment();
myPolyLineSegment.Points = 
    new PointCollection(polyLinePointArray);
pathFigure2.Segments.Add(myPolyLineSegment);
pathFigure2.Segments.Add(
    new QuadraticBezierSegment(
        new Point(200,200),
        new Point(300,100),
        true /* IsStroked */ ));
myPathGeometry.Figures.Add(pathFigure2);

// Display the PathGeometry. 
Path myPath = new Path();
myPath.Stroke = Brushes.Black;
myPath.StrokeThickness = 1;
myPath.Data = myPathGeometry;

StreamGeometry

Like the PathGeometry class, a StreamGeometry defines a complex geometric shape that may contain curves, arcs, and lines. Unlike a PathGeometry, the contents of a StreamGeometry do not support data binding, animation, or modification. Use a StreamGeometry when you need to describe a complex geometry but do not want the overhead of supporting data binding, animation, or modification. Because of its efficiency, the StreamGeometry class is a good choice for describing adorners.

For an example, see How to: Create a Shape Using a StreamGeometry.

Path Markup Syntax

The PathGeometry and StreamGeometry types support a Extensible Application Markup Language (XAML) attribute syntax using a special series of move and draw commands. For more information, see Path Markup Syntax.

Composite Geometries

Composite geometry objects can be created using a GeometryGroup, a CombinedGeometry, or by calling the static Geometry method Combine.

• The CombinedGeometry object and the Combine method performs a Boolean operation to combine the area defined by two geometries. Geometry objects that have no area are discarded. Only two Geometry objects can be combined (although these two geometries may also be composite geometries).

• The GeometryGroup class creates an amalgamation of the Geometry objects it contains without combining their area. Any number of Geometry objects can be added to a GeometryGroup. For an example, see How to: Create a Composite Shape.

Because they do not perform a combine operation, using GeometryGroup objects provides performance benefits over using CombinedGeometry objects or the Combine method.

Combined Geometries

The preceding section mentioned the CombinedGeometry object and the Combine method combine the area defined by the geometries they contain. The GeometryCombineMode enumeration specifies how the geometries are combined. The possible values for the GeometryCombineMode property are: Union, Intersect, Exclude, and Xor.

In the following example, a CombinedGeometry is defined with a combine mode of Union. Both Geometry1 and the Geometry2 are defined as circles of the same radius, but with centers offset by 50.

<Path Stroke="Black" StrokeThickness="1" Fill="#CCCCFF">
  <Path.Data>
    
    <!-- Combines two geometries using the union combine mode. -->
    <CombinedGeometry GeometryCombineMode="Union">
      <CombinedGeometry.Geometry1>
        <EllipseGeometry RadiusX="50" RadiusY="50" Center="75,75" />
      </CombinedGeometry.Geometry1>
      <CombinedGeometry.Geometry2>
        <EllipseGeometry RadiusX="50" RadiusY="50" Center="125,75" />
      </CombinedGeometry.Geometry2>
    </CombinedGeometry>
  </Path.Data>
</Path>

In the following example, a CombinedGeometry is defined with a combine mode of Xor. Both Geometry1 and the Geometry2 are defined as circles of the same radius, but with centers offset by 50.

<Path Stroke="Black" StrokeThickness="1" Fill="#CCCCFF">
  <Path.Data>
    
    <!-- Combines two geometries using the XOR combine mode. -->
    <CombinedGeometry GeometryCombineMode="Xor">
      <CombinedGeometry.Geometry1>
        <EllipseGeometry RadiusX="50" RadiusY="50" Center="75,75" />
      </CombinedGeometry.Geometry1>
      <CombinedGeometry.Geometry2>
        <EllipseGeometry RadiusX="50" RadiusY="50" Center="125,75" />
      </CombinedGeometry.Geometry2>
    </CombinedGeometry>
  </Path.Data>
</Path>

For additional examples, see How to: Create a Composite Shape and How to: Create a Combined Geometry.

Freezable Features

Because it inherits from the Freezable class, the Geometry class provide several special features: Geometry objects can be declared as Resources Overview, shared among multiple objects, made read-only to improve performance, cloned, and made thread-safe. For more information about the different features provided by Freezable objects, see the Freezable Objects Overview.

Other Geometry Features

The Geometry class also provides useful utility methods, such as the following:

• GetArea - Gets the area of the Geometry.

• FillContains - Determines whether the Geometry contains another Geometry.

• StrokeContains - Determines whether the stroke of a Geometry contains a specified point.

See the Geometry class for a complete listing of its methods.

See Also

Reference

Geometry
PathGeometry
Path
GeometryDrawing

Concepts

Path Markup Syntax
Animation Overview
Shapes and Basic Drawing in WPF Overview
Drawing Objects Overview

Other Resources

Geometries How-to Topics
Geometries Samples