Table of Contents
- Activating Your License
- What’s New
- User Interface and Workflow
- The Basics…
- Integration with the AutoCAD Civil 3D User Interface
- Visual Report Designer User Interface
- Insert Report Wizard User Interface
- Insert Report to Layouts User Interface
- Advanced Topics
- The Basics…
- Advanced Topics – Data Entities
- Point Locations
- Corridor Cross Sections
Visual Report Designer is an AutoCAD Civil 3D plug-in application which allows the user to visually design and create rich, data bound reports from their Civil 3D drawing objects. The resulting report documents may be saved to PDF, HTML, CSV, etc, or may be inserted directly into a DWG. Visual Report Designer consists of an Editor Component where reports may be defined, and several additional components which allow previously designed reports to be executed individually and/or in batch mode.
Visual Report Designer v4.x requires that you have the .NET Framework 4.0 and at least one version of AutoCAD Civil 3D (versions 2012 through 2016 – .NET 4.5 is also required for AutoCAD Civil 3D 2015/2016) installed on your machine in order to run. It will only install on 64-bit versions of Windows.
Visual Report Designer is intended to be loaded into AutoCAD Civil 3D as a plug-in using the AppAutoLoader feature introduced in AutoCAD 2012. The application files are automatically installed to the following location:
TIP: Note that previous releases may have installed to the application plugins folder located either in your local user data folder or under ‘C:\ProgramData\Autodesk\ApplicationPlugins’…if present after upgrading or uninstalling the old version, these files should be removed prior to running AutoCAD Civil 3D. These files would be located in a ‘C3PTVisualReportDesigner.bundle’ folder found at the following location:
If present, you can delete the entire old ‘bundle’ folder for Visual Report Designer.
TIP: If you do not know where your %AppData% folder is located, open Windows Explorer, type %AppData% in the address bar, and press the enter/return key. Windows will automatically resolve this shortcut and navigate to the actual folder. The most common location for this folder is: C:\Users\<username>\AppData\Roaming\Autodesk\ApplicationPlugins
Also note that installation REQUIRES admin permissions as it automatically installs for ‘all users’.
Terminating the Autodesk InfoCenter Process
If AutoCAD Civil 3D crashes or terminates abnormally and hangs up on subsequent attempts to restart, you may need to manually terminate certain running applications using task manager. If this occurs, start task manager and first look for process file called ‘WSCommCntr4.exe’ (the ‘4’ in the example filename may be a different number on your machine depending on what version of AutoCAD Civil 3D you are running).
Terminate this process and AutoCAD Civil 3D should start to work again; if it does not, then look for and terminate all instances of AutoCAD (acad.exe) and subsequently restart AutoCAD Civil 3D.
Activating Your License
After installing Visual Report Designer, you will need to activate your license before you can run the application. You may need administrative privileges in order to complete this process.
1) Run AutoCAD Civil 3D and open a drawing (or start a new one)
2) Look for and select the ‘civil+plus’ ribbon tab at the top of the AutoCAD Civil 3D window
3) Click on the ‘Activate Visual Report Designer’ icon in the ‘Visual Report Designer’ ribbon panel
5) In your purchase documentation emails, you should have received an activation key code…enter this in the field provided here. If activating a new installation that is to connect to an existing network license, you can leave this field blank and proceed to the ‘Advanced Options’…
6) If installing a standalone license, click ‘Activate Now’ to proceed with activation. Note that if you are using a proxy or are attempting to configure a network license, you will need to turn on the ‘Advanced Options’ using the button provided.
If you enable the ‘Advanced Options’ feature, the ‘Activate Now’ button on the main activation dialog will change to a ‘Next…’ button. Either click on this or select the ‘advanced…’ tab manually. In this dialog you may:
- Set the ‘License Mode’ (Standalone or Network)
- Set the path to the network license file share
- Manually activate your license with a code provided by tech support if you are unable to connect to the license server/activate automatically.
- Enable the ‘Connect using a proxy’ option (if you enable this you will be provided an opportunity to set your proxy configuration settings).
A complete version history for the latest version of Visual Report Designer may be found here .
User Interface and Workflow
Integration with the AutoCAD Civil 3D User Interface
When Visual Report Designer is properly deployed and activated, the AutoCAD Civil 3D user interface will be automatically updated with a custom ribbon panel as shown below:
There are eight commands in the standard Visual Report Designer ribbon panel (developer/NFR editions may contain more)
- Visual Report Designer: launches Visual Report Designer
- Insert Report Wizard: Launches a wizard used to select a report and insert it into the current DWG. Also used for modifying and updating reports already inserted into the current DWG.
- Insert Report to Layouts: Launches a wizard which used to insert a copy of a report on each of several selected layouts, with a viewport from each layout used to form a boundary filter for the instance of the report on that same layout.
- Batch Export Reports: Launches a wizard which enables reports to be executed in a pre-defined sequence (with pre-defined settings) as a single task/process.
- LinkVpToBlock: Links a viewport in paperspace to an anchor block for automatically inserting a report to the layout.
- Update All Reports: Updates selected VRD reports in the current DWG.
- Update All Reports: Updates ALL VRD reports in the current DWG.
- ShowVrdStatusLog: Enables and shows the Visual Report Designer status log window.
TIP: If you lose the Visual Report Designer or the Insert Report Wizard window behind your AutoCAD (or another application) window, just click on the appropriate button on this ribbon to bring it back into focus. If this does not work, use the Windows task bar to ‘maximize’ the VRD window after which you may restore it to its floating/non-maximized state.
Visual Report Designer will automatically add two new commands to the AutoCAD Civil 3D ‘block’ context menu which appears when the user right-clicks with an inserted report selected:
These new commands allow you to update the ‘selected’ report(s), or ALL reports in the current drawing.
TIP: The Insert Report Wizard and Visual Report Designer windows cannot both be open at the same time. Likewise, you cannot ‘update’ a report already in a drawing if either window is currently open.
Visual Report Designer will also add a command to your ‘viewport’ context menu, plus a new ribbon bar visible only for selected viewports:
The new command accessed via the context menu and the ribbon bar allow you to define a link between a special block and a viewport, thus allowing the ‘Insert Report to Viewports’ command to automatically determine the correct viewport-based boundary filter and the proper location at which to insert the report.
Visual Report Designer User Interface
The Visual Report Designer user interface resembles many familiar office applications, and most features should be familiar to the user. It is arranged as several docked panes comprising:
- a ribbon bar
- a toolbox containing various controls which may be added into a report
- a status bar
- a tabbed multi-document editor
- a field list which contains a hierarchical listing of all available fields for inserting into the report
- a report explorer which contains information about the logical arrangement of the report contents
- a properties window which displays the properties of the currently selected item in the editor
- other panes/windows (such as the script editor, and the ‘Group and Sort’ pane shown below, etc)
Further, there are three ‘views’ of the report which may be selected via tab controls at the top of the application window:
- Report Designer: This is where you construct your report documents
- Print Preview: This view allows you to view a report generated using data from the currently active DWG in AutoCAD Civil 3D. The user is given the opportunity to adjust the query settings used to mine the project data when populating the report each time the Print Preview and HTML View views are activated.
- HTML View: Similar to print preview, but views the report document in HTML form.
TIP: The Insert Report Wizard and Visual Report Designer windows cannot both be open at the same time. Likewise, you cannot ‘update’ a report already in a drawing if either window is currently open.
The report document consists of a document container filled with bands. Each band may contain other bands, detail reports, or it may contain controls. There are several types of bands which may be inserted by right-clicking in the document and selecting from the Insert Band context menu item.
The Detail Band is special in that it is automatically bound to the CivilDocument Entity, which is the root entity for all bound data in the current drawing. It may also contain child Detail Report Bands which are bound to the various entity collections shown in the Field List. Detail Report Bands will automatically contain a child Detail Band which may in turn contain both controls and child Detail Report Bands which are bound to the child collections defined for the entity collection bound to the parent Detail Report Band. The easiest way to understand this is to see a couple of examples:
Example 1: A simple report bound to the Points entity collection:
Example 2: A slightly more complex report framework which is bound to both the Corridors and the Baselines entity collection, the latter being a child of the former:
Tool Box and Field List – Adding fields to your report
The Tool Box and the Field List are both used to place controls into the report via drag/drop. If you use the Tool Box to insert a control, no data binding will be pre-set for that control – you can manually set the data binding via the control’s Task Pane (and in the Property Grid with the targeted control selected). If, however, you select a field and drag it into a band in the active report document, an appropriate control will be created (based on field type and attributes) and will be automatically bound to the dragged field. Note that in order for the control to actually contain data in a report, it must be located in a detail band of the appropriate entity type. For example, if you place a label bound to the Point.PointNumber field in a Detail Report Band bound to the Alignments collection, it won’t return a meaningful result.
Certain toolbox based controls are unbound, meaning that they do not retrieve any data from the drawing. Examples of such controls are Lines, Shapes, Picture boxes, etc.
The field list is the primary source for quickly adding data-bound label controls into the report:
When a field is dragged into a band in a report document, an appropriate control is created; if an entity collection is dragged from the field list into a band, a table is created.
For individual fields, one of several label types will be automatically selected based on the nature of the field:
- Generic fields will use Argumented Label controls by default, however, basic Label controls are also valid and can be used with manual binding; ‘arguments’ cannot be applied to fields referenced via basic Label controls.
- Fields referring to point coordinates will use Argumented Label controls.
- Fields containing generic angular values will use Angle Label controls (supports arguments).
- Fields containing directional values will use Directional Label controls (supports arguments).
- Fields which require references to other AutoCAD Civil 3D entities to calculate a value will use Reference Label controls (supports arguments).
- Fields representing an entity ‘image’ will use an Entity Image Box control, which is NOT currently available via the toolbox – it can only be added by dragging an image field from the Field List into the document. The Entity Image Box control is not the same as the Picture Box control, which is available via the toolbox.
TIP: You must use an Argumented Label control (or another label control which is derived from this) in order to utilize the arguments feature when referencing a field.
TIP: Entity Image Box controls are only available by dragging an ‘image’ field (actual field name may vary) into the report. The binding will be automatically pre-set as is the case with all other controls generated by dragging/dropping from the field list. You can change the binding via the task pane for this control; however take care to only change it to another ‘image’ field if you choose to modify the control’s settings using this method.
Some fields will also automatically apply formatting to control visibility based on certain characteristics of the bound data (e.g. alignment sub geometry fields will automatically hide themselves if the current sub-geometry entity is of the wrong type).
The Argumented Label control allows you to specify additional data which may affect the value returned by the field. The most common use of this is to re-project point coordinates in the report. To do this, a coordinate system must be specified for the drawing, and a different coordinate system is entered for the Arguments property in the Properties Window (with the control selected) or via the task pane (see below):
You will also find the option to change the value for this field in the Task Pane for the control (more on this below).
In addition to an Arguments field, the Reference Label control uses a Reference Query field in the Properties Window (and in the Task Pane) in order to specify a reference query for the control to use.
In this case, the property field will contain a button labeled with an ellipsis (“…”) which will bring up the Select Reference Query Dialog when clicked:
This dialog will allow you to select from a list of previously defined reference queries, or create/edit/delete reference queries. Click on the combo box button on the right side of the selection control to bring up the following popup dialog for creating/editing/deleting reference queries, or to simply select from the list:
If you click the ‘New’ (or ‘Edit’) button, you will see the Create New Reference Query dialog:
Specify a name (make this something meaningful) and press the OK button to save it to the report. Note that the Query Properties grid allows you to see the target entity type(s) the query will be configured to use.
The reference query selection mechanism contains safeguards to prevent the user from selecting queries which target the wrong type of drawing entity – such contextually invalid queries will not be shown in the list. Regardless of whether a query is present in the current list, its name MUST be unique in the report, as must the name of any new reference query. For example, you cannot have two queries named ‘Query1’ regardless of the targeted entity type(s).
TIP: If you need to delete an ‘orphaned’ reference query created for a Reference Label which no longer exists in the report or has changed binding/context, use the ‘Show All’ option in the ‘Select Reference Query…’ dialog:
All controls have a Task Pane which may be accessed via the button with the “>” symbol which appears at the top right corner of the control when it is selected. This dialog allows you to specify values for special properties of the control. For example, the Task Pane for a Picture Box control looks like this:
Edit Queries Dialog
When switching between the Report Designer and either of the other views, you will be shown the Edit Queries dialog:
There are two types of queries which may be edited here:
- Root Queries: These query settings control the entities used to generate the primary entities collections bound by the report. Only those queries targeting entities which are data-bound to your report (via detail report bands) will be shown in this dialog. These queries by default will search the entire collection of valid entities in the current drawing, however, you may restrict the search to a selection set using the SelectionSet property (use the ‘…’ button to select objects). Wildcards in the other fields are ‘simple’ – i.e. only one wildcard may be used per field. If you wish to select all points named with the prefix “ROW”, you could use the wildcard filter “ROW*” for the Name field. Entities may also now be filtered by a boundary filter – if specified, only those entities which lie within the boundary are considered.
- Reference Queries: These queries are created and uniquely named by the user while designing the report and are used to enable bound entities to reference other entities from the current drawing in order to perform a calculation (e.g. the OffsetToAlignment property of the Point entity requires a reference to an alignment object in order to return a value). Reference queries require a single entity selection via the SelectionSet property.
Selection sets may be set by selecting from a list of object names (if no ‘name’ is available, an object handle/id is shown), or by picking from the current DWG:
Boundaries may be selected in a manner similar to specifying a selection set. In addition to being able to select a boundary from a list of items, there is an option to determine whether an entity (which is checked based on an origin point/point location) which lies directly on the boundary should be included in the resulting selection set:
In addition to the queries for determining which entities from the drawing will appear in the report, there are also ‘Query Extensions’ shown in this same list (where appropriate). A query Extension is essentially a set of properties, child entity queries, and/or rules which apply to the entire group of entities of a given type which are used to generate a report. For example, the EndArea Volume Computation Query Extension found in the Corridor ‘Root’ Query, contains rules/filters used to further refine the corridor sub-entities used for volume calculations, settings telling the reporting engine where to find the required configuration files, and a ‘SurfaceQuery’ to enable inclusion of sampled surfaces in the calculation (and section views…).
The ‘SurfaceQuery’ contains a set of filters similar to those found in a Root Query, including the Selection Set Editor which allows you to select the targeted entities by name or by picking from the current DWG:
Print Preview – Preview, Export/Export and E-mail, and Insert to DWG
In the Print Preview view, you will be able to see the result of binding the current report to the current drawing with the specified query properties:
From here, you may print the report, modify the layout parameters, adjust page colors, add watermarks, export the report to various formats (and optionally e-mail the exported document), or insert the report to the current drawing. The following screen capture shows a listing of the supported formats for exporting report files:
If you use the Insert to DWG command, you will see the Insert to DWG Options dialog:
This dialog allows you to modify the scaling of the inserted report, control whether it is paginated or continuous, adjust spacing and layout for paginated reports, and adjust other pertinent settings. Reports are inserted to AutoCAD Civil 3D as blocks. Inserted reports no longer require Visual Report Designer to be viewed in a DWG – inserted blocks now reference unique block definitions for each instance, thus allowing the contents to be viewed by any appropriate version of AutoCAD or AutoCAD Civil 3D regardless of whether Visual Report Designer is installed. Note that if Visual Report Designer is not installed on a machine which is viewing a DWG containing inserted reports, the ‘update’ commands for the reports will not be available. An example of the report shown above in the Print Preview inserted into a DWG is shown below:
Insert Report Wizard User Interface
The Insert Report Wizard is designed to allow end users who may not need to use the full report creation and editing capabilities of Visual Report Designer and instead simply need to run a report which has already been defined for them (by their CAD Manager, a DOT or other agency, etc). It is also useful for users who have already created their own reports in the designer and simply wish to quickly run these reports without loading the designer, and to modify the settings of and update reports which are already inserted in a drawing.
TIP: The Insert Report Wizard and Visual Report Designer windows cannot both be open at the same time. Likewise, you cannot ‘update’ a report already in a drawing if either window is currently open.
The ‘Preview’ button will bring up a window similar to the Print Preview tab in the Visual Report Designer user interface from which you will be able to modify print settings, print the report document, and export/export and e-mail.
The ‘Insert to DWG’ button allows you to insert the generated report document into your active AutoCAD Civil 3D drawing. If you simply click on the button, focus will shift to AutoCAD and you will be asked to digitize a location in the drawing. If the drawing is currently in model space, the report must be inserted in model space; if the current drawing is in a particular layout, the report must be inserted in that layout. To insert the report in a different layout, or in model space regardless of what layout the drawing is currently in, use the pull-down list on the right side of the button:
This list is automatically populated with an entry for ‘model space’ and an entry for each layout within the current drawing. Selecting one of these will enable you to insert the report into that layout (or into model space) by automatically switching the drawing to your selection prior to prompting you for the report insertion point.
The ‘Update in DWG’ button will update the selected report in the drawing (if it exists), using the current settings for the report, or if the appropriate option in this dialog is selected, using the current dialog settings. This button will only be enabled if a report is available to be updated in the drawing.
Select Report Tab
The Select Report tab is used to choose the report you would like to run. To select a report, simply choose it from the list of available reports and click on the ‘Next…’ button to advance to the ‘Set Queries’ tab.
To configure the source locations for reports (and the categorization/group names) use the ‘Options’ button. This will bring up the following dialog window:
This dialog enables you to specify the folders which contain your report files and assign an alias to each folder (immediately after the folder path, enclose the alias in ‘brackets’). If specified, the alias will show as the category header in the Select Report Tab of the Insert Report Wizard; if not, the full path will be used.
You may include as many paths as you like, each with or without an alias. Enter each path on a separate line.
If a report exists in the drawing, a small triangle will appear next to the report name in the available reports list; by clicking on this you will be able to expand the report to show all individual instances of that report in the drawing. Selecting a specific instance will cause any ‘update’ operation to apply to that instance only; selecting the report name will apply updates to ALL instances of that report. All ‘selected’ instances will be highlighted in your drawing with a red box around the report extents:
Set Queries Tab
The Set Queries tab contains the same information and controls as does the Edit Queries dialog in the Visual Report Designer user interface. Use this tab to control what entities are used to generate your report, set query extension data, and to set reference query target selections.
The ‘import’ and ‘export’ options are not yet implemented…
The Options tab is the same as the Insert to DWG Options dialog seen in the Visual Report Designer user interface. It allows you to control the options used for inserting the report into your AutoCAD Civil 3D drawing.
Insert Report to Layouts User Interface
The Insert Reports to Layouts command allows you to insert a report into each of several selected layouts as a batch operation, using a viewport in each layout to automatically determine a boundary filter for the report inserted into that layout. The viewport may be selected automatically, or via a link to a specially inserted block which serves as an anchor point for the inserted report. If the block anchor option is not used, the starting point for the layout will be used.
Reports are selected via the combo-box editor in the upper-left region of the dialog. When you click in this control, a categorized drop-down list containing all reports found in the pre-defined search paths will be shown. Search paths are defined using the ‘Edit Search Paths’ button and are shared with the Insert Report Wizard.
When a report is selected, the list of layouts in the current DWG will be updated. If a layout is valid as a selection for the currently selected report, it will be ‘enabled’, otherwise it will be ‘disabled’ in the list. To select or de-select a layout, click on it in the list and then click on the checkbox. Reports will not be inserted on any de-selected or disabled layouts.
The Report Options tab contains the Query Editor and Reference Query editor controls. These controls are used to specify the selection criteria for the entities to be included in the report.
The Insert Options tab allows you to modify the general settings which control how a report will be inserted into the DWG. Additional settings (such as the targeted anchor block, horizontal and vertical offsets from the anchor point, etc are specified within the report document definition and cannot be changed in this wizard/dialog).
Inserting the Selected Report to Selected Layouts
After selecting the report, selecting the layouts, and adjusting the queries and settings as desired, the report may be inserted to the selected layouts using the ‘Insert to Selected Layouts’ button in the lower-right corner of the window.
Visual Report Designer supports advanced features such as custom formatting of values, conditional formatting of text (including controlling text visibility), grouping/sorting of data, creation of calculated fields, calculating summations, filtering data, and running programmatic scripts. These topics (among others) will be addressed below.
To create a custom format for a numeric value, use the Task Pane to access the Format String property:
Clicking on the ‘…’ button in the Format String field will bring up the Format String Editor dialog, which allows you to specify a pre-made format string, or create a custom format string yourself :
The Formatting Rules property on the Task Pane allows you to create custom rules to control text size, color, visibility, etc.
Data Filtering and Sorting/Grouping
Filtering is done via the Task Pane for the detail report for which you want to filter data. Use the ‘Filter String’ property to do so:
Clicking on the ‘…’ button in the ‘Filter String’ field will bring up the ‘FilterString Editor’, which will allow you to construct a filter string, which is just a logical test to see whether a field value (or values) matches a condition (or conditions):
Sorting/Grouping is done via the ‘Group and Sort’ pane in the designer. If this pane is not already visible, use the ‘Windows’ menu icon on the ribbon bar to turn it on:
‘Grouping’ allows you to organize the report data based on a group defined by the values of a specified field (all entities in a group are of the same type by definition). For example, you could group entities based on Style Name, so that all point entities with style set to ‘Fence’ will be grouped together in a report.
‘Sorting’ allows you to control the order in which the data/entities are listed in the report; sorting requires a field on which to sort the data, and a sort order (either ascending or descending).
The Summary property allows you to create summations in the report. For example, let’s say you want a parcel report which lists the areas for each parcel, and then sums the areas at the bottom of the report. You would create a Detail Report Band bound to the Parcels entity collection, insert the appropriate bound labels into the Detail Report Band, and then insert another label bound to the Area field of the Parcel entity in the report footer. You would then select that last label and edit the Summary property via the Task Pane. In the Summary Editor, you can specify the Summary Function, the bound field (preset for you), the format string, whether to ignore ‘null’ values, and how the elements being summed are to be grouped.
Calculated Fields and Expressions
Calculated fields are created in the Field List. These fields use expressions to calculate values from other entity field values. These may be used for converting a value to alternate units, or for calculating quantities from corridor section areas and distances between sections.
Parameters are variables (or named values) which may be created and integrated into the design of a report. A default value is set at design-time, and when the report is run, the user will be able to set the value of the parameter(s) via the Edit Queries dialog in the designer, the Set Queries tab of the Insert Report Wizard, or the Report Options tab of the Insert Report to Layouts dialog. Parameters may be used to allow the user to make choices which affect the logic of a report, to specify values for specific fields, or to pass through as arguments in Argumented label controls to affect the reported values of the fields bound to the controls (e.g. a parameter may be used to specify a coordinate system which may then be used to re-project a point to report the coordinates in the specified coordinate system rather than in the drawing coordinate system). Parameters are added using a context menu accessed by right-clicking on the ‘Parameters’ collection found at the bottom of the field list:
The ‘Add New Parameter’ dialog is brought up if the ‘Add Parameter’ menu item (above) is selected:
Added parameters will show up in the field list under the ‘Parameters’ collection:
You may delete a parameter by right-clicking on it in the field list and selecting the ‘Delete’ menu item:
If the ‘Edit Parameters’ menu item is selected, the ‘Parameter Collection Editor’ is shown:
This dialog allows you to modify all parameters in the current report in one location as well as add/remove parameters.
Argumented properties are a mechanism by which you can cause the value of a field to be dynamically calculated for each reference in the report. As seen previously in this document, the arguments are set via an ‘Arguments’ property in any label control supporting this feature. If the bound field also supports an argument, any value you enter will be used to modify the field results according to the type of argument specified. For example, an argument used in a positional field may reference a coordinate system and therefore cause a transformation to be applied to the position prior to returning the referenced value. An argument may also reference a user defined parameter which contains a value such as a coordinate system.
Arguments are specified using the following format:
Single argument reference:
\<Escape Sequence>[<argument value>]
Multiple argument reference:
\<Escape Sequence>[<argument value>]|\<Escape Sequence>[<argument value>]|…
Valid Escape Sequences:
- Parameter Reference: \param
- Coordinate System: \cs
- Generic String: \str
- Reference Query: \refq
- File Reference: \file
- Field Name: \field
- DWG Custom Property: \dwgprop
- Generic Integer: \int
- Bounded Integer: \intrange
- Generic Number: \num
- Regular Expression: \regex
Some arguments support multiple values, such as ‘Bounded Integer’. In these cases, the values are specified as comma delimited lists in between the brackets shown above (e.g. \intrange[<value>,<lower limit>,<upper limit>] ).
Arguments referencing user-defined report parameters and DWG Custom Properties are resolved to the value of the parameter/property as the argument is used by the reporting engine. These arguments may be nested inside of other arguments, such as a Coordinate System argument:
By doing this, you can specify the actual coordinate system value to use as the report is created rather than relying on a hard-coded value in the report template.
Visual Report Designer supports the use of custom scripts written in C#, VB.NET, or Jscript.NET. The default language is C#. To access the scripting interface, use the ‘Scripts’ icon in the ribbon bar.
This will change the report document view to the script editor. Inside the script editor you can add event handlers for specific controls in your report (based on control name), add new methods, create variables, etc.
The scripting language may be changed via the property grid for the current report:
The script editor does not currently include an ‘Intellisense’ feature like Visual Studio. Because of this you will be dependent on your knowledge of the syntax of your language of choice, as well as the arguments, argument types, and return types for function/method calls. The Visual Studio object browser is an invaluable tool for API discovery. We have also compiled a list of useful class diagrams available here .
Additional information about using the scripting feature (including tutorials) will be added at a later time. For any questions in the meantime please contact technical support .
Advanced Topics – Data Entities
Visual Report Designer uses a pre-defined list of entities which wrap AutoCAD Civil 3D (and plain vanilla AutoCAD) entities. The entities exposed in Visual Report Designer allow the reporting engine to access commonly used properties of the AutoCAD/Civil 3D entities, and also give you various internally calculated fields which are not part of but are derived from the AutoCAD/Civil 3D entities, and alternate entity configurations (similar to data views in databases). For certain fields, there are additional options which may be set to control the reported values (e.g. via argumented properties, query extensions, reference queries, etc). In some cases, special entity collections are created to facilitate reporting based on relationships with other entities (see ‘Paired Points’ below). Some of the more common configurations are described below.
Point entities in Civil 3D (COGO Points) are typically organized by point groups. In Visual Report Designer, the point group is simply a field in the point entity, thus by default Visual Report Designer will show the points for the ‘_AllPoints’ group. The points used to generate a report can of course be filtered via queries or filter strings in the report itself, and the reported points can be grouped within the report based on the point group field. By ‘flattening’ the point groups collection to a single points collection, you are given the most flexibility as to how your point reports are created and how the data are grouped and formatted.
Visual Report Designer introduces a new concept called ‘Paired Points’. This does not exist in AutoCAD Civil 3D. It is a collection of ‘child’ point entities which are related in some way to a parent point object (from the primary ‘Points’ collection). For example, a use for this would be for drill path points for oil/gas wells: The primary point, or ‘Well Surface Point’ would show where the drilling would start, and a series of drill path ‘Paired Points’ would represent the path of the drill for that well. The easiest way to relate these points is by point name – e.g. the well center point might be ‘WC1’, ‘WC2’, etc, and the drill path points might be ‘WC1DP1′, WC1DP2’, etc for the first well, and so forth.
The criteria use to define this relationship (and thus separate the ‘Paired Points’ from the primary ‘Points’ collection) is defined as an extension to the Point Query:
The ‘ExcludePairedPointsFromPrimaryResult’ property is used to remove the ‘Paired Point’ entities from the primary ‘Points’ collection. If disabled, any ‘Paired Points’ found will coexist in both collections simultaneously (this is not a common situation, thus the default value of ‘true’ for this property).
The ‘PairedPointSelectionRules’ property contains a collection of user-defined relationships between points:
The ‘ParentPointNameFilter’ property allows you to determine which point names can be associated with paired points; the ‘PairedPointNameRule’ property determines what the paired point names should be for the current parent point (the ‘@’ symbol is used as a placeholder representing the name of the parent point entity).
You may have as many Paired Point Selection Rules as desired. When determining the associations, the first rule found to apply to a given point will govern the determination for that point. It is therefore a good idea to use a well thought out naming convention for naming parent and paired points where there are no conflicts or overlaps.
Most ‘Point2D’, ‘Point3D’, or derived fields (such as ‘Location’ fields) will support coordinate transformation, surface projection, alignment projection, boundary operations, etc. regardless of the entity the location is exposed by. This means that a label anchor location, a cogo point or paired point location, and a polyline vertex among many others) will all support these features.
Point coordinate transformation is achieved via argumented properties in one of two ways:
- Via a coordinate system argument (e.g. ‘\cs[CANA27-10TM115]’)
- Via a referenced report parameter (nested) which contains the coordinate system description (allows the user to set the value in the ‘Edit Queries’ dialog or tab as a report is previewed or inserted to a drawing) (e.g. ‘\cs[\param[MyCoordinateSystemParam]]’ where the string parameter ‘MyCoordinateSystemParam’ might contain a value such as ‘ CANA27-10TM115’).
In either case the drawing MUST have a coordinate system set in the drawing settings in order for the projection to occur. If the projection fails for any reason, a value of ‘NaN’ (‘Not a Number’) will be returned for the transformed coordinate.
TIP: The same technique is used to provide a coordinate system for calculating lat/long for a point if no coordinate system is specified for the current drawing (if the drawing already has a coordinate system set, this value will be used for lat/long unless overridden via argumented properties).
Projection to Alignments
A special ‘composite’ field is provided for calculating the projection of a point location to an alignment:
The alignment is specified via a reference query, and in the event that the reference query contains several viable alignment to which a projection may be made, the closest alignment will be used automatically. When you drag a field from this composite field, a ‘Reference Label’ will be automatically created, thus exposing the reference query user interface for defining and specifying a reference query:
TIP: If you need to specify both a reference query and another argument for a given field reference, use the more generic ‘Argumented Label’ control (drag from the toolbox and manually bind to the correct data collection via the label’s task pane). Specify the argument as follows:
Projection to a Surface
The ‘Elevation’ field of any 3d point location may be use a projection to a surface to calculate the reported elevation instead of using the actual point elevation. This is useful if you need to calculate a ‘delta elevation’ between a point and a surface for accuracy checks, etc. The mechanism is similar to that used for projecting point locations to Alignments (above) – a reference query is used to define the target surface and is referenced by name in the Reference Label created when the field is dragged onto the report.
A point location may also be related to a boundary in Visual Report Designer. Like the ‘ClosestReferenceAlignment’ field, the ‘ClosestReferenceBoundary’ is a composite field which contains additional fields.
The ‘_CustomPropertyExtensionValue’, ‘ObjectId’, and ‘XDatumValue’ fields are taken directly from the boundary object. The ‘DistanceTo…’ fields are calculated based on where the point lies within the boundary.
TIP: By default the distances are projected along the cardinal directions; if you want the perpendicular distance to the boundary (at the segment which has the perpendicular in on the correct side which is closest to the cardinal direction) you must prefix the name of the reference query with a ‘~’ character.
Another special field is provided to enable you to determine whether a point location lies within the boundary of a surface:
Dragging this field into the report will result in the creation of a Reference Label which is used in a similar manner to those found in the descriptions above.
Corridor Cross Sections
Corridors and related entities such as cross sections are the most complex set of entities in Visual Report Designer. These give you the ability to report on corridor information sampled directly from your corridor objects without needing to first create sample lines. Some of the section (and related) entities also allow automatic merging with sampled surface data, thus allowing you to create complex quantity reports which can seamlessly combine both earthwork and structural quantities in a single report. Corridor sections also support the creation of section view images in the report. These images are generated dynamically – i.e. there is no need to use a sample line or even have a single section view in your drawing. The colors and symbols used for the various components of the section, as well as the specification for the section view graphics (gridlines, etc) are all taken directly from the styles associated with the entities or specified via query extension.
Sorting Corridor Section Shape Geometry Segments/Links
Corridor section shape geometry is generally defined as a collection of links which form closed polygons. In some cases, such as when creating a report compliant with the German REB standard, it may be necessary to report these links in a particular order, and even starting at a particular location on the shape. This is accomplished via the Shape Geometry Sorting Options query extension found in the Corridor Entity Query:
Clicking on the ‘…’ button in this field will bring up the Edit Shape Geometry Sort Order Options dialog:
This dialog allows you to determine the sort order (clockwise, counter-clockwise, or ‘as-defined’), the starting point location (upper/lower + inside/outside/right-most/left-most, or ‘original’), and a horizontal tolerance for determine which points to consider when looking at the horizontal option for selecting a starting point. For example:
Corridor sections contain several collections which represent different ‘views’ of the points, links, and shapes which make up each individual section:
The generic collections (‘Points’, ‘Links’, and ‘Shapes’) expose each individual entity as a separate data object in the report. Because of this these collections are not particularly useful for most production oriented reports, but are very good for corridor section analysis and quality control for subassembly developers, support personnel, etc.
The most common collections to use are the ‘ByCode’ collections. These collections group the section entities based on code, and expose aggregate entities which contain properties determined from all similar section entities in the group as a whole. These entities expose ‘incremental’ and ‘cumulative’ calculated fields for quantity determinations. For example, the ‘ShapesByCode’ entity exposes ‘AverageArea’, ‘IncrementalVolume’ (from previous station), and ‘CumulativeVolume’ (from the start of the current region):
The ‘LinksByCode’ and ‘PointsByCode’ entities contain similar calculated properties, thus allowing both linear and areal quantities to be calculated for links, and both item count and linear (longitudinal – think ‘feature lines’) quantities to be calculated for points.
The ‘AggregatedSectionPoints’ and ‘AggregatedSectionLinks’ are special collections which aggregate entities on either side of the baseline with a maximum number of entities per data row. These are useful for producing slope stake reports (such as the CalTrans slope stake report) of the form:
Within a given data row, the specific entity being referenced must be indexed using an integer argument (e.g. ‘\int’ or ‘\int[-1]). Use an index of ‘0’ for the centerline or baseline, a positive number for the right side, and a negative number for the left side.
You can specify the maximum number of entities on each side via a query extension.
Another set of special collections is included under the ‘Baseline’ entity:
These entities are almost identical to the ‘ByCode’ entities found in the ‘Sections’ entity, except that they include data for ALL sections in all regions on a given baseline. The station and region index are provided as fields. This allows you do things such as group data by code, and show quantities for each station for the entity with the current code:
Calculating Material Volumes
Corridor material volumes are handled a little differently than what many AutoCAD Civil 3D users are used to by Visual Report Designer. The basic concepts are substantially similar, however, Visual Report Designer breaks from the AutoCAD Civil 3D model in several ways, including:
- No sample lines are needed – data are sampled directly from the corridor model
- Surface data may be sampled at the same time as the corridor data and if sampled, is automatically added together with the section data as additional ‘links’ thus allowing seamlessly combined structural and earthwork quantities
- An material classification table (a text file which closely matches the format of the CAiCE earthwork classification tables – the basic format is identical except for an added ‘Style’ column) is used to define the relationships between various materials and the links which bound the areas in the sections representing these materials (a similar concept already exists in AutoCAD Civil 3D but it relies upon corridor surfaces, not links) – resolved areas are treated the same as and are merged together with section shapes for volume calculations.
- A code map file is provided which can relate generic surface names to specific codes for use with the earthwork table.
Material Classification Tables
The table below (and its XML form, also below) define two materials based on relationships with two sets of links (by code):
- EXIST and DATUM are surface or link-code designations (names)
- CUT and FILL are material designations (names)
The table is interpreted as follows:
- Any material BELOW surface EXIST and ABOVE surface DATUM is defined as CUT material,
and it’s a “C” or cut type material with a shrink/swell factor of 1.0; it’s style is “Cut_Material”
- Any material ABOVE surface EXIST and BELOW surface DATUM is defined as FILL material,
and it’s a “F” or fill type material with a shrink/swell factor of 1.0; it’s style is “Fill_Material”
TIP: The ASCII form of the Material Classification Table is compatible with the Earthwork Tables used in CAiCE.
Code mapping is primarily used to convert surface codes (but also regular link codes) to a final code to be used by the Material Classification Table. It uses regular expressions ( http://www.regular-expressions.info/ ) to match codes currently assigned to links and a ‘CodeFormat’ to specify the format of the final code to be used for calculations, imaging, etc.
In its simplest form, the code mapping is applied as shown in the following diagram:
Specifying Material Classification and Code Map Files
The Material Classification and Code Map files are specified as extensions of the Corridor Query:
In this Query Extension, you will also be able to specify the surfaces to be sampled (via the sub-query ‘SurfaceQuery’), and the filters to be applied to the corridor links and shapes which will be considered in the volume calculations.
The filters use a wildcard based matching pattern as do most patterns/filters exposed via the user interface (as opposed to the regular expressions used in the code map file). This is because the query extensions are exposed to the end user of a report and are likely to be modified, thus they should be easy to modify; the code map file on the other hand is configured by a cad manager or consultant and it typically left alone once complete, therefore the additional complexity of a regular expression is justified in order to gain the additional functionality offered by regular expressions. To exclude all entities of a given type from the calculations, enter a value of ‘<None>’ in the appropriate field.
Calculating Pay Items
Pay items may be calculated using a price per unit table (CSV) for certain entities (Cross section points, links, and shapes from the ‘ByCodes’ collections) based on entity type, code, and optionally quantity. This is accomplished using a simple reference label control (bound to a property supporting this feature) in which you specify the full path and filename to the CSV file as a ‘Filename Argument’, and optionally the name of the field containing the quantity value as a ‘Field Name Argument’ (delimited with a ‘pipe’ (‘|’) character). More information on Argumented Properties (including a list of argument types/valid escape sequences, can be found here). For example, an argument value might look something like:
Note that if a 2 column table is used, specifying the field to measure the quantity from will have no effect on the output as the 2-column table ignores quantity; it will, however, slow down the processing of the report because the quantity field reference will still be evaluated.
The CSV files may be 2, 3, or 4 column:
<Code>,<Price Per Unit>
<Code>,<MaximumQtyAtPrice>,<Price Per Unit>
<Code>,<MinimumQtyAtPrice>,<MaximumQtyAtPrice>,<Price Per Unit>
Pricing for a 2-column table is determined based solely on code. In this table, each code must be unique.
For a 3-column table, if the actual quantity is less than the specified maximum for the range AND the code matches, the range with the lowest maximum quantity will be used. Codes are not required to be unique, nor are the lines required to be in any particular order. For example, if our pricing table looks like this:
The price per unit resulting from a query based on code ASPH for the quantity 455 units would be 255.0 because this quantity falls in the range between 100 and 500, therefore the line with the maximum quantity of 500 applies. Note that the ‘maximum’ value of the last range for each code should be sufficiently large that a reasonable quantity will not exceed the maximum specified (example: make the maximum quantity on the last range of each code 9999999 or so).
The 4-column table is similar except that it also includes a minimum value column. The maximum value for one range of a given code should correspond to the minimum value of the subsequent range (the lines are not required to be in order, but it is recommended that you keep them well ordered/organized). If a query is made, the quantity is evaluated against all ranges specified for that code to find a match. If no match is found, a value of ‘0’ is returned. If the ranges are not contiguous for a given code, it is possible a value may fall between and return a price of 0, thus the requirement that the minimums and maximums of adjacent ranges of quantities for a given code align.