In this example we use the Expression tab of the Transform dialog to clip areas in a drawing to fit within horizontal bounds. In addition we use the Add Component button to save the results as a new drawing without changing the original drawing. We create a query in the Command Window that performs the action of the expression by using the Edit Query button.
We begin with a drawing of provinces in Mexico. The drawing geometry is stored in a geom field in a table called Mexico Table.
We double-click on the Mexico drawing in the Project pane to open the drawing. Our intention is to "cookie-cut" the area objects seen in the drawing so that any part of any area above latitude 30 is cut off and any part of any area below latitude 20 is cut off.
We choose Edit - Transform to open the Transform dialog.
We click on the Expression tab in the dialog.
Next, we enter the following expression:
GeomClip([Geom],
GeomMakeRect(VectorMakeX4(-120, 20, 0, 30)),
true, 0)
We can write that expression free-hand or assemble it by double-clicking on template parts in the lists of templates and fields that the dialog provides. Note that how we format the expression, using indents or putting part of the expression on new lines is up to us as white space does not matter in expressions.
To learn more about the numbers used or how the expression works, see the notes at the end of this topic for additional discussion and illustrations.
As soon as we begin writing the expression and we get far enough along so the result can be interpreted as a valid expression the results of the expression will be immediately previewed in blue preview color in the drawing window.
The preview shows what would be the result in the drawing if the expression were put into effect.
We can change the values in the Expression pane, for example, to latitude bounds of 18 and 22, and the preview in the drawing window immediately will be updated.
The new values that are latitude bounds which are closer together will clip even more of the area objects.
Let us restore the original latitude values used, of 20 and 30.
The preview again shows what would be the results.
So far all we have is a preview computed on the fly for display purposes. The data in the table has not been changed and will not be changed until we press the Update Field button.
Instead of changing the data in the table we can save the results into a new component by changing the Update Field choice to Add Component.
We then press Add Component.
That creates a new table in the Project pane called Mexico Table Geom along with a new drawing that visualizes that table. We double-click on the new drawing to open it.
The new drawing contains the results of applying the expression to the Mexico drawing's data, but saved into a new drawing without changing the original data.
Another way to capture the work of the expression without changing the original data is to save it as a query.
To do that, we press the Edit Query button. Note that the current status of the action button to the left of the Edit Query button is to Add Component. Therefore, the query we now ask Manifold to create will be a query that does not alter the original data but which creates a new table with the modified data along with a drawing to visualize that data. The result is a significantly larger query than a query which would simply update the existing table.
Doing so opens a Command Window that is populated with an automatically generated SQL query that is the equivalent of the expression we wrote in the Transform dialog. We can now modify the query or save it for later use.
The query is large because it must create and specify all of the infrastructure, such as the coordinate system to use, required for a new table and a new drawing based on the new table. The query would be much simpler if it was written to update the existing table, that is, to change the original data.
Suppose the action button was set to Update Field instead of to Add Component. In that case, when we press the Edit Query button the resulting query would be written to operate on the existing table.
Instead of creating a new table and a new drawing the query is a simple UPDATE query as seen above.
How does the expression work? We can take it step by step to see. We will begin by opening the Mexico drawing and zooming out slightly.
The expression we wrote in the example above was:
GeomClip([Geom],
GeomMakeRect(VectorMakeX4(-120, 20, -80, 30)),
true, 0)
In this case, the GeoMakeRect function on the fly creates a rectangle from the VectorMakeX4 function result which takes one corner as the longitude, latitude (x, y) coordinate values of -120, 20 and the diagonally opposite corner with longitude, latitude (x, y) coordinate values of -80, 30. That rectangle is then used by GeomClip to clip the area objects in to only those portions which fall within the clipping rectangle. The result is to clip off any parts of any areas that extend above 30 degrees latitude or below 20 degrees latitude.
We can see how it works by choosing Edit - Transform to open the Transform dialog, clicking on the Expression tab and then entering only the GeoMakeRect function portion of the full expression:
GeomMakeRect(VectorMakeX4(-120, 20, -80, 30))
That expression will be immediately previewed in the drawing window, displaying the rectangle that is created by the GeoMakeRect function.
The result of the expression is a rectangular area specified by the four arguments to VectorMakeX4 which specify one corner as the longitude, latitude coordinates of -120, 20 and the diagonally opposite corner at -80, 30. Note that only one area object is created by the expression since there is no reference to the [Geom] field that contains data for the many areas in the Mexico table.
We can use a Map window showing both the Mexico drawing and the clipping rectangle as layers to see how the rectangle created by the GeoMakeRect function is then used by GeomClip to clip the area objects in the Mexico drawing to only those portions which fall within the clipping rectangle. The result is to clip off any parts of any areas that extend above 30 degrees latitude or below 20 degrees latitude.
To create the illustration above we saved the results of the GeomMakeRect(VectorMakeX4(-120, 20, -80, 30)) expression to a new component, renamed that component ClipRect and then created a map with both the Mexico drawing and the ClipRect drawing in it as layers.
The illustration shows the coordinates of the corners of the rectangle specified by the VectorMakeX4(-120, 20, -80, 30) function which in turn is used by the GeomMakeRect function to create the clipping rectangle area object.
Where do the magic numbers used in the coordinates come from? - The latitude values of 20 and 30 are the upper and lower limits above and below which we want to clip away any parts of the Mexico areas. The Western longitude limit of -120 and the Eastern longitude limit of -80 are completely arbitrary so long as the Western limit is beyond whatever is the furthest Western extent of any of our areas in Mexico and so long as the Eastern extent is likewise beyond whatever is the furthest Eastern extent of any of the areas. So long as the rectangle extends far enough West and East to cover all the areas to be clipped it does matter what longitudes we use and thus how "wide" the rectangle is. We are using the rectangle as a "cookie cutter" so as long as the cutter is bigger than the "cookie" we are cutting it doesn't matter how big it is.
If we didn't know what were the longitudinal boundaries of Mexico but we were sure that all of Mexico was to be found somewhere only in the Western hemisphere we could have just as easily used values of (-180, 20) and (0,30), which would have formed a clipping rectangle between 20 and 30 degrees of latitude that extended from the Prime Meridian at 0 longitude where it cuts through Africa far to the South of Greenwich, England, all the way across the Western Hemisphere to the 180 longitude far out in the Pacific Ocean. If we were total slackers and had no idea whether Mexico was in the Western or Eastern hemispheres we could have used values of (-180, 20) and (180,30) for the clipping rectangle, which would create a clipping rectangle that extended all the way around the Earth between latitudes 20 and 30.
The main reason we used values of (-120, 20) and (-80,30), is that the resulting rectangle fits neatly into a small illustration like the last illustration shown above.
How do we know to use latitudes and longitude numbers? - If we turn on the Info pane with View - Panes - Info it will report the coordinate system used by a drawing or table. When we see Latitude / Longitude as the coordinate system for the Mexico drawing we know that degrees are the units of measure and that numbers such as (-180, 20) and (0,30) will make sense as the geographic degree numbers for the longitudes and latitudes we desire.
Another way to see the coordinate system used by the Geom field in the Mexico Table table, and thus by the Mexico drawing, is to right click onto Mexico Table in the Project pane and choosing Properties in the resulting context menu.
The FieldCoordSystem.Geom property tells us the coordinate system used by the Geom field.
To read the full details we can double-click into the value for the property and then use the right arrow key in the keyboard to scan through it to the right until we see, first, that it is a Latitude / Longitude coordinate system and second, that the coordinate system uses degrees as units.
Fields inherited - Objects that are created as a result of Transform operations will whenever possible inherit the data content of the fields for that record. If we replace a state in Mexico with a clipped version of that state, the alteration when we choose Upgrade Field is to the contents of the geom field. Other fields for that record, for example, any field that gives the population of the state, remain unchanged. See the discussion in the Transform Options topic.
Inner or Outer GeomClip - What does the true argument mean in the GeomClip function? That specifies the setting for the <inner> argument, whether the clip leaves what is inside the clipping area (when <inner> is true) or whether the clip leaves what is outside the clipping area (when <inner> is false). For example, when we use true in the expression:
GeomClip([Geom],
GeomMakeRect(VectorMakeX4(-120, 20, 0, 30)),
true, 0)
We get what is inside the clipping rectangle:
In contrast, when we use false in the expression:
GeomClip([Geom],
GeomMakeRect(VectorMakeX4(-120, 20, 0, 30)),
false, 0)
We get what is outside the clipping rectangle:
Transform Templates - Datetime
Example: Two Drawings from the Same Table - Take a table with a geom field that is visualized by a drawing. Add a second geom field to the table and create an rtree index on that field so it can be visualized by a drawing. Copy the first drawing, paste it and adjust the pasted copy so it uses the second geom field. Demonstrate how to use the Transform dialog to show "live" modifications in the second drawing compared to the first drawing.
Example: Copy one Column into Another Column with Transform - How to use the Transform dialog to copy the contents of one column in a table into another column, but only for selected records. Uses the Products table from the Nwind example data set.
Example: Transform Field Values using an Expression in the Transform Dialog - How the Expressions tab of the Transform Dialog may be used to change the values of fields. We include an example of changing the price of selected products and using two different Transform dialogs open at the same time for two different table windows.
Example: Construct JSON String using Select and Transform - Use the Select and Transform dialogs to manually construct a JSON string using values from other fields in a table. Shows how we can manipulate text to build desired contents in a field.
Example: Edit a Drawing with Transform Dialog Templates - In this example we open a drawing and edit objects in the drawing using the Transform dialog Template tab. Includes examples of using the Add Component button and also the Edit Query button.
Example: Use a Transform Dialog Expression to Create Buffers in a Drawing - Use the Expression tab of the Transform Dialog to create three different sizes of buffers for different lines in a drawing and then automatically create a query which does the same thing. Includes examples of using the Add Component button and also the Edit Query button.
Example: Smooth Lines with a Transform Dialog Expression - Use the Expression tab of the Transform dialog to make lines smoother in a drawing so that longer lines are smoothed more. Includes examples of using the Edit Query button to show how different queries are created automatically depending on if we want to update a field or to add a new component.
Example: Transfer Options and Merge Areas - Using the Merge Areas Transform dialog template, an exploration of the difference between using Copy and Sum for transfer options.
Example: Transform Templates, Expressions and Queries - We learn to use a function by clicking on a template in the Transform dialog, seeing what it does in a preview, looking at the query Manifold creates and then trying out the function in the Expression tab.