Project and Design Files

This chapter covers information relevant to project and design files.

It includes:

• Design file formats

• LandXML design files

• Receiving projects/designs from WorksManager

• Design validation

• Troubleshooting designs

• File naming conventions

• Exporting a LandXML design from Trimble Business Center

• Coordinate systems

Design file formats

You can use LandXML, .dsz or .vcl designs that are created in an office design tool such as Trimble Business Center. You can also create or select an infield surface.

When you select a LandXML or .vcl design file that contains multiple surfaces, you can further select an individual guidance surface from the file and you can select a master alignment for that surface (if available).

.dsz design files only contain a single surface, so if you select a .dsz design file the system automatically selects it in the Guidance Surface field. If required, you can deselect the surface or change it to an infield surface.

The system supports filled 2D linework in .vcl files. The fill reflects the color set in Trimble Business Center.

LandXML design files

The system supports designs in the industry-standard LandXML format, loaded from a USB drive or an online service.

Store the LandXML design in the project’s /Designs/ folder, as you do with .vcl and .dsz designs. A LandXML design requires the same supporting files, such as a .cal site calibration for GNSS or UTS guidance.

The system will validate the LandXML file to ensure it is usable. For more information, see Design validation.

Supported LandXML features

Surfaces

Any surfaces must be full TIN models. Files that contain parametric surface definitions (i.e. stringlines or cross-sections), or source data (i.e. breaklines), are not supported.

For instructions on exporting a LandXML design with the correct surface type from Trimble Business Center, see Exporting a LandXML design from Trimble Business Center.

Linework

The system supports lines connecting coordinate points (either as part of a surface mesh or separately).

The system supports lines that contain horizontal and vertical geometry and station (chainage) information.

• Horizontal:

  • Straight lines

  • Circular arcs

  • Spirals (clothoid and parabola types only)

• Vertical:

  • Points

  • Circular arcs

  • Parabolic

  • Elevations defined under the <Alignment> tag are not supported. 3D linework is supported in plan features.

• Attributes:

  • Alignment/layer names created in Trimble Business Center.

  • Colors defined in Trimble Business Center. Other color definition formats are not supported.

Points

3D points marking exact locations.

Roadways

Roadways are supported through triangulated surface meshes, alignments, and planimetric features. String line, cross-section, and structural models are not supported.

Railways

Railways are supported through triangulated surface meshes, alignments, and planimetric features. String line, non-linear stationing, cross-section and track, and structural models are not supported.

Waterways

Waterways are supported through triangulated surface meshes, alignments, and planimetric features. Cross-section, string line, or structural models are not supported.

Features not supported in LandXML

The following LandXML features are not supported:

• Surfaces derived from parametric source data (i.e. breaklines)

• Surface derived from parametric surface definitions (i.e. stringlines or cross sections)

• Non-linear stationing

• Pipe networks

Receiving projects/designs from WorksManager

If you are connected to WorksManager, the service can push the latest project and design files to your system.

If the Project and Design drop-downs show a cloud icon beside the name, the project and design are managed from an online service. The cloud icon states are:

Icon	Description
	For a project: All the project files, including design files, are downloaded. For a design: The design is successfully downloaded from the online service and validation is complete. It is available to use.
	For a project: Part of the project is still to be downloaded. For a design: The design on the service is new or updated, and is queued to download to your system. It is not currently available to select. If a number displays beside the icon, it represents the design download percentage.
	There was an error downloading the project or design. It is not available to select. For more information, contact your site's data manager. There is additional troubleshooting information in the Configuration Guide contained in the technician's commissioning manuals. You can view the state of published files in WorksManager.
No icon	The design is not published directly from WorksManager.

On start-up, your system will check with the online service to ensure your designs are up to date. Any updates download automatically.

If the files are updated on the online service while your system is running, the online service sends the updates to your system. If you have a design selected when it is updated, the system notifies you and returns you to the Job Setup screen. You will need to reselect the design and the guidance surface.

If your system is connected to a service and you are in Design Mode, the Refresh button on the Job Setup screen is available. It enables you to manually check with the service to ensure you have:

• All available projects and designs

• The latest version of each project and design

If the check finds any files that are out-of-date or missing, the system automatically downloads them.

On the Project screen, you can expand the project to show the files that are included.

If the machine has Autos engaged when the project is updated, Autos will continue to operate. When Autos is disengaged, the warning message displays and the Operator App returns to the Dashboard.

Troubleshooting WorksManager downloads

Viewing the state of published files

You can view the state of published files in WorksManager.

Design validation

If a downloaded file is invalid, the Operator App reports Issue > Invalid File > Check Design.

There is an issue with the file in WorksManager. Check that the file is valid and that the design elements are supported in the grade control system.

Perform a TCC sync

For new EC520 devices, perform a TCC (Connected Community) sync to authenticate the device before you can use WorksManager.

WorksManager updates project/design that operator is using

If WorksManager updates a project that the operator is currently using, the Operator App reports Project updated remotely.

If WorksManager updates a design that the operator is currently using, and auto-archive is enabled, the grade control system deletes the design and downloads the new version. The Operator App reports Design deleted remotely.

The dashboard displays so the operator can select the updated project/design. If Autos is engaged, the system waits until Autos is disengaged before returning to the dashboard.

Re-download of deleted project is incomplete

If you delete the local copy of a project sent from WorksManager, the system re-sends the project. However, the re-sent project may be slow to start downloading.

To work around this issue, tap the Refresh button on the Job Setup screen. This re-sends the full project.

Project or design renamed on WorksManager appears to be deleted

If a project or design is renamed in WorksManager, the grade control system believes that it is deleted. The system deletes the local copy and downloads the new version. The Operator App will report either Project deleted remotely or Design deleted remotely.

Download connection is poor

If the download connection is poor, causing low download speed, you can select the project and design in the Operator App's Job Setup screen. This prioritizes these downloads above other projects and designs in the queue.

Download fails to complete

If a download fails to complete in the allotted time, the partial download can resume when the internet connection is back online.

Known issues

TCC sync delays WorksManager design download

An issue has been reported where the user could not apply a new design, despite download status of 100%.

The grade control system delays installing a design if it is simultaneously syncing large files from TCC. The design becomes available after the TCC sync completes.

Project converted from local to cloud appears twice

An issue has been seen where WorksManager adds a design to a project that is saved on a local device (so, WorksManager effectively takes control of the project). The system showed 2 versions of the project in the list on the Job Setup screen: one version with the cloud icon indicating it is linked to the cloud, and one version that appears local.

Workaround: Exit the Job Setup screen and then re-open it. The list will only show one version.

Design validation

The system supports designs in LandXML, .vcl or .dsz format. When a design is added to the system, the system validates the file to ensure it is valid. You cannot use the file until validation is complete.

When a design is queued for validation, the system shows the validating icon .

When the system is validating the design:

• The system displays the validating icon and a time on the Job Setup screen beside the design's name in the Design File menu.

• The time is an estimate of how long the validation will take.

• A warning message displays:

  On-screen Message	Description
  File > Validation in progress...	Wait for the system to complete the validation process.

  NOTE – If you load a design, the system will pause validation of other designs.

If a design was received automatically from WorksManager, the error or warning is also recorded in the WorksManager system.

Validation timing

The time that the system takes to validate your designs varies depending on the complexity of the design:

• In the Design File drop-down, the system shows a countdown of the estimated time remaining for the design that is being validated.

• To validate a specific design ahead of other designs, select it in the Job Setup screen.

Troubleshooting designs

Files within a project can fail validation for a number of reasons. This section describes some causes. Validation occurs for several file types within a project (not just designs).

Validation troubleshooting

You can receive 2 types of validation message:

• A red cross : the design cannot be used. The file fault will need correcting in the office software.

• An orange exclamation mark : the design can be loaded, but there is a warning. It may not display fully or provide guidance as expected.

The Operator App provides basic guidance on why a design fails validation. This section describes how to get more detailed information.

When the system validates a design, it creates a text file called ProjectDiagnostics.txt in each project's folder that records details of the validation. The contents of this file can help you to locate the cause of the failure and correct it.

To obtain the file:

1. Use the File Transfer screen to export the project to a USB drive.

2. On a PC, navigate to the ProjectDiagnostics.txt file in the project.

3. View the file in Notepad and scroll to the section for the design that failed validation.

4. Look for the following strings:

   • Validation State

   • Validation Warnings

   Here is an example from a design that failed validation. ProjectDiagnostics.txt states:

   • Validation State: Invalid

   • Validation.Warnings.0: Linework extends outside design boundary (400x400km)

   This design was invalid because a line element extends beyond the design boundary. There may be more than one reason why a design fails validation. The validation file records the first 5 reasons for failure.

For designs that are usable but generate an orange warning because an element is missing , you can also find detailed validation information in the Web Interface's Monitor > Program Log screen. Look for warnings relating to <NavigationProcessorComponent>. For example:
WARNING - <NavigationProcessorComponent> Validation warning: Linework extends outside design boundary (400x400km)

Issues that stop the system from loading the design include:

On-screen Message	Description
Issue > File Missing > Check File Structure	You cannot load the design because the system could not find the file. This issue can also occur if the file is present but is 0 kB.
Issue > Unrecognized Format > Check Design	You cannot load the design because the system does not recognize the file format.
Issue > Invalid File > Check Design	You cannot load the design because the file is invalid. This may be because: The file does not conform to the design schema. (This condition does not apply to LandXML.) Units of measure are not defined in the file. The units that are defined are unsupported. The maximum number of line elements is exceeded.
Issue > Invalid File > File Size Too Large > Check Design	You cannot load the design because the file’s size is too large: For .vcl files, the limit is 150 MB. For LandXML files, the limit is 50 MB. For .dsz files, there is no size limit.
Issue > Surface Too Complex > Check Design	There are too many triangles in the design's TIN model (more than 65,0000 in one page).
Missing project coordinate system file	The system cannot find a .cal file for this project. Check the project's \OfficeData\ folder.
No Measured Data selected	Select a Measured Data file in Job Setup screen.

Issues where there is a problem with the design, but you can still load it, include:

On-screen Message	Description
Avoidance zones do not work with a 2D positioning source	The selected project contains one or more avoidance zones, but cannot display them because you are using a 2D positioning source.
Design File > Surface Issue Design loaded, but only valid TIN surfaces will show. Check the design file.	The system can load the design, but there is an issue with one or more surfaces: The surface may be missing an element. The surface is not a valid TIN model.
Design File > Surface Issue Design loaded, but one or more surfaces contain missing or invalid data and may be unusable. Check the design file.	The system can load the design, but there is an issue with one or more surfaces. Causes include: Missing faces or points Invalid points Invalid face Face refers to non-existent points System cannot process the surface TIN model
Design File > Surface Issue Design loaded, but surface is out of date and should be rebuilt in office.	The design was updated in Trimble Business Center but the TIN surface was not updated to match. See Project and design creation in Trimble Business Center.
Design File > Linework Issue Design loaded, but one or more layers contain missing or invalid linework data and may be unusable. Check the design file.	There are many possible causes of this error. Refer to the ProjectDiagnostics.txt file for more detail.
Linework elements unsupported in LandXML Line is not 2D or 3D Curve is not 2D or 3D Curve has inconsistent radius Curve length does not match provided length Curve has undefined bearing or arc length Invalid point list Point list has incorrect number of values Line color is unknown format Point has invalid coordinates Point has no name Curve has invalid rotation Curve has invalid or no center coordinate Start/end dimensions do not match Line has wrong contents Alignment does not have a name Alignment has no staStart or length Alignment total length does not match
Linework elements unsupported in VCL: Unsupported linestring elements: Dependent Location Three Point Arc Dependent Three Point Arc Dependent Segment Three Point Arc Dependent PI Arc with elevation Offset with useSlope Offset endpoint with negative along Endpoint with StationOffset Line only has one horizontal element Error converting string to double cgPoint contains no value or reference Invalid spiral radius Cannot find point in layer No layer exists Circular referencing Invalid point Cannot find point in lookup table Point name should be unique Feature tag has empty label Feature tag has empty value Invalid PI dimension Spiral start and end point is neither 2D nor 3D Linework contains bad data Unsupported linework type Unsupported linestring vertical elements: eStationSlopeToParabola eStationSlopeFromPI eStationSlopeFromParabola eStationSlopeToFromPI eStationSlopeToFromParabola eStationSlopeToArc eStationSlopeFromArc eStationSlopeToFromArc Singular best fit arc linestring element Best fit arc linestring element with the same start and end points Smoothed polylines Smooth Curves RoadIntersectionLinestring UtilityLine Hatch Moss6D Linestring with no elements 3D spirals Smart text Decreasing stationing Point Coordinate Component Point Coordinate Type Vertical alignment segment of type “<type>” Offsets to alignment spirals Any entities defined on a cutting plane Any entities defined using a User Coordinate System Composite surfaces Only single point coordinates supported, <number> points found Only alignments with curve type = “arc” are supported Only alignments with spiral type = "Clothoid" or "Cubic" or "Cubic Parabola" or "NSW Cubic Parabola" or "Half Sine" are supported

Design complexity limits

A design can also fail validation if it contains too many elements. Exceeding the following limits can cause a design to fail validation:

Element	Limit
Dense surface	Avoid using surfaces where the TIN triangles are too small, e.g. under 0.01 m² per triangle or has more than 65,000 triangles in an area of 50 m x 50 m.
Too many points	160,000 points.
Oversized TIN triangles	TIN triangles with 40 km sides. If you require extremely large TIN triangles, use .dsz format.
Avoidance zones	The system supports multiple avoidance zones with up to 800 segments (or sides) each. For best performance: Try to keep individual polygons below 500 segments. Break up a large or thin polygon into multiple polygons with similar dimensions. If an avoidance zone fails validation, refer to the ProjectDiagnostics.txt file to troubleshoot it.

In addition, use of the following may cause issues within a design:

• Contains a spiral, horizontal cubic, or NSW spiral

• 3D lines of curves

• Complex vertical segment arcs with horizontal spirals

• Ferguson linestring elements

• Excessive text/labels

• Excessive line names

• Excessive layers

• Design triggers many warnings/information notes

File naming conventions

This section describes appropriate naming conventions for files in projects (including designs):

• Ensure all designs have a version number in the name. If you edit the file, increase the version number.

• Ensure that version numbers are uppercase. The Operator App may show the version number in uppercase, even if it is actually lowercase.

• When you create or edit an infield project, the project name must be 225 characters or fewer.

• When a file is imported to the system from an online service or from USB, the system automatically converts the filename extension to lowercase (for example, .dsz, .vcl, .xml, .ggf, .cal).

• If the system encounters two versions of a file with the same name and version number:

  1. If one version is sent from an online service, it is retained and the local file is deleted.

  2. If both files are on the local system, the file with the newer date is retained and the older file is deleted.

• Avoid duplicate filenames.

• Avoid using slashes and backslashes in design file names.

• Avoid using symbols and emojis in design file names.

• Ensure geodata file names (.ggf) are lowercase (filename and extension).

• Avoidance zones files must always end with .avoid.svl.

• Linework files end with .svl.

Exporting a LandXML design from Trimble Business Center

1. In TBC, click the Export icon. The Export dialog displays.

2. Select LandXML exporter from the list of file formats.

3. Select Options > Select All from the Data field.

4. Click the ... button in the File Name field.

5. Specify the filename and the stored location.

6. Set the Surface description in the Settings field to 2 – Triangles. This ensures that all surfaces are TIN surfaces. Other forms of surface are not supported.

7. Click the Export button.

To use the design in the grade control system:

1. In File Explorer, navigate to the location you selected when exporting.

2. Copy the LandXML design file.

3. Paste the file into the grade control system's USB file structure: ProjectLibrary / Projects / (Project Name) / OfficeData / Designs.

4. Use the USB file transfer method to import the design into the system.

The system does not support .tsd files exported from TBC as a .dsz design. To use data from a .tsd, export the file from TBC as a .vcl and import the .vcl file into the grade control system.

Project and design creation in Trimble Business Center

You can create project files in TBC v3.80 or later. For customers using TBC's .vcl design file format in the grade control system, use TBC v5.21 or later.

When you generate a design in TBC for use in the grade control system, ensure the surface is up to date. If the surface rebuild method is set to Show empty or By user, the surface may be out of date which can cause a design validation error. You can right-click on the surface and select Rebuild Surface before exporting the design.

Coordinate systems

Selecting a coordinate system

When you create a project, you can select the coordinate system to work with - if your technician gives you permission (this feature is disabled by default).

You can either create the .cal file for the project by selecting the correct coordinate system (such as a national reference system) or copy the .cal file from another existing project. This feature can be useful if you don't have a .cal file, but you know your published coordinate system requirements and have the right correction source.

Enabling the feature

This feature is recommended for advanced users and it is disabled by default. Your technician can enable it via the Web Interface's Operation > File Management screen.

Confirming your coordinates are accurate

1. Create the project and select your coordinate system:

   1. Select the Job Setup screen.

   2. Tap the button beside the Project dropdown. The Create Project screen displays.

   3. Enter a name for your new project.

   4. Select the type of coordinate system you want to use from the Coordinate Setup dropdown:

      Item	Description
      Default (Universal)	The system automatically selects a coordinate system to generate the .cal file.
      Existing Calibration File	You can select a .cal file from one of your existing projects.
      Published	You can select from a list of published or made-available coordinate systems.

2. Save your design and enter the work screen.

Viewing the coordinate system details

You can check the details of a project's coordinate system in the infobox on the Projects screen.

To view the Projects screen, tap the button beside the Project dropdown on the Job Setup screen.

Using a grid file that isn’t published

In previous versions of the software, CoordSystemDatabase.xml and the .cal file must both list any grid files. If they were not in the .cal file, they wouldn’t be usable. These grid files that are referenced in CoordSystemDatabase.xml are called “published”. This made it challenging to add new grid files to the system.

However, you can now also add a grid file to a project without needing to mention it in the .cal file. These grid files are called “independent”. Place the file in the \GeoData\ folder.