# Transform - Geometry: Compose

The Compose template appears in the template list when a geometry field, of type geom, geommfd, or geomwkb, has been picked in the Transform pane.  It composes objects from coordinates.

Compose

Compose a geometry value from coordinate numbers and save to the specified Result destination:

• circle  -  Compose a circle from X and Y coordinate values and a Radius.
• point -  Compose a point from X and Y coordinate values.
• point with z -  Compose a point from X and Y coordinate values and add a Z value.
• rectangle  -  Compose a rectangle from X and Y coordinate values for two diagonally opposite corners.
• segment  -  Compose a straight line segment from X and Y coordinate values for the beginning and end coordinates.
• triangle -  Compose a triangle from X and Y coordinate values for each of the three vertices.

Launch the template by choosing a geometry field and then double-clicking the Compose template.  When the template launches we can specify options. Compose : circle

Most frequently used as a transform operation for tables, where the operation is clearer: For each record in the table, given an X value, a Y value and a Radius value, create a circular area object of specified radius centered on the specified X,Y location and save to the specified Result destination.

In the case of drawings, each record in the drawing's table specifies an object in the drawing.  When we utilize this transform operation from a drawing the intent is for each object in the drawing to create a circle, with the circle usually intended to be related to the location of the object for which it is generated.   For example, if a drawing has points we might want to create a circle of given radius at each point, and if a drawing has areas we might want to create a circle of given radius at the center of each area.

To do that instead of using simple numbers or fields for the X and Y values we will probably use expressions in the X and Y combo boxes that extract the X and Y coordinates of the centroid of each object.

Consider a starting drawing that has four point objects, located at coordinates as follows (just the diagonal corner coordinates being labeled): We can use the Compose : circle operation to create a circular area object centered upon the location of each point.

With the focus on the drawing, in the Transform pane, we choose the Geom field.   We double-click the Compose template to launch it. In the Compose template we choose circle as the Compose option.

In the X box, we choose Expression and enter the expression:

VectorValue(GeomCoordXY([Geom], 0),0)

In the Y box, we choose Expression and enter the expression:

VectorValue(GeomCoordXY([Geom], 0),1)

See the section below on SQL functions to learn what the above expressions do.

For Radius we enter 5.   The Radius box takes whatever are the native units used by the coordinate system used by the geometry field we are using.   Since our drawing uses Pseudo-Mercator projection, which uses meters, the unit of measure is meters.  We are asking for a radius of five meters for each circle.

For the Result destination, we choose New Field, and we enter Geom circles as the name of the new geometry field.  We enter Circles as the name of the New drawing that will visualize that new geometry field.   We can use whatever names we like for the new field and new drawing, but it is wise to use names that remind us of what they contain.

Press Transform.

A new drawing called Circles appears in the Project pane.   We can drag and drop it as a layer into the drawing window. The template automatically creates a new geom field called Geom circles and populates it with circular area objects that are centered on each point with each circle having a radius of five meters.   The Circles drawing visualizes that new geometry field.  We show the Circles drawing above styled using blue color, and using the Layers pane to set the opacity of the layer at 50%, so we can see the points in the layer below.

We are not required to use a fixed radius for all objects, of course.   We could choose a field to control the value of the Radius.

To choose a purely artificial example, suppose we chose the mfd_id field as the value to control the Radius.  In the sample drawing the four points were created in order in a new, blank drawing so their mfd_id values are 1, 2, 3 and 4, respectively.   Using mfd_id to control the Radius therefore says to use those numbers as values for Radius for the four circles that are created. We can re-run the transform with the same X and Y expressions, but this time from the pull down menu for the Radius parameter we choose the mfd_id field.

For the Result destination, we choose the existing Geom circles field that we created in the previous example.   This will automatically send the results of the operation into that existing field, updating the drawing as well.

Press Transform. The Circles drawing immediately updates to show how the circles now have radii ranging from one to four meters, based on the value of the mfd_id field for their respective points.

How might we use this operation in real life?

Suppose we have a drawing that shows the locations of radio station antennas as points, and for each point we also have an attribute field that gives the transmission power for that station.  Creating a circle at each point using the transmission power to provide the radius will create a drawing of circles that will be larger for higher power stations and smaller for lower power stations.

The operation might also be used for classic military purposes such as targeting.   Each point could be the target coordinates for a particular warhead and the radius might be taken from a field that gave the effective range of destruction for that warhead.

### SQL Functions Used in X and Y Boxes

The expression used to get the X,Y value for the first coordinate of a geom is:

GeomCoordXY([Geom], 0)

The GeomCoordXY function returns the (X,Y) value for the specified coordinate of a geom.  We ask for the 0 coordinate, that is, the first coordinate that defines the object.   In this case because we are working points there is only one coordinate in the geom that defines each point object, but had we been working with lines where many coordinates might define the line asking for coordinate number 0 of the geom would return the (X,Y) value of the first coordinate, that is, the beginning of the line.

Once we have the X,Y value of a coordinate, we can get either the X or the Y part by using the VectorValue function.

In the X box we want only a single number, the X part of the (X,Y) coordinate vector returned by GeomCoordXY so we will use the VectorValue function to get only that part.

The VectorValue( ) function takes two arguments: the first is a vector and the second argument, a number such as 0, 1, 2, 3... asks for that specified value in the vector.   In the case of a vector that has only two numbers in it such as an (X,Y) vector using a second argument of 0 asks for the first number, the X value, and using a second argument of 1 asks for the Y value.  If the vector we were working with was an (X,Y,Z) vector with three values in it then using a second argument of 2 would get the Z value.

The expression...

VectorValue(GeomCoordXY([Geom], 0), 0)

... means get the (X,Y) vector value of the first coordinate in the object in Geom, and then use VectorValue to extract from that the X value.     We use that expression in the X combo box and it will be automatically computed for each object in the drawing to produce the X value to be used for creating the circle for that object.

The expression...

VectorValue(GeomCoordXY([Geom], 0),1)

... means get the (X,Y) vector value of the first coordinate in the object in Geom, and then use VectorValue to extract from that the Y value.  We use that expression in the Y combo box and it will be automatically computed for each object in the drawing to produce the Y value to be used for creating the circle for that object.

Compose : point

Most frequently used as a transform operation for tables, where the operation is clearer: For each record in the table, given an X value and a Y value, create a point object at the specified X,Y location and save to the specified Result destination.

In the case of drawings, each record in the drawing's table specifies an object in the drawing.  When we utilize this transform operation from a drawing the intent is for each object in the drawing to create a point, with the point usually intended to be placed at some meaningful spot related to the location of the object from which it was created.  For example, we might want to create a point at the first coordinate of each object in the case of a drawing that contains lines.

Consider a starting drawing that has two point objects, two lines and three areas: Following a procedure similar to the Compose : circle example above, we will first generate a single point located at the position of the first coordinate that defines each object, and then we will generate a single point located at the position of the second coordinate that defines each object.

With the focus on the drawing, in the Transform pane, we choose the Geom field.   We double-click the Compose template to launch it. In the Compose template we choose point as the Compose option.

In the X box, we choose Expression and enter the expression:

VectorValue(GeomCoordXY([Geom], 0),0)

In the Y box, we choose Expression and enter the expression:

VectorValue(GeomCoordXY([Geom], 0),1)

See the section on SQL functions in the Compose : circle discussion to learn what the above expressions do.

For the Result destination, we choose New Field, and we enter Geom points as the name of the new geometry field.  We enter Points from objects as the name of the New drawing that will visualize that new geometry field.   We can use whatever names we like for the new field and new drawing, but it is wise to use names that remind us of what they contain.

Press Transform.

A new drawing called Points from objects appears in the Project pane.   We can drag and drop it as a layer into the drawing window. For a more understandable display, we can style the points using bright green color, and we can use the Layers pane to reduce the opacity of the Objects Drawing background layer to 20%: The transform created points at the first coordinate that defines each object in Objects Drawing.   Seven points have been created in the Points from objects drawing, one for each of the seven original objects.

We can adjust the expressions used to get X and Y values for the second coordinate of each object: We re-run the transform with slightly different X and Y expressions.

For the X expression we use:

VectorValue(GeomCoordXY([Geom], 1), 0)

For the Y expression we use:

VectorValue(GeomCoordXY([Geom], 1), 1)

In this case the 1 argument in ([Geom], 1) picks out the second coordinate defining the object, counting from zero.

For the Result destination, we choose the existing Geom points field that we created in the previous example.   This will automatically send the results of the operation into that existing field, updating the drawing as well.

Press Transform. The Points from objects drawing immediately updates to show the points created by the transform.

Note that there are two fewer points in the Points from objects drawing.   No points have been created for the two point objects in the original drawing. Turning off the Objects Drawing layer, we can easily see there are only five points in the Points from objects drawing.

The original drawing had two point objects, but point objects have only one coordinate location that defines them.   Our expressions get the X and Y values of the second coordinates for each object, which the two original points do not have.  The result of the Compose : point operation will be a NULL for each point object in the original drawing.

Compose : point with z

Exactly the same as Compose : point with the addition that we can specify a Z value for the point.  We might take that from a field for each object that specifies a height or some other attribute of interest.

Compose : rectangle

Similar to Compose : circle but instead creates rectangles.   For each record in the table, creates a rectangular area object that is vertically aligned using the specified coordinates for the X 0, Y 0 corner and diagonally opposite X 1, Y 1 corner.

Consider a starting drawing that has four point objects, located at coordinates as follows (just the diagonal corner coordinates being labeled): We can use the Compose : rectangle operation to replace each point object with a rectangular area object centered upon the location of the point.   We will use expressions that extract the X and the Y locations of each point and then add to them or subtract from them to create the desired offset locations of the lower left corner and the upper right corner of the rectangles to be created.

In the pull down menus for the parameter boxes, we choose Expression so we can enter expressions using SQL functions.  See the Compose : circle discussion for an explanation of the functions used.

With the focus on the drawing, in the Transform pane, we choose the Geom field.   We double-click the Compose template to launch it. In the Compose template we choose rectangle as the Compose option.

In the X 0 and Y 0 boxes, we choose Expression and enter the expressions:

VectorValue(GeomCoordXY([Geom], 0), 0) - 4

and

VectorValue(GeomCoordXY([Geom], 0), 1) - 2

In the X 1 and Y 1 boxes, we choose Expression and enter the expressions:

VectorValue(GeomCoordXY([Geom], 0), 0) + 4

and

VectorValue(GeomCoordXY([Geom], 0), 1) + 2

The X 0 and Y 0 expressions place the lower left corner of the new rectangle four units to the left and two units below the location of the point.  We take advantage of Manifold's ability to handle mathematics within expressions that are placed inside combo boxes.

The X 1 and Y 1 expressions place the upper right corner of the new rectangle four units to the right and two units above the location of the point.   The net effect is to create a rectangle that is eight units wide and four units high that is centered on the location of the point for which it is generated.

For the Result destination, we choose New Field, and we enter Geom rectangles as the name of the new geometry field.  We enter Rectangles as the name of the New drawing that will visualize that new geometry field.   We can use whatever names we like for the new field and new drawing, but it is wise to use names that remind us of what they contain.

Press Transform.

A new drawing called Rectangles appears in the Project pane.   We can drag and drop it as a layer into the drawing window. The template automatically creates a new geom field called Geom rectangles and populates it with rectangular area objects that are centered on each point, using the various X and Y locations computed by the expressions.  The Rectangles drawing visualizes that new geometry field.  We show the Rectangles drawing above styled using blue color, and using the Layers pane to set the opacity of the layer at 50%, so we can see the points in the layer below.

Compose : segment

Pending Update  Similar to Compose : rectangle but instead of creating a rectangular area object, for each record in the table the Compose : segment operation creates a straight line segment between the specified  coordinates for the X 0, Y 0 beginning and X 1, Y 1 end of the line.

Consider a starting drawing that has four point objects, located at coordinates as follows (just the diagonal corner coordinates being labeled): We can use the Compose : segment operation to create a straight line segment for each point object that is centered upon the location of the point.   We will use expressions that extract the X and the Y locations of each point and then add to them or subtract from them to create the desired offset locations of the lower left corner and the upper right corner of the line segments to be created.

In the pull down menus for the parameter boxes, we choose Expression so we can enter expressions using SQL functions.  See the Compose : circle discussion for an explanation of the functions used.

With the focus on the drawing, in the Transform pane, we choose the Geom field.   We double-click the Compose template to launch it. In the Compose template we choose segment as the Compose option.

In the X 0 and Y 0 boxes, we choose Expression and enter the expressions:

VectorValue(GeomCoordXY([Geom], 0), 0) - 4

and

VectorValue(GeomCoordXY([Geom], 0), 1) - 2

In the X 1 and Y 1 boxes, we choose Expression and enter the expressions:

VectorValue(GeomCoordXY([Geom], 0), 0) + 4

and

VectorValue(GeomCoordXY([Geom], 0), 1) + 2

The X 0 and Y 0 expressions place the lower left coordinate of the new segment four units to the left and two units below the location of the point.

The X 1 and Y 1 expressions place the upper right coordinate of the new segment four units to the right and two units above the location of the point.   The net effect is to create a line consisting of one segment that slants from lower left to upper right, a total of eight units wide and four units high, and centered on the location of the point for which it is generated.

For the Result destination, we choose New Field, and we enter Geom segments as the name of the new geometry field.  We enter Segments as the name of the New drawing that will visualize that new geometry field.  We can use whatever names we like for the new field and new drawing, but it is wise to use names that remind us of what they contain.

Press Transform.

A new drawing called Segments appears in the Project pane.   We can drag and drop it as a layer into the drawing window. The template automatically creates a new geom field called Geom segments and populates it with line objects consisting of a single straight line segment that are centered on each point, using the various X and Y locations computed by the expressions.  The Segments drawing visualizes that new geometry field.  We show the Segments drawing above styled using blue color, and using the Layers pane to set the opacity of the layer at 50%, so we can see the points in the layer below.

Using suitable expressions, we can use this transform to create lines that are oriented to various bearings, perhaps taking their direction from attribute fields for each point.  Using a style that places an arrow head at the end of each line we can create maps of wind directions and other flow fields.

Compose : triangle

Similar to Compose : rectangle but instead of creating a rectangular area object the Compose : triangle operation for each record in the table creates a triangular area object using as corners of the triangle the specified  coordinates for the  X 0, Y 0 corner,  X 1, Y 1 corner and X 2, Y 2 corner,

Consider a starting drawing that has four point objects, located at coordinates as follows (just the diagonal corner coordinates being labeled): We can use the Compose : triangle operation to replace each point object with a triangular area with one corner placed at the location of the point.   We will use expressions that extract the X and the Y locations of each point and then add to them or subtract from them to create the desired offset locations of the corners of the triangles to be created.

In the pull down menus for the parameter boxes, we choose Expression so we can enter expressions using SQL functions.  See the Compose : circle discussion for an explanation of the functions used.

With the focus on the drawing, in the Transform pane, we choose the Geom field.   We double-click the Compose template to launch it. In the Compose template we choose triangle as the Compose option.

In the X 0 and Y 0 boxes, we choose Expression and enter the expressions:

VectorValue(GeomCoordXY([Geom], 0), 0)

and

VectorValue(GeomCoordXY([Geom], 0), 1)

These expressions place the first corner of the triangle at the location of the original point.

In the X 1 and Y 1 boxes, we choose Expression and enter the expressions:

VectorValue(GeomCoordXY([Geom], 0), 0) + 4

and

VectorValue(GeomCoordXY([Geom], 0), 1) + 2

These expressions place the second corner of the triangle four units to the right and two units above the location of the point.

In the X 2 and Y 2 boxes, we choose Expression and enter the expressions:

VectorValue(GeomCoordXY([Geom], 0), 0) + 4

and

VectorValue(GeomCoordXY([Geom], 0), 1) - 4

These expressions place the final corner of the triangle four units to the right and four units below the location of the point.

The net effect of the expressions is to create a triangle with one corner at the location of the for which it is generated, and the rest of the triangle to the right of that location.

For the Result destination, we choose New Field, and we enter Geom triangles as the name of the new geometry field.  We enter Triangles as the name of the New drawing that will visualize that new geometry field.  We can use whatever names we like for the new field and new drawing, but it is wise to use names that remind us of what they contain.

Press Transform.

A new drawing called Triangles appears in the Project pane.   We can drag and drop it as a layer into the drawing window. The template automatically creates a new geom field called Geom triangles and populates it with triangular area objects.  The Triangles drawing visualizes that new geometry field.

We can style the new drawing and apply some transparency: We show the Triangles drawing above styled using blue color, and using the Layers pane to set the opacity of the layer at 50%, so we can see how the first vertex of the triangle falls exactly on the center of each point icon.

## Notes

Curvilinear segments - As a practical matter, most people doing GIS will use straight line segments for lines and areas.   Few GIS systems do a good job of supporting curved segments, so there is much less data published using curved segments.   Manifold's ability to work with curved segments allows us to use that data within Manifold in a limited way, at least for display and interactive editing.

However, most processing tools in Manifold, such as Transform templates and various Geom SQL functions, do their work by first converting a curvilinear segment into a straight line segment between the same two start and finish coordinates.  That will often lead to weird or otherwise unexpected results.  To avoid such problems, first convert curvilinear segments into equivalent constellations of straight line segments at whatever resolution is desired, using the transform template with the convert curves to lines operation option and the number of linear segments desired to approximate the curve in the Curve limit parameter.   See the Curved Segments discussion in the Drawings topic.

Transform Pane

Transform Reference

Transform - Expression

Transform - Geometry