Example: Clip Areas with a Transform Expression

In this example we use the Expression tab of the Transform panel 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.

 

eg_xform_clip01_01.png

 

We begin with a drawing of provinces in Mexico.    The drawing geometry is stored in a geom field in a table called Mexico Table.   The drawing uses the Latitude / Longitude coordinate system, which uses geographic degrees as a unit of measure.

 

eg_xform_clip01_02.png

 

We double-click on the Mexico drawing in the Project pane to open the drawing.  The drawing has been styled to color the areas using a palette of pastel colors, and the Layers panel has been used to color the background of the drawing in a calm beige color.

 

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.

 

In the Contents pane we choose the Transform panel.

 

eg_xform_clip01_03.png

 

We click on the Expression tab in the panel.

 

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.  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.    SQL normally looks better and reads more easily when indents are used, but in this example to save space in the illustrations we do not use indents.

 

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.

 

 

eg_xform_clip01_04.png

 

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.

 

eg_xform_clip01_05.png

 

The preview shows what would be the result in the drawing if the expression were put into effect.  

 

 

eg_xform_clip01_06.png

 

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.

 

eg_xform_clip01_07.png

 

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.  

 

 

eg_xform_clip01_08.png

 

The preview again shows what would be the results.

 

eg_xform_clip01_05.png

 

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.

 

 

eg_xform_clip01_09.png

 

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.

 

 

eg_xform_clip01_10.png

 

We then press Add Component.

 

eg_xform_clip01_11.png

That creates a new table in the Project pane called Mexico Table Transform along with a new drawing that visualizes that table.   We double-click on the new drawing to open it.

eg_xform_clip01_12.png

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.  Since it is a new drawing and has not been styled, it uses default, gray formatting.

 

Another way to capture the work of the expression without changing the original data is to save it as a query.

 

eg_xform_clip01_13.png

 

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.

 

eg_xform_clip01_14.png

 

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, using Edit - Save as Query.

 

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.

 

eg_xform_clip01_13a.png

 

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.

 

eg_xform_clip01_14a.png

 

Instead of creating a new table and a new drawing the query is a simple UPDATE query as seen above.

 

Notes

How does the expression work?  We can take it step by step to see.   We will begin by opening the Mexico drawing as a layer in a map with the view zoomed out slightly.  We have used a pale blue-green background color.

 

eg_xform_clip01_15.png

 

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 using the Transform panel, clicking on the Expression tab and then entering only the GeoMakeRect function portion of the full expression:

 

GeomMakeRect(VectorMakeX4(-120, 20, -80, 30))

 

 

eg_xform_clip01_16.png

 

That expression will be immediately previewed in the drawing window, displaying the rectangle that is created by the GeoMakeRect function.

 

eg_xform_clip01_17.png

 

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.   

 

The display shows what appears to be one rectangular area, but in fact it is a stack of many identical rectangular areas, one for each record in the table.  When the Transform panel evaluates the expression it does so for each record.  Therefore, it replaces each area object for the various records, with each area object shaped in the form of the Mexican province it represents, with an area object that is a rectangle created by the expression.

 

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.

 

eg_xform_clip01_18.png

 

To create the illustration above we saved the results of the GeomMakeRect(VectorMakeX4(-120, 20, -80, 30)) expression to a new component, renamed the drawing ClipRect and then created a map with both the Mexico drawing and the ClipRect drawing in it as layers.  The ClipRect drawing layer has 50% opacity set in the Layers panel so we can better see how it overlaps the Mexico drawing below.

 

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.

 

Questions and Answers

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?  - The Component panel of the Contents pane reports the coordinate system used by a drawing.  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 by right clicking onto Mexico Table in the Project pane and then choosing Properties in the resulting context menu.

 

eg_xform_clip01_19.png

 

The FieldCoordSystem.Geom property tells us the coordinate system used by the Geom field.  We can right-click onto the cell and choose Edit to see the entire contents.

 

eg_xform_clip01_20.png

Right away we can see that it is a Latitude / Longitude coordinate system and that the units of measure used are degrees.

Notes

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:

eg_xform_clip01_21.png

 

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:

 

eg_xform_clip01_22.png

 

See Also

Style

 

Contents Pane

 

Contents - Transform

 

Command Window

 

Queries

 

Transform Templates

 

Transform Templates - Boolean

 

Transform Templates - Datetime

 

Transform Templates - Geom

 

Transform Templates - Numeric

 

Transform Templates - Text

 

SQL Functions

 

Example: Copy one Column into Another Column with Transform - How to use the Transform panel 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 Panel - How the Expressions tab of the Transform panel may be used to change the values of fields.  

 

Example: Construct JSON String using Select and Transform - Use the Select panel and the Transform panel 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 Templates - In this example we open a drawing and edit objects in the drawing using Transform panel templates.  Includes examples of using the Add Component button and also the Edit Query button.

 

Example: Use a Transform Expression to Create Buffers in a Drawing - Use the Expression tab of the Transform panel 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 Expression - Use the Expression tab of the Transform panel 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 panel 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 panel, seeing what it does in a preview, looking at the query Manifold creates and then trying out the function in the Expression tab.