We learn to use a function by clicking on a template in the Transform pane, seeing what it does in a preview, looking at the query Manifold creates and then trying out the function in the Expression tab.
User interfaces for the Transform pane have been changed. See the Transform Reference topic for guides to new interfaces while this topic is updated. The current build does not do previews in map windows.
Previews in Manifold show in blue preview color what a proposed command will do before we issue that command. Previews can save us from errors. When it is obvious what a proposed operation will do we can correct our workflow before committing any changes.
We start with a map with one layer, a drawing of regions in France as areas.
We launch the Transform pane.
We click on the Convert to Line template. This drawing uses Geom as the name of the geometry field that contains the shapes of objects in the drawing.
The moment we choose the Convert to Line template Manifold will preview what that template would do to the drawing in blue preview color. The template takes area objects and converts them to lines by drawing a line for the boundary of the area.
We can see what SQL magic is used behind the scenes to accomplish that conversion by pressing the Edit Query button.
That launches the Command Window loaded with the SQL query that is used to do the conversion. The query is simple: it starts with a housekeeping PRAGMA statement that sets up the progress bar to show progress in case of long computations. The THREADS statement is just the usual automatic parallelization that says to use as many threads as there are CPU cores in the system.
The heart of the query is a single function, GeomConvertToLine([Geom]), which takes the [Geom] field and converts whatever is in it to a line object.
Manifold is full of such useful functions. In addition to reading documentation and browsing functions within lists in the Query Builder, clicking on templates in the Transform pane to see what they do and then clicking the Edit Query button to see how the SQL works is a great way to learn about functions and how to use them.
Now that we know about the GeomConvertToLine([Geom]) function we can use it in our own, custom work. We copy the function from the Command Window (no need to keyboard when we can copy and paste) and then back in the Transform pane we paste it into the Expression template in the pane.
The Transform pane has two tabs: the Template tab provides a list of point-and-click templates while the Expression tab allows us to write our own expressions that are snippets of SQL expressions. The expression above use the same function used by the query we automatically created:
The Expression tab is like a blend of the convenience of a point-and-click infrastructure of the Template tab with the custom power of SQL in the Command Window.
The moment we paste the function into the Expression pane Manifold goes to work to preview it.
Not surprisingly, since we copied and pasted the function from the SQL created for the Convert to Line template, the preview for the function as evaluated in the Expression tab creates exactly the same preview as for the template. That is OK and cool, but more interesting is that now that we know about the function we can play around with writing a more customized expression using the function in the Expression tab.
For example, the drawing of provinces has the French identification number for each region as one of the fields for each record. We can write an expression that converts to lines only those provinces which have an identification number greater than 30:
WHEN [Number] > 30
Manifold will immediately evaluate the above to create a preview.
The preview above shows that all regions which have a Number value greater than 30 will be converted into lines. Those regions which have a Number value less than or equal to 30 will be copied in unmodified form.
So far, what we have created are just previews. The actual data has not been modified. If we like what we see, we can apply the transform by clicking the Update Field button.
The moment we click the Update Field button Manifold will apply the transform to the drawing.
If we did not want to change the drawing we could have changed the Update Field button to Add Component and then pressed the Add Component button.
That would have created in the Project a copy of the drawing, as modified by the transform, without modifying the original drawing.
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 pane 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 pane 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 Pane - How the Expression template in the Transform pane may be used to change the values of fields.
Example: Construct JSON String using Select and Transform - Use the Select pane and the Transform pane 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 pane templates. Includes examples of saving results to a new component and also the Edit Query button.
Example: Use a Transform Expression to Create Buffers in a Drawing - Use the Expression template in the Transform pane 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 saving results to a new component and also the Edit Query button.
Example: Clip Areas with a Transform Expression - Use the Expression template in the Transform pane to clip areas in a drawing to fit within horizontal bounds. Includes examples of saving results to a new component and also the Edit Query button.
Example: Simplify Lines with a Transform Expression - Use the Expression template in 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.