March 2020

Introduction

Trimble Siteworks v1.20 has added the ability to use Trimble VCL files for several functions within Siteworks.  VCL files are a Trimble-proprietary file format exported by Trimble Business Center (TBC).  These files can be used as design files, site (background) maps, and avoidance zone files.   When using VCL files for linework data, the user will have the same functionality as with DXF/DWG files.  When using surface data from the VCL file, the user will experience the same behavior as with TTM files.  More information on how to produce VCL files in Trimble Business Center for use in Siteworks can be found in the relevant TBC documentation.  

Siteworks offers some of the same functionality as it does .PRO files when using Corridor Data from a VCL file, but also some additional and enhanced functionality is gained. However, some of the workflows around using and selecting the data have changed when using VCL Corridor data.  Additionally, VCL files now offer equivalent and enhanced Roading functionality to .PROs on the Android platform since .PRO files are not and never will be supported on Android devices. 

Several benefits of using VCL files over the existing TTM/DXF/DWG/PRO design scheme are:

• One VCL design file now can contain points, multiple surfaces, multiple corridor surfaces, multiple template surfaces, and multiple alignments.  This reduces the file and design management burdens of office and field personnel.
• Direct design file sharing capabilities with Trimble Earthworks  v1.9 and above.
• Ability to choose any alignment and get a station/offset and cut/fill to any selected active surface.
• 3D visualization of Corridor Surfaces and Corridor Template Surfaces.
• Corridor and Corridor Template surfaces can now be used in volume calculations.
• Design contour lines can now be created and visualized in the map view for Corridor and Template surfaces.
• Richer data format allows for enhanced future capabilities.
• Support for Corridors, Alignments, Cross sections and Templates on Siteworks Mobile for Android.

The use of VCL files for any Corridor and Alignment-related functionality in Siteworks requires the purchase and installation of the optional Roading Module on both Windows and Android platforms.  The Roading option is not required to use VCL files for points, surfaces, and linework.  If an alignment is present in a VCL design file and the Roading module is not installed, the alignment will be treated as a normal polyline and stationing along the Alignment will not be available. 

Export

Siteworks does not write out any data to VCL files. There is no export to VCL files from within Siteworks.  Linework is still written to a DXF file, surfaces are still saved as TTM files, and Key-in Road data as .PRO files.  Note that Key-In Road functionality and reading or writing .PRO files is not and never will be available on the Android platform. 

When saving the measured surface as a design, the user still has the option to merge the measured surface with the active design surface of the VCL. The merged surface will be saved as a TTM surface in a new design folder.

The user can also still select to include the VCL linework when saving the measured surface as a new design. The design VCL’s linework will be saved as a DXF file in the new design folder.

Background/Project Map

A VCL file can be used as a Project background map, similar to a DXF/DWG file.  This Is a  separate VCL file from any VCL designs or avoidance zone files.  

While creating a new site, the user can select a VCL file as the “Project Map” file. If the project is already created, the user can copy the VCL file into the project’s root folder and all the linework within the VCL file will appear as the background linework. 

Only the linework from the Project Map VCL file will be displayed in the map views when the project is loaded; alignments and text data are not displayed. The linework in the Project Map cannot be selected or interacted with. This is the same behavior as with DXF/DWG files currently used as Project Maps in Siteworks.

Avoidance Zones

When placing a separate VCL file with the file name <filename>.avoid.VCL in the project’s root folder,  closed circles and polygons present within the file will be used as the project’s avoidance zones. This behavior matches the current behavior of DXF/DWG avoidance zone files.   Siteworks does not support embedded Avoidance Zone boundary types as defined in Trimble Business Center, it will simply treat any closed polygon present in the <filename>.avoid.vcl as an avoidance zone.  

VCL Designs

A valid VCL design and associated design folder contains a single VCL file and an optional CSV stakeout point file. The design folder can also have an additional Siteworks-created DXF file in it to continue supporting Siteworks’ ability to create circles and arcs via the COGO feature.  If an additional DXF with design linework is in the design folder with the VCL file, that linework will also be present and selectable on the map screen.  It is recommended to only use the Siteworks COGO-created circle and arc DXF files in the design folder when using VCL files and not include an additional DXF linework file.  This will reduce the potential for operator confusion and errors when selecting linework and objects to stake from the design.  

When creating a design in Siteworks, the user is able to select a VCL file as the “design file”. Once selected as the “design file”, the VCL is automatically selected as the linework file, and the “design map” (linework) file selection will be grayed out in the Create Design screen.  All of the linework in the VCL file will be displayed and available for selection, regardless of the surface selected.  In other words, all the linework in the VCL file will be visible and selectable no matter what surface is selected to be active.  

When selecting a VCL design, a new “Surface” combo box is displayed. This combo box is used to select the ‘Active’ surface to be used in Siteworks. Only one surface can be the ‘Active’ surface at a time. The combo box will contain all the supported surfaces from the VCL file, and will display an icon to indicate the surface type.

The user can change the ‘Active’ surface from the “Surface” combo box displayed in the “Open Project” window when a VCL design is selected, or from the “Surface” combo box displayed in the “Surface Settings” window (accessed via the Main Hamburger menu).  Note: The “Surface” combo box is only displayed in the “Surface Settings” window while in the Measure feature, if the setting window is accessed from the Stakeout feature, the combo box will be hidden.

Open Project Screen Showing new Surface Combo Box

VCL Surfaces

Siteworks supports three surface types defined in a VCL file: Surface, Corridor Surface, and Corridor Template Surface.  Tapping and holding on the active surface in the Siteworks map screen will give the user a Tap and Hold menu, with the option to “Stakeout Surface”.  Similar to TTM surfaces, this menu option will take the user to the stakeout surface feature.

A “VCL Surface”  is one or more triangulated surface(s) defined in the VCL file. This surface type is treated the same as a TTM surface. The user can use these surfaces as the grade check surface in the measure routine, as the second surface in the measure feature, as a stakeout surface in the Stakeout feature, and as a design surface in the COGO features.  Cross sections are not available when using a VCL Surface. VCL Surfaces are shown in the 3D view similar to how TTMs are currently displayed.  These types of surfaces can be used in volume calculations. 

A “Corridor Surface” is a triangulated surface generated in Trimble Business Center from the defined cross sections for a Corridor model. The Corridor Surface is treated like a TTM surface in Siteworks. The user is able to select this surface as the grade check surface in the measure feature, as a second surface in the measure feature, as the stakeout surface in the Stakeout feature, and as the design surface in the COGO feature. Corridor Surfaces are shown in the 3D view.  Cross sections are not available when using a Corridor Surface.  Corridor surfaces can now be used in volume calculations.  

When selecting a Corridor Surface as the active surface, the surface's alignment, as defined in TBC, will be automatically selected as a reference line. The reference line can still be changed/deselected using the Settings > Reference Line Hamburger menu option or the Select as Reference Line Tap and Hold menu option.  

A “Corridor Template Surface” is the surface defined by the corridor’s templates created in Trimble Business Center. This surface is similar to .PRO roadway surfaces.  A Corridor Template Surface can be used as the grade check surface in the measure feature. In the Stakeout feature, the user can select to stake the corridor template as a surface, stake specific features and nodes from the template data, or stake catch points from the template data. The Corridor Template Surface cannot be selected as a second surface.  Corridor Template surfaces are shown in the 3D view.  Siteworks will display a cross section view similar to a .PRO roadway when using a Corridor Template Surface.   

Similar to Corridor Surfaces, when a Corridor Template Surface is selected, the surface’s alignment associated via TBC is automatically selected as the reference line. The user can select or change/deselect the template surface’s alignment as the reference line using the Tap and Hold menu option or through the Settings > Reference Line side menu option.

When a Corridor Template Surface is used to Compute Volumes, displayed in the 3D view, or when design contour lines are generated, the Corridor Template Surface is internally converted to a Corridor Surface in Siteworks. As a result, the design tie slopes will be included as part of the surface. However when using the Corridor Template Surface feature in the Measure, Stakeout, and COGO features the template data only is utilized and the design tie slopes are not included as part of the surface.

Surface Offset

Regardless of the VCL surface type being used as the active surface, the user can apply a surface offset to it. The surface offset setting is accessed in the “Surface Settings” window, which can be accessed from the side panel menu, information bar button, or some workflow settings buttons.

The VCL surfaces can be offset vertically or perpendicularly above or below the original surface. Once the surface offset is set for the current active surface, it will be applied in all Siteworks features (Measure, Stakeout, and COGO).  

Changing the active surface through the “Open Project” window will default the surface offset setting to zero. Changing the offset through the “Surface Settings” window will apply the surface offset value displayed in the same window.

The current surface offset value will be saved with the measured data, just like when using a TTM or PRO design.

VCL Points

Similar to point data from a DXF/DWG file, if a 3D or 2D point in the VCL file has a valid point name then it can be used in Siteworks.  VCL points are displayed as an “X” in the map view just like DXF/DWG points. These points can be toggled on/off with the “Stakeout points” Map Option.  VCL Points that do not have a valid name associated with them will be drawn as a hollow circle and are not selectable within Siteworks.

A VCL point can be selected in the stakeout feature and COGO features. Tapping and Holding on the VCL point will give you the same menu options as Tapping and Holding on a stakeout point from the design’s stakeout point CSV file.

VCL Lines

Line data from the VCL design will be displayed in the map views of Siteworks. All the valid lines within the VCL file will be displayed, regardless of the design’s surface selection.  The lines can be selected in the stakeout feature, the COGO features, or as reference lines. Tapping and holding on the lines will display a Tap and Hold menu similar to the one currently seen with DXF/DWG linework data.

The line data can be toggled on/off in the map view using the “Design” map option setting or by toggling the individual design layer the line data is on.

If the VCL line data has a defined name, that name will be displayed in Siteworks. Otherwise Siteworks will use a generic “Unnamed CAD” string as the line’s name, as is currently done with unnamed lines in DXF/DWG files. The line’s layer name will also now be displayed as part of the tap and hold menu title bar. 

VCL Alignments

All defined Alignment objects created in TBC and exported into the VCL design are displayed and selectable in Siteworks. The alignments can be used as reference lines, selected in the stakeout feature to stake a station and offset location, and in the COGO features.

Unlike with .PRO files, selecting an alignment does not automatically select the surface associated with that alignment. The user has to manually select the surface they want to use via the “Surface” setting in the “Surface Settings” or “Open Project” window.

The alignment data visibility can be toggled via the “Corridor” map options setting or by selecting/deselecting the design layer the alignment is on. 

The Tap and Hold menu for the VCL alignment will give the option to stake a location (station and offset) from the alignment or select the alignment as a reference line.

Measure

 If the user has a surface from the VCL file selected in the measure feature they will see a Cut/Fill, Design Elevation, and Thickness values displayed in the information bar and recorded with the measured point. These values are only displayed while the user is over the active surface.

This is the same functionality and behavior as with a TTM or PRO design. However, when using a Corridor Surface or Corridor Template Surface, the surface’s alignment will be automatically selected as the reference line. If the user changes or deselects the surface’s alignment as the reference line, Siteworks will highlight the surface’s alignment as a blue line. The “Station” and “Offset” value displayed in the information bar will be to the surface’s alignment, and the reference station and offset values will be to the selected reference line. Siteworks will continue to only record the reference station and offset with the measured data.

 The active surface name will be recorded with the measured data in the format of [Design Name]:[Surface Name].

Second Surface

VCL Surfaces and Corridor Surfaces can be used as second surfaces in the measure feature. However, you can only select second surfaces from the currently loaded VCL design and not from a separate design file.  VCL Corridor Template surfaces are not selectable as a second surface.

In the “Second Surface Settings” window, you can select the current VCL design as the “Second surface design”. Once selected, a “Surface” combo box is displayed, allowing the user to select a surface from the VCL design.

There is no change in functionality when using a VCL surface or VCL Corridor surface as a second surface, compared to when using a TTM surface.

Stakeout

Siteworks supports the staking of lines, points, alignments, and surfaces from the VCL design. If the active surface is a Corridor Template Surface, then template nodes, and template catch points can be staked.

VCL Points

Staking VCL points behaves the same as staking other points in Siteworks. The points can be selected via the Tap and Hold menu or through the Stakeout Object selection window. In the Stakeout Object selection window, the point can be selected by tapping on it in the map view, by manually entering the point’s name in the “Object” input field, or by selecting it out of the “Point” table in the “Select Object” window accessed by tapping the List icon button.  As with DXF/DWG points, the point must have a defined name.  

Once selected, the point can be staked. A side slope can also be projected from the point, and the side slope or catch point can be staked.

The stake report’s data and saved data for the VCL point matches the stake reports and saved data for any other selectable point in Siteworks.

Just like with DXF points, a 2D or 3D point can be selected and staked. An elevation for the point can be defined if the user wants to stake a side slope or catch point from the 2D point.

VCL Lines

Staking lines from the VCL design behaves the same as staking lines from DXF/DWG designs. The lines can be selected via the Tap and Hold menu and through the Stakeout selection window. In the Stakeout selection window, the line can be selected by tapping on it in the map view or by selecting it from the “List” table in the “Select Object” window (accessed by tapping the List icon button).

Once selected, the user can stake the line, a side slope from the line, or a catch point projected from the line.  The line direction of the VCL line can be reversed. A horizontal and vertical offset can also be applied to the selected line.

VCL Surfaces

Only the ‘Active’ surface (i.e., the currently selected surface in the “Surface” combo box displayed in the Surface Settings or Open Project window) can be staked. Once a surface from the VCL file is selected as the active surface, the user can select the surface to stake via the Tap and Hold menu or through the Stakeout feature.

In the Stakeout feature the user can select the surface by tapping on it (note that if there are other objects in the tap radius they will be selected instead), by manually entering the surface’s name in the Object input field, or by selecting the surface from the “Surface” table in the list window. The “Surface” tab will only list the currently active surface, regardless of the surface type (VCL Surface, Corridor Surface, or Corridor Template Surface).

If a VCL Surface or Corridor Surface is selected, the only stake method option is “Surface”.  The “Surface” stake method is the same as staking a TTM surface. For Corridor Surfaces, the surface’s alignment will be selected as the reference line if no other reference line is currently selected. If a different line is selected as the reference line, the user will be asked if they want to use the Corridor Surface’s alignment as the reference line. Selecting to use the surface’s alignment as the reference line will set the reference line to the surface’s alignment for all features. The user can still manually change the reference line to a different line if desired.

If the user selects to stake the active VCL Corridor Template Surface, they will have the following stake method options: surface, template nodes, template catch points.

Selecting the “Surface” stake method for the Corridor Template Surface behaves the same as selecting the same option for a Corridor Surface. The template surface’s alignment will be selected as the reference line if no other reference line is selected. If another reference line is already selected, then the user will be asked if they want to use the Corridor Template Surface’s alignment as the reference line.

Selecting the “Feature” stake method will take the user into the same workflow and features as staking roadway nodes from a .PRO file. The stakeout reports, stake options, and saved data for staking VCL template nodes is identical to .PRO node features.

Selecting the “Catch Point” stake method for a VCL template surface will take the user into the same tie slope selection workflow that was used with .PRO files. This workflow has the same options of selecting existing tie slopes, defining custom tie slopes from a selected node, or using the outer segments if there are no defined tie slopes. The stakeout reports, settings, and saved data for staking a VCL catch point match staking a .PRO catch point. Note that SIteworks v1.20 only supports basic design tie slopes that are defined from the last node of the cross section during template creation in TBC.  If tie slopes are defined in the middle of the cross section or via look-up tables, these types of tie-slopes are not yet supported.  

Just like with .PRO data, the tie slopes will always be projected from the original surface, even if a surface offset is applied to the Template Surface.

VCL Alignments

An alignment in a VCL file can be selected to stake via the Tap and Hold menu or through the Stakeout feature. In the Stakeout selection window, the user should be able to select any VCL alignment by tapping on it in the map, entering the alignment’s name in the Object input field, or selecting the alignment from the “Alignment” tab in the list window.  Note that if still using a .PRO there will be a “Corridor” tab instead of “Alignment” where the user can select any available corridor from the PRO file.  

Staking a VCL Alignment is slightly different than staking a .PRO Alignment. When a VCL Alignment is selected (as opposed to the VCL Surface associated with it) the user is only able to stake a station and offset location. Selecting this option takes the user into a workflow similar to staking a location from a HAL only or HAL/VAL .PRO alignment (i.e. a .PRO with no corridor surfaces or templates present).  The user is able to select a station and offset to define the stake location. They are also able to define the elevation for the stake location. The elevation options available to the user will change depending on if the selected alignment is 3D (HAL and VAL) or 2D (HAL only) alignments. Having a surface associated with the selected alignment does not have any impact on the stakeout options.

When staking a 3D VCL Alignment, the available elevation options are: ignore, define grade, vertical offset, manually entered elevation, and design surface. The design surface will be the currently selected VCL surface.

For 2D VCL Alignments the available elevation options are: ignore, manually entered elevation, and design surface. The design surface will be the currently selected VCL surface.  In the Siteworks v1.20 release, there is no ability to stop at either horizontal or vertical alignment Tangent Point nodes.  Siteworks will only currently select stations based on the interval value entered as part of the Corridor Settings. 

COGO

VCL data of points, lines, alignments, and active surface are supported for use in the Siteworks COGO features.

Review & Edit Data

In the Review & Edit Data COGO feature, the user can select VCL lines and points when defining segments for compute distance, compute total distance, compute area, and compute down and out. The user can use VCL points for computing angles, and can use the active surface for computing volumes.  This includes all surface types of VCL surface, Corridor Surface, and Corridor Template Surface. 

Create Points/Arcs

In the Create Points/Arcs feature, the user is able to select VCL Lines, points, and alignments. Similar to DXF data, the user can select the VCL lines and points for the tools that use line segments. The user is able to select VCL points for the toolbar that uses points.

The VCL Alignments are only selectable for the Create Point at Offset from Corridor and the Deflection from Corridor tools.

Key In Corridors

The Key In Corridor COGO feature still only generates .PRO roadways. VCL Corridor Template Surfaces cannot be created or edited in Siteworks.  Key in Corridors and writing .PRO files are not available on Android OS devices.  

Cross Section View

Siteworks supports displaying a Corridor’s Template cross section in the cross section view window. The template cross section will be displayed when measuring a VCL Corridor Template Surface, when staking a VCL Corridor Template Surface, and when staking a corridor’s template feature or catch point.

When a surface offset is applied to a Template Surface, both the original template cross section and the offset template cross section will be displayed in the cross section view.

While in the Measure feature with a Template Surface selected as the active surface, the cross section segment the user is currently over/under will be highlighted.  A vertical line from the user’s location (in the cross section view) to the highlighted segment will also be drawn.

When staking a VCL Alignment, the cross section view will generally show the alignment’s location marked by a small dot underneath a CenterLine icon and the entered offset location desired to be staked as an open green circle. A red line will typically be drawn connecting the two locations.  If there are no elevations for either the Alignment (HAL only) or the desired stake point (Elevation set to “Ignore”) then there will be no display in the cross section view.  When the Elevation Method is set to Vertical Offset in the Station Selection screen there will be a vertical line representing the vertical offset and a horizontal line representing the horizontal offset to the desired stake location. For all other Elevation methods, a straight line will be drawn from the alignment’s position to the desired offset position location.   

Enhancements

Unlike with .PRO designs, Siteworks now displays the Corridor Template surface in the 3D View and is able to generate and display design contour lines for the surface. However, the 3D View surface and the design contours are generated from a surface version of the Corridor Template Surface, so the design’s tie slopes are included.  As a result, when the user’s location is over the design tie slopes, Siteworks won’t display design elevation data in the measure feature even though they are over the 3D surface or within the design contour area.

In the Stakeout feature, the user is able to select a corridor alignment independent of the active surface/corridor. This will allow the user to stake a station and offset from any VCL alignment to the currently active surface, even if that surface isn’t associated with the selected alignment.

In the Stakeout Object selection window, if the user taps on the alignment for the active surface, they will get a new pop-up menu giving the user the option to select the alignment or the active surface. This is to help .PRO users transition to VCL data. With .PRO data the user selects the alignment to stake the cross section data. With VCL data, the user has to select the Corridor Template Surface to stake the cross section data.

In the Review & Edit Data COGO feature, if the active surface is a Corridor Template Surface, the user can use it to compute the volume between the measured surface and the template surface. It is important to note that the template’s design tie slopes will be included in the volume computation.  These tie slope surfaces are calculated in TBC and are dependent on what surface the user had selected when defining the template and may not be part of the original design and may extend outside the boundaries of the design’s footprint.  Therefore, volume calculations may include calculated or extrapolated data instead of design data only.   To see the extents of the Template surface that will be used to compute the volume calculation the user can turn on design contours from the Map Options settings. The red line drawn around the design surface indicates where the design tie slopes end.

When saving the current Work Order’s measured data as a new design, the user now has the option to merge the measured data with the Corridor Template Surface. When merging the measured data with the template data, the design tie slope segments of the template surface will be included in the merge. To see the full extent of the template surface that will be included in the merge, the user can turn on the design contours from the Map Options setting.  The red line around the design surface seen in the plan map view indicates the extent of the Template surface, and what data will be used when merging the template surface with the measured surface.

Known Issues

The following items are known to be issues with VCL files in the Siteworks v1.20 Release. If any issues are consistently encountered please work with your local Sitech dealer to submit a support case.  Please include the VCL file and relevant details (e.g. steps to replicate, screenshots, videos) of exactly what the issue is so that the Siteworks team can effectively address the issue.  

• Current support does not include the use of Tie Slopes from a lookup table.
• Horizontal and Vertical Tangent points are not currently supported when advancing down an alignment. 
• Certain workflows will result in the “Surface” (displayed in the Open Project window) to be empty. Loading the project with the “(No Surface Needed)” option selected and then returning to the “Open Project” should re-populate the “Surface” combo box.  This issue occurs mainly when switching between a .PRO and VCL file.  Users not opening a .PRO should not experience this issue.