Example: Use a Transform Expression to Create Buffers in a Drawing

In this example we use the Expression tab of the Transform pane to create three different sizes of buffers for different lines in a drawing.  We then automatically create a query which does the same thing.


 User interfaces for the Transform pane have been changed.  See the Transform Reference topic for guides to new interfaces while this topic is updated.



We will start with a drawing that shows the locations of Roman roads in Europe and around the Mediterranean as lines.  The drawing is shown as a layer in a map with a Bing satellite base layer for background.   Major roads have been styled in green and minor roads in yellow, slightly thinner lines.


If we open the table for the drawing we see that there is a CLASS field that describes whether the road is a major or minor road.



Clicking Ctrl-End jumps us to the end of the table.   We can see that the values in the CLASS field include the text values Major Road and Minor Road



We will click on the map and then zoom into a region in France center on the town of Bourges where we know that some roads are major roads and some roads are minor roads.    Our task is to create buffer zones, that is, area objects, around the major and the minor roads but to create a substantially larger buffer around the major roads instead of around the minor roads.



The point of such a task in archaeological research might be to define target regions for remote sensing searches, perhaps using ground-penetrating radar, with the notion that it may be worthwhile to search larger regions adjacent to major roads where there might be a greater likelihood of finding structures or other remains than with minor roads.


With the focus on the Roads drawing layer in the map, we use the Transform pane to create buffers, using the Buffer template.



In the above, we have clicked on the Buffer template, chosen Geom as the target field, Geom as the source geom field and a Distance of 2000 meters for the buffer.   The default Distance unit is meters because this drawing (as we could see by taking a look at the Info pane) is in Pseudo Mercator, the same as Bing, and that projection uses meters.



As soon as we choose the Buffer template and begin entering Distance values the pane right away previews what will happen in blue preview color.    That is fine, but we do not want to create the same buffers for both major and minor roads, we want in a single step to create buffers of different sizes for the major roads and the minor roads.


To do that, we click on the Expression tab in the Transform pane, so we can enter an expression.



The Expression tab allows us to write an SQL expression that will be immediately evaluated, on the fly, as we write it with the results being previewed in the drawing window.  The results shown are only a preview until we click the Update Field button.


We write the expression in the upper pane.   In the middle pane, Manifold shows us all the fields of the table.  In the lower pane is a list of SQL constructs, such as operators and functions, we can use.



We plan on using the GeomBuffer function.  To find it, we start entering the name of the function into the filter box.   As we enter Geom the list of functions shown gets reduced to only those which match what we have entered so far in the filter box.



As we get to GeomB the list is reduced even further.



By the time we enter GeomBu that leaves only one function.  We double-click on the GeomBuffer function to add it into the Expression window without having to manually keyboard the name of the function.



The pane has all the fields associated with the drawing's table so we can save some more keyboarding by highlighting the <geom> argument in the function template and then double-clicking the Geom field where the geom data for the drawing's lines are stored.    White space is not significant in the Expression tab, so we can start a new line after the <geom>, argument and then a few space character to indent the next line, which makes the expression we are writing fit better into the illustration and look prettier.



That automatically enters the name of the field.   We then change the <tolerance> argument to a value of 0 (meaning automatic tolerance) and proceed to manually enter the rest of the expression we will use.



In this case we will use the following expression:


GeomBuffer([Geom], CASE [CLASS]

  WHEN 'Major Road' THEN 1000

  WHEN 'Minor Road' THEN 5

  ELSE 0.05 END, 0)


The value of the <distance> argument for the buffer is set by CASE depending on the value of the CLASS field.  We will use a distance of 1000 when the value of CLASS is 'Major Road', a value of 5 when the value of CLASS is 'Minor Road' and a value of 0.05  when the value of CLASS is anything else.  


The moment we enter the above expression, or when enough of it is entered to be understandable as an expression, Manifold starts evaluating it and starts previewing the result in the drawing window.  



In the illustration above we can see that larger buffer areas have been created around major roads.  The minor roads also have buffers created around them, but in a zoomed out view the difference between buffers which are at a distance of 1000 meters from the line and those which are 5 meters from a line gives the impression there are no buffers on the minor roads.


We can see that effect by zooming far into the drawing and changing the values in the CASE to be used for buffer distances for major roads and for minor roads to 100 and 20.



The expression in the above illustration is:


GeomBuffer([Geom], CASE [CLASS]

  WHEN 'Major Road' THEN 100

  WHEN 'Minor Road' THEN 20

  ELSE 0.05 END, 0)


Right away as we change the values Manifold will change the preview of the result in the drawing.     If we zoom far in to where such smaller buffer distances are visible we see that the buffer areas on the major roads really are bigger than the buffer areas drawn around the lines for the minor roads.



No matter what we write in the Expression pane the results we see in the drawing are only a preview.  As we change the expression the preview dynamically changes.



The expression in the above illustration is:


GeomBuffer([Geom], CASE [CLASS]

  WHEN 'Major Road' THEN 3000

  WHEN 'Minor Road' THEN 5

  ELSE 0.05 END, 0)


For example, we can make the buffers on the major roads, at 3000 meters, very much larger than those on the minor roads, at 5 meters.



Or, if we like we can make the buffers on the minor roads, at 2000 meters, larger than the buffers on the major roads, at 500 meters.



The expression in the above illustration is:


GeomBuffer([Geom], CASE [CLASS]

  WHEN 'Major Road' THEN 500

  WHEN 'Minor Road' THEN 2000

  ELSE 0.05 END, 0)


Right away, as we change the expression the preview of the result in the drawing window will change.



At any time we can commit changes to the drawing by pressing the Update Field button.  Or, if we prefer we can write the new objects to a new component, that is, just the buffer areas, which are created by the expression.


To do so we change the Update Field action in the pull-down menu to Add Component.



We can then click on Add Component.



Two new components, a new table and a drawing for that table, will be created in the Project pane.



We can drag and drop the Roads Table Transform Drawing into the map to see the new drawing in context.  We can see that the buffers which are created by the expression have been saved into the new table and new drawing that were created by the Add Component button.



Note that using the Add Component button does not change anything in the original data.   It simply writes the new objects which are created by the expression into a new table and then creates a new drawing to visualize that table's geometry.



We can Style the newly created drawing of buffers, to use transparent fill color for the buffer areas, so only the area borders appear.  We can color those in yellow and green to show minor and major roads.  In the illustrations above we have turned off the original Roads layer, to better see only the new layer that we have added.


Automatically Creating a Query

At any time we can see the SQL that the Expression tab uses to work its magic.  


We first reset the action button back to Update Field.



If we click the Edit Query button a Command Window will open up that is loaded with the query that the Expression tab is executing.



We can use this capability to save the query for later use, to edit the query in a more sophisticated way than is convenient in the Expression tab or simply to learn more about how SQL can be used.  In the query above the PRAGMA sets up the progress bar, which given the speed of queries is unlikely to appear at all unless the data set is very large.  The THREADS statement parallelizes the query, telling the query engine to use as many threads as there are CPU cores available.


If we would like to save the query in the Command Window as a query component, we choose Edit - Save as Query.


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 create buffers on lines the alteration when we choose Upgrade Field is to the contents of the geom field.   Other fields for that record remain unchanged.


See Also



Select Pane


Transform Pane


Command Window




Example: Transform Field Values using an Expression in the Transform Pane - How the Expressions tab of the Transform pane may be used to change the values of fields.  


Example: Edit a Drawing with Transform Templates - In this example we open a drawing and edit objects in the drawing using Transform pane templates.  Includes examples of using the Add Component button and also the Edit Query button.


Example: Clip Areas with a Transform Expression - Use the Expression tab of the Transform pane to clip areas in a drawing to fit within horizontal bounds.   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 pane 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.