0% found this document useful (0 votes)

440 views

Civil 3 D Developers Guide

Uploaded by

ELGRANDE

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

440 views

Civil 3 D Developers Guide

Uploaded by

ELGRANDE

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 254

AutoCAD Civil 3D 2009

Developers Guide

April 2008

2008 Autodesk, Inc. All Rights Reserved. Except as otherwise permitted by Autodesk, Inc., this publication, or parts thereof, may not be reproduced in any form, by any method, for any purpose. Certain materials included in this publication are reprinted with the permission of the copyright holder.

Trademarks The following are registered trademarks or trademarks of Autodesk, Inc., in the USA and other countries: 3DEC (design/logo), 3December, 3December.com, 3ds Max, ActiveShapes, Actrix, ADI, Alias, Alias (swirl design/logo), AliasStudio, Alias|Wavefront (design/logo), ATC, AUGI, AutoCAD, AutoCAD Learning Assistance, AutoCAD LT, AutoCAD Simulator, AutoCAD SQL Extension, AutoCAD SQL Interface, Autodesk, Autodesk Envision, Autodesk Insight, Autodesk Intent, Autodesk Inventor, Autodesk Map, Autodesk MapGuide, Autodesk Streamline, AutoLISP, AutoSnap, AutoSketch, AutoTrack, Backdraft, Built with ObjectARX (logo), Burn, Buzzsaw, CAiCE, Can You Imagine, Character Studio, Cinestream, Civil 3D, Cleaner, Cleaner Central, ClearScale, Colour Warper, Combustion, Communication Specification, Constructware, Content Explorer, Create>what's>Next> (design/logo), Dancing Baby (image), DesignCenter, Design Doctor, Designer's Toolkit, DesignKids, DesignProf, DesignServer, DesignStudio, Design|Studio (design/logo), Design Your World, Design Your World (design/logo), DWF, DWG, DWG (logo), DWG TrueConvert, DWG TrueView, DXF, EditDV, Education by Design, Exposure, Extending the Design Team, FBX, Filmbox, FMDesktop, Freewheel, GDX Driver, Gmax, Heads-up Design, Heidi, HOOPS, HumanIK, i-drop, iMOUT, Incinerator, IntroDV, Inventor, Inventor LT, Kaydara, Kaydara (design/logo), LocationLogic, Lustre, Maya, Mechanical Desktop, MotionBuilder, Mudbox, NavisWorks, ObjectARX, ObjectDBX, Open Reality, Opticore, Opticore Opus, PolarSnap, PortfolioWall, Powered with Autodesk Technology, Productstream, ProjectPoint, ProMaterials, Reactor, RealDWG, Real-time Roto, Recognize, Render Queue, Reveal, Revit, Showcase, ShowMotion, SketchBook, SteeringWheels, StudioTools, Topobase, Toxik, ViewCube, Visual, Visual Bridge, Visual Construction, Visual Drainage, Visual Hydro, Visual Landscape, Visual Roads, Visual Survey, Visual Syllabus, Visual Toolbox, Visual Tugboat, Visual LISP, Voice Reality, Volo, Wiretap, and WiretapCentral The following are registered trademarks or trademarks of Autodesk Canada Co. in the USA and/or Canada and other countries: Backburner, Discreet, Fire, Flame, Flint, Frost, Inferno, Multi-Master Editing, River, Smoke, Sparks, Stone, and Wire All other brand names, product names or trademarks belong to their respective holders. Disclaimer THIS PUBLICATION AND THE INFORMATION CONTAINED HEREIN IS MADE AVAILABLE BY AUTODESK, INC. "AS IS." AUTODESK, INC. DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE REGARDING THESE MATERIALS. Published By: Autodesk, Inc. 111 Mclnnis Parkway San Rafael, CA 94903, USA

Contents

About the Developer's Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Intended Audience . . . . . . . . . . . . . Organization . . . . . . . . . . . . . . . . Using VBA in AutoCAD Civil 3D . . . . . . New Features and Differences . . . . . . . . General . . . . . . . . . . . . . . . . Alignments . . . . . . . . . . . . . . Styles . . . . . . . . . . . . . . . . . Surfaces . . . . . . . . . . . . . . . . Labels . . . . . . . . . . . . . . . . . Pipes . . . . . . . . . . . . . . . . . . Migrating Existing Code to Civil 3D 2009 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 .1 .3 .3 .3 .4 .5 .5 .5 .6 .6

Chapter 1

Root Objects and Common Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Root Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Accessing Application and Document Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Using Collections Within the Document Object . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Accessing and Using the Database Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Ambient Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Changing General and Specific Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Label Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Creating a Label Style Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Defining a Label Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Using Property Fields in Label Style Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Sharing Syles Between Drawings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Chapter 2

Survey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

iii

Root Objects . . . . . . . . . . . . . . . . . . . . . Obtaining Survey-Specific Root Objects . . . . Changing Survey-Specific Ambient Settings . Changing Survey User Settings . . . . . . . . Using the Equipment Database . . . . . . . . Creating a Survey Project . . . . . . . . . . . Adjusting Survey Project Settings . . . . . . . Accessing Extended Properties . . . . . . . . . Survey Network . . . . . . . . . . . . . . . . . . . Creating a Survey Network . . . . . . . . . . Adding Control Points to a Network . . . . . Adding Directions to a Network . . . . . . . . Adding Setups to a Network . . . . . . . . . . Adding Non-control Points to a Network . . . Creating Paths for Traverse Analysis . . . . . . Adding Survey Data to the Drawing . . . . . . Getting Survey Network Drawing Objects . . Figures . . . . . . . . . . . . . . . . . . . . . . . . Creating a Figure Object . . . . . . . . . . . . Adding Lines to a Figure . . . . . . . . . . . . Adding Arcs to a Figure . . . . . . . . . . . . Adding Figures to the Drawing . . . . . . . . Figures and AutoCAD Civil 3D . . . . . . . . Creating a Figure Style . . . . . . . . . . . . . Using the Figure Prefix Database . . . . . . . Sample Program . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . .

. 18 . 18 . 19 . 19 . 20 . 21 . 22 . 22 . 22 . 23 . 23 . 23 . 24 . 25 . 26 . 26 . 27 . 27 . 27 . 27 . 28 . 28 . 28 . 29 . 30 . 31

Chapter 3

Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Points Collection . . . . . . . . . . . . . . Accessing Points in a File . . . . . . . . . . . . . . . Using Points . . . . . . . . . . . . . . . . . . . . . . Point User-Defined Properties . . . . . . . . . . . . . Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Point Styles . . . . . . . . . . . . . . . . . . Creating Point Label Styles . . . . . . . . . . . . . . Using Point Description Keys . . . . . . . . . . . . . Point Groups . . . . . . . . . . . . . . . . . . . . . . . . . Creating Point Groups . . . . . . . . . . . . . . . . . Adding Points to a Point Group Using QueryBuilder . Using Point Groups . . . . . . . . . . . . . . . . . . Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 . 33 . 33 . 34 . 35 . 36 . 36 . 37 . 37 . 38 . 39 . 39 . 40 . 41 . 41

Chapter 4

Surfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Object Hierarchy . . . . . . . . . . . . . . . . . . . Using the Surfaces Collection . . . . . . . . . . . . Creating a Surface . . . . . . . . . . . . . . . . . . Creating a Surface From a LandXML File . . . Creating a TIN Surface . . . . . . . . . . . . . Creating a Grid Surface . . . . . . . . . . . . Creating a Volume Surface . . . . . . . . . . . Working with Surfaces . . . . . . . . . . . . . . . . Adding a Boundary . . . . . . . . . . . . . . Adding Data from DEM Files . . . . . . . . . Improving Performance By Using Snapshots . Finding Intersections . . . . . . . . . . . . . Working with TIN Surfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 . 44 . 44 . 44 . 45 . 45 . 46 . 47 . 47 . 49 . 49 . 49 . 50

iv | Contents

Adding Point Data to a TIN Surface . . . . Adding Points Using Point Files . . . Adding Points Using Point Groups . Adding a Breakline to a TIN Surface . . . . Adding a Standard Breakline . . . . Adding a Proximity Breakline . . . . Adding a Non-destructive Breakline . Adding a Wall Breakline . . . . . . . Importing Breaklines from a File . . Adding Contours to a TIN Surface . . . . . Extracting Contours from a TIN Surface . Surface Style . . . . . . . . . . . . . . . . . . . Creating a Style . . . . . . . . . . . . . . Changing a Surface Style . . . . . . . . . Assigning a Style to a Surface . . . . . . . Performing Surface Analysis . . . . . . . . . . . Creating an Elevation Analysis . . . . . . Creating a Watershed Analysis . . . . . . Sample Programs . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . .

. 50 . 50 . 50 . 51 . 51 . 52 . 52 . 52 . 53 . 53 . 54 . 55 . 55 . 55 . 56 . 56 . 56 . 57 . 61

Chapter 5

Sites and Parcels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Object Hierarchy . . . . . . . . . . . . . . . . Sites . . . . . . . . . . . . . . . . . . . . . . Creating Sites . . . . . . . . . . . . . . Using Sites . . . . . . . . . . . . . . . . Parcels . . . . . . . . . . . . . . . . . . . . . Creating Parcels with Parcel Segments . About Parcel Segments . . . . . . . . . . Determining Parcel Loops . . . . . . . . Parcel Style and Parcel Segment Style . . Parcel Label Style . . . . . . . . . . . . . Parcel User-Defined Properties . . . . . . Accessing Daylight Feature Lines . . . . Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 . 63 . 64 . 64 . 64 . 64 . 65 . 66 . 67 . 68 . 69 . 69 . 70

Chapter 6

Alignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Object Hierarchy . . . . . . . . . . . . . . . . . . Basic Alignment Operations . . . . . . . . . . . . Creating an Alignment . . . . . . . . . . . Defining an Alignment Path Using Entities . Determining Entities Within an Alignment . Stations . . . . . . . . . . . . . . . . . . . . . . . Modifying Stations with Station Equations . Creating Station Sets . . . . . . . . . . . . . Specifying Design Speeds . . . . . . . . . . Superelevation . . . . . . . . . . . . . . . . Alignment Style . . . . . . . . . . . . . . . . . . Creating an Alignment Style . . . . . . . . Alignment Label Styles . . . . . . . . . . . Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 . 72 . 72 . 74 . 74 . 75 . 75 . 76 . 76 . 77 . 78 . 78 . 79 . 80

Chapter 7

Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Object Hierarchy . . . . . . . . . . . . . . . Profiles . . . . . . . . . . . . . . . . . . . . Creating a Profile From a Surface . . . Creating a Profile Using Entities . . . . Editing Points of Vertical Intersection . Creating a Profile Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 . 82 . 83 . 83 . 84 . 85

Contents | v

Profile Views . . . . . . . . . . . . . . Creating a Profile View . . . . . Creating Profile View Styles . . . Setting Profile View Styles . . . . Setting the Axis Style . . . Setting the Graph Style . . Profile View Style Example Sample Programs . . . . . . . . . . . .

. . . . . . . .

. 85 . 86 . 86 . 86 . 86 . 87 . 88 . 89

Chapter 8

Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Sample Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Creating a Sample Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Defining Sample Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Creating Sample Line Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Creating Sample Line Label Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Creating Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Using Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Section Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Creating Section Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Creating Section View Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 Setting Section View Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Setting the Axis Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 Setting Graph Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Section View Style Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Chapter 9

Data

Bands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 . 107 . 108 . 110 . 112 . 114 . 116 . 119 . 121 . 121 . 121 . 122 . 122 . 123 . 123

Object Hierarchy . . . . . . . . . . . . . . . . . Defining a Data Band Style . . . . . . . . . . . . Data Band Concepts . . . . . . . . . . . . Profile Data Band Style . . . . . . . . . . . Horizontal Geometry Data Band Style . . . Vertical Geometry Data Band Style . . . . Superelevation Data Band Style . . . . . . Section Data Band Style . . . . . . . . . . Creating a Data Band Set . . . . . . . . . . . . . Creating Data Band Sets for Profile Views . Creating Data Band Sets for Section Views . Using Data Bands . . . . . . . . . . . . . . . . . Adding Data Bands to a Profile View . . . . Adding Data Bands to a Section View . . . Sample Programs . . . . . . . . . . . . . . . . .

Chapter 10

Pipe Networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Base Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Accessing Pipe Network-Specific Base Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Pipe-Specific Ambient Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Listing and Adding Dynamic Part Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 Retrieving the Parts List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 Creating a Pipe Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Pipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Creating Pipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Using Pipes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Creating Pipe Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Creating Pipe Label Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

vi | Contents

Structures . . . . . . . . . . . . . . . . . Creating Structures . . . . . . . . . Using Structures . . . . . . . . . . Creating Structure Styles . . . . . . Creating Structure Label Styles . . . Interference Checks . . . . . . . . . . . Object Hierarchy . . . . . . . . . . Performing an Interference Check . Listing the Interferences . . . . . . Interference Check Styles . . . . . . Sample Program . . . . . . . . . . . . .

. . . . . . . . . . .

. 136 . 136 . 137 . 138 . 138 . 140 . 141 . 141 . 142 . 143 . 144

Chapter 11

Creating Custom Subassemblies Using .NET . . . . . . . . . . . . . . . . . . . . . . . . . 145

Overview . . . . . . . . . . . . . . . . . . . . . . . . . Subassembly Changes . . . . . . . . . . . . . . . . . . Designing Custom Subassemblies . . . . . . . . . . . . Naming Custom Subassemblies . . . . . . . . . . Attachment and Insertion Methodology . . . . . User-defined vs. Hard-coded Parameters . . . . . . Input Parameter Types . . . . . . . . . . . . . . . Superelevation Behavior and Subassemblies . . . . Creating Subassembly Help Files . . . . . . . . . . Structure of Subassembly Programs . . . . . . . . . . . The Subassembly Template (SATemplate.vb) . . . . The Corridor State Object . . . . . . . . . . . . . Support Files (CodesSpecific.vb, Utilities.vb) . . . Sample VB.NET Subassembly . . . . . . . . . . . . . . The Subassembly Tool Catalog . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . Creating a Tool Catalog ATC File . . . . . . . . . . Sample Tool Catalog ATC Files . . . . . . . . Tool Catalog Data Type Information . . . . . Creating a Tool Catalog Cover Page . . . . . . . . Creating a Tool Catalog Registry File . . . . . . . . Installing Custom Subassemblies . . . . . . . . . . . . . Exporting Custom Subassemblies Using a Package File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 . 145 . 147 . 147 . 147 . 148 . 148 . 149 . 150 . 153 . 153 . 153 . 154 . 156 . 166 . 166 . 167 . 167 . 174 . 176 . 176 . 177 . 178

Chapter 12

Corridors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Root Objects . . . . . . . . . . . . . . . . . . . . . . Object Hierarchy . . . . . . . . . . . . . . . . . Accessing Corridor-Specific Base Objects . . . . Ambient Settings . . . . . . . . . . . . . . . . . Corridors . . . . . . . . . . . . . . . . . . . . . . . . Corridor Concepts . . . . . . . . . . . . . . . . Listing Corridors . . . . . . . . . . . . . . . . . Creating Corridors . . . . . . . . . . . . . . . . Baselines . . . . . . . . . . . . . . . . . . . . . . . . Object Hierarchy . . . . . . . . . . . . . . . . . Listing Baselines in a Corridor . . . . . . . . . . Adding a Baseline to a Corridor . . . . . . . . . Listing Baseline Regions . . . . . . . . . . . . . Accessing and Modifying Baseline Stations . . . Listing Offset Baselines . . . . . . . . . . . . . . Assemblies and Subassemblies . . . . . . . . . . . . . Object Hierarchy . . . . . . . . . . . . . . . . . Listing Applied Assemblies in a Baseline Region . Getting Applied Subassembly Information . . . Feature Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 . 182 . 182 . 183 . 186 . 186 . 186 . 187 . 187 . 188 . 188 . 188 . 188 . 189 . 189 . 190 . 191 . 191 . 192 . 193

Contents | vii

Object Hierarchy . . . . . . . . . . . . . . . Listing Feature Lines Along a Baseline . . . . Listing Feature Lines Along Offset Baselines . Corridor Surfaces . . . . . . . . . . . . . . . . . . Object Hierarchy . . . . . . . . . . . . . . . Listing Corridor Surfaces . . . . . . . . . . . Listing Surface Boundaries . . . . . . . . . . Computing Cut and Fill . . . . . . . . . . . Styles . . . . . . . . . . . . . . . . . . . . . . . . Assembly Style . . . . . . . . . . . . . . . . Link Style . . . . . . . . . . . . . . . . . . . Shape Style . . . . . . . . . . . . . . . . . . Roadway Style Sets . . . . . . . . . . . . . . Sample Program . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. 193 . 193 . 194 . 195 . 195 . 196 . 196 . 197 . 198 . 198 . 199 . 199 . 199 . 200

Appendix A Object

Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

AutoCAD Civil 3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Appendix B Creating Custom Subassemblies with VBA . . . . . . . . . . . . . . . . . . . . . . . . . . 207

Designing Custom Subassemblies . . . . . . . . . Naming Custom Subassemblies . . . . . . . Attachment and Insertion Methodology . . User Defined vs. Hard-Coded Parameters . . Input Parameter Types . . . . . . . . . . . . Superelevation Behavior and Subassemblies . Creating Subassembly Help Files . . . . . . . COM Objects for Subassemblies . . . . . . . . . . VBA Structure for Subassemblies . . . . . . . . . . Defining Point, Link, and Shape Codes . . . . . . Sample Subassembly VBA Script . . . . . . . . . . Creating a Subassembly Tool Catalog . . . . . . . Sample Tool Catalog Registry File . . . . . . . . . Sample Tool Catalog ATC File . . . . . . . . . . . Data Type Information . . . . . . . . . . . . . . . Creating a Tool Catalog Cover Page . . . . . . . . Installing Custom Subassemblies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 . 207 . 207 . 208 . 208 . 209 . 210 . 213 . 213 . 214 . 215 . 227 . 228 . 229 . 237 . 239 . 239

Appendix C Creating Client Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

viii | Contents

About the Developer's Guide

Intended Audience
The AutoCAD Civil 3D API Developers Guide is designed for developers who want to customize AutoCAD Civil 3D or create applications using the underlying API. It can also be used for creating macros to automate repetitive tasks for AutoCAD Civil 3D users and for developers of custom subassemblies.

Organization
This guide is organized by the major features of AutoCAD Civil 3D. It consists of the following chapters, each of which includes samples taken from one or more demonstration programs:

Chapter 1: Root Objects and Common Concepts (page 9)

Explains how to obtain the base objects representing the documents and databases, which are required for all subsequent chapters. Also discussed are objects common to many features, such as ambient settings and label styles.

Chapter 2: Survey (page 17)

Covers the creation and manipulation of survey networks, including control points, directions, set-ups, and non-control points. Also covers the equipment database, traverses, and figures.

Chapter 3: Points (page 33)

Covers the creation and uses of points, including point groups.

Chapter 4: Surfaces (page 43)

Covers the creation and manipulation of surfaces. Covers TIN, grid, and volume surfaces, and explains how to import surfaces from files, manipulate point data directly, insert breaklines, manage borders, modify contours, and analyze elevation and watershed information.

Chapter 5: Sites and Parcels (page 63)

Discusses the uses of sites and the creation of profiles using profile segments.

Chapter 6: Alignments (page 71)

Describes how to create alignments through layout functions, from polyline entities, or based on an offset from existing alignments. Includes discussion of stations, speeds, and superelevation.

Chapter 7: Profiles (page 81)

Covers the creation of profiles and profile views, including profiles based on surfaces and profiles created with entities.

Chapter 8: Sections (page 91)

Covers the creation of alignment cross sections and their display in section views.

Chapter 9: Data Bands (page 107)

Explains how to design data bands for profile views and section views.

Chapter 10: Pipe Networks (page 125)

Covers the creation of pipes, structures, and pipe networks, including interference detection.

Chapter 11: Corridors (page 181)

Discusses how to modify and gather information about existing corridors, baselines, feature lines, assemblies and subassemblies in a document.

Chapter 12: Creating Custom Subassemblies Using .NET (page 145)

Covers the preferred method for creating and installing of custom subassemblies using Visual Basic .NET and the creation of catalog files which enables users to access custom subassemblies. This is the currently supported method, although you can also create subassemblies using VBA (see the Appendix Creating Custom Subassemblies with VBA (page 207) for more information).

Appendix A: Object Hierarchy (page 201)

Displays the hierarchy of all major objects. This is useful for determining which class instances are required to create an object of a particular type, or which objects can be accessed from an existing instance.

Appendix B: Creating Custom Subassemblies with VBA (page 207)

Describes the legacy method for creating and installing custom subassemblies using Visual Basic for Applications (VBA). This method is described for backwards-compatibility with older custom subassemblies.

Appendix C: Creating Client Applications (page 241)

Covers the creation of applications that utilize AutoCAD Civil 3D. Samples in Visual Basic.NET, C++, and C#.

2 | Part 1 About the Developer's Guide

Using VBA in AutoCAD Civil 3D

The following AutoCAD Civil 3D command-line instructions enable you to interact with the Visual Basic programming environment and with loaded VBA macros:

VBAMAN - Displays a dialog box allowing you to load, unload, edit, embed, extract, edit, and save copies of VBA applications. VBAIDE - Displays the Visual Basic programming environment. VBARUN - Allows you to select which macro to run from a dialog box displaying all available subroutines in all loaded modules. -VBARUN <module.macro> - Runs a particular macro from the command line. VBALOAD - Loads a global VBA project into the current work session. After entering this instruction, you are presented with a file selection dialog box. -VBALOAD <full path and filename> - Loads a particular project from the command line. If the path contains spaces, you need to type quotes around the path and filename string. VBAUNLOAD - Unloads an existing VBA project. After entering this instruction, you are prompted to type in the full path and filename of the project. If the path contains spaces, you need to type quotes around the path and filename string. VBASTMT - Executes a VBA statement on the command line. A statement generally occupies a single line, although you can use a colon (:) to include more than one statement on a line. VBA statements are executed in the context of the current drawing.

VBA projects are usually stored in separate .dvb files, which allow macros to interact with many separate AutoCAD Civil 3D drawings.

New Features and Differences

General
Criteria-Based Design changes
Several API changes allow access to the Criteria-Based design feature. For Alignments:

You can now specify whether an Alignment uses a design criteria file (AeccAlignment::UseDesignCriteriaFile property) and design check set (AeccAlignment::UseDesignCheckSet property). Design Speed: Alignments now have a DesignSpeeds collection. Minimum Transition Length: AeccAlignmentSpiral now has a MinimumTransitionLength property, which contains the minimum transition length according to the design speed check. Minimum Radius: AeccAlignmentArc now has a MinimumRadius property, which contains the minimum radius according to the design speed check. You can now access the collection of design checks with the AeccAlignmentCurve::DesignChecks property.

Using VBA in AutoCAD Civil 3D | 3

For Profiles:

You can now specify whether a Profile uses a design criteria file, using the
AeccProfile::UseDesignCriteriaFile property.

You can now access the collection of design checks with the AeccProfileCurve::DesignChecks property. Profiles now have properties for the minimum K value for stopping, headlight, and stopping sight distances. These properties are in IAeccProfileCurve, IAeccProfileCurveAsymmetric, IAeccProfileCurveCircular, IAeccProfileCurveParabolic , and their PVI counterparts.

Custom Subassemblies

You can now share custom subassemblies by creating a subassembly package file. See Exporting Custom Subassemblies Using a Package File (page 178). Subassemblies can now target objects other than profiles and alignments, and this affects how custom subassemblies are written. See Subassembly Changes (page 145).

Other Changes

The feature lines for grading objects are now exposed. Command Settings: there are over 200 new AeccSettings* objects, which expose the settings for many command-line commands. You can now access user-defined attributes, using the AeccUserDefinedProperties object. The AeccMaterialSection object now supports volume calculations. You can now access the background mask property of text components, using the new
AeccLabelStyleTextComponentBorder::BackgroundMask property.

You can now write to the AeccPoint::Number property. You can now add events to the Event Viewer using the AeccDatabase::AddEvent() method. The framework for defining display representation styles for profile, plan, model, and section views has changed. Many objects have new *DisplayStyleModel/Plan/Profile/Section properties, and some enumerations in the AeccXPipeLib library have changed. See Migrating Existing Code to Civil 3D 2009 (page 6) for details on how to migrate existing code.

Alignments
Curve Types
Complex curve types are now accessible via the API. The new objects representing these types are:

Spiral-Spiral: AeccAlignmentSSGroup Spiral-Spiral-Curve: AeccAlignmentSSCGroup Curve-Spiral-Spiral: AeccAlignmentCSSGroup Spiral-Curve-Spiral-Curve-Spiral: AeccAlignmentSCSCSGroup Spiral-Curve-Spiral-Spiral-Curve-Spiral: AeccAlignmentSCSSCSGroup

4 | Part 1 About the Developer's Guide

Station Subentities
You can now get the subentity at a given station. The AeccAlignmentEntity object now has a SubEntity() method, which allows you to access the subentities by index.

Styles
Style changes

New objects for view frame styles and style groups, and match line styles: AeccViewFrameStyle,
AeccViewFrameStyles and AeccMatchLineStyle.

The abbreviations for drawing settings are now exposed with the AeccSettingsAbbreviation object. You can now export styles to another drawing, using the AeccStyle::ExportTo() method. The CreatedBy property for various style objects is now read/write. Alignment marker styles are now exposed with the AeccAlignmentStyle object.

Surfaces
Surface Intersection
You can now find the intersection point between the specified vector and the surface with the AeccSurface::IntersectPointWithSurface() method.

Extract Boundary
You can now extract a surfaces border and contours as AutoCAD objects, using the new AeccSurface::ExtractBorder() and AeccSurface::ExtractContour methods.

Sampled Surface Entities

You can now access objects other than sufaces in the AeccSampledSurfaces collection with the new AeccSampledSurface.AcadEntity property.

Labels
NoteLabels
The AeccDocument object now has a NoteLabels property.

Station offset labels

You can now create and modify station offset labels with the new AeccAlignmentLabels object and IAeccAlignmentLabels::AddStationOffsetLabel() method.

Styles | 5

Pipes
Network parts
You can now use the new AeccGraphProfileNetworkPart::GetModelNetworkPart() method to get the original model network part.

Part Family
You can now get the part family that a particular pipe comes from, using the AeccPipeNetworkPart::PartFamily property.

Adding Part Lists

The AeccPartLists object now has an Add() method.

Migrating Existing Code to Civil 3D 2009

Some changes to the API may break existing code written for previous versions of AutoCAD Civil 3D, and will require changes before it will run with this release. Other changes wont break existing code, but should be updated to be made explicit.

Updating References
The AecX*.tlb libraries have moved to C:/Program Files/Common Files/Autodesk Shared and now contain the version number in the file name, so applications that reference them (such as VC++ applications) need to point to the new location and file name. For example:
#import "C:/Program Files/AutoCAD Civil 3D 2008/AecXBase.tlb" raw_interfaces_only named_guids no_namespace #import "C:/Program Files/AutoCAD Civil 3D 2008/AecXUIBase.tlb" raw_interfaces_only named_guids no_namespace

is now:
#import "C:/Program Files/Common Files/Autodesk Shared/AecXBase57.tlb" raw_interfaces_only named_guids no_namespace #import "C:/Program Files/Common Files/Autodesk Shared/AecXUIBase57.tlb" raw_interfaces_only named_guids no_namespace

Existing VBA projects need to reference the updated Autodesk Civil Engineering Land 6.0 Object Library, Autodesk Civil Engineering UI Land 6.0 Object Library, and any of the Survey, Roadway, and Pipe libraries required, instead of the 5.0 versions. Where the VBA application gets the AcadApplication object, it needs to be updated to reference the 6.0 library version:
Dim oApp As AcadApplication Set oApp = ThisDrawing.Application ' NOTE - Always specify the version number. Const sAppName = "AeccXUiLand.AeccApplication.6.0" Set g_oCivilApp = oApp.GetInterfaceObject(sAppName)

6 | Part 1 About the Developer's Guide

AeccXPipeLib Enumerations
Four enumerations are changed in the Pipes library to reflect the new display representation framework. These are:
AeccPipeDisplayComponents AeccPipeHatchComponents AeccStructureDisplayComponents AeccStructureHatchComponents

Now these enumerations no longer refer to a display view; rather, you pass them to a DisplayStyle*() method for the display view you want to set (plan, model, section, or profile). In general, calls to DisplayStyle2d() should be changed to DisplayStylePlan(), (except where they apply to profile or section styles), while DisplayStyle3d() should be changed to DisplayStyleModel(). For example: 2008:
' Modify the colors of pipes using this style, as shown in ' plan view. oPipeStyle.DisplayStyle2d(aeccDispCompPlanPipeOutsideWall).color = 40 ' orange oPipeStyle.DisplayStyle2d(aeccDispCompPlanPipeInsideWall).color = 255 ' white oPipeStyle.DisplayStyle2d(aeccDispCompPlanPipeEndLine).color = 255 ' white

2009:
' Modify the colors of pipes using this style, as shown in ' plan view. oPipeStyle.DisplayStylePlan(aeccDispCompPipeOutsideWalls).color = 40 ' orange oPipeStyle.DisplayStylePlan(aeccDispCompPipeInsideWalls).color = 255 ' white oPipeStyle.DisplayStylePlan(aeccDispCompPipeEndLine).color = 255 ' white

Other Display Representation Changes

In addition to the changes in the AeccXPipeLib, display style methods in all libraries have been changed from *DisplayStyle2D() to *DisplayStylePlan(), *DisplayStyleSection(), and *DisplayStyleProfile(). The *DisplayStyle3d() calls are now *DisplayStyleModel(). This reflects the change in display styles in the user interface. This change doesnt break existing code, as all *DisplayStyle2D() and *DisplayStyle3d() calls are mapped to the appropriate new methods. However, you should consider updating these calls for clarity.

Changed APIs
AeccProfiles::Add() no longer takes SampleStart, SampleEnd, and LayerName parameters.

Several obsolete properties have been removed from the AeccSheetStyle object:
PageMarginTop PageMarginBottom PageMarginLeft PageMarginRight MajorHorizontalGridSize MinorHorizontalGridSize

Migrating Existing Code to Civil 3D 2009 | 7

MajorVerticalGridSize MinorVerticalGridSize

8 | Part 1 About the Developer's Guide

Root Objects and Common Concepts

Root Objects
This section explains how to acquire references to the base objects which are required for all applications using this API. It also explains the uses of the application, document, and database objects and how to use collections, which are commonly used throughout the API.

Object Hierarchy

Root Object Model

Accessing Application and Document Objects

The root object in the AutoCAD Civil 3D COM hierarchy is the AeccApplication object. It contains information about the main application window, base AutoCAD objects, and a collection of all open documents. AeccApplication is inherited from the AutoCAD object AcadApplication. See the AutoCAD ObjectARX documentation for information about all inherited methods and properties.

The AeccApplication object is accessed by first using the exposed ThisDrawing object, an AutoCAD object of type AcadDocument. Its AcadDocument.Application property returns the AutoCAD AcadApplication object. From this point, use COM Automation to get the desired AutoCAD Civil 3D AeccApplication object. This example demonstrates the process of accessing the AeccApplication and AeccDocument objects:
Dim oAcadApp As AcadApplication Set oAcadApp = ThisDrawing.Application ' Specify the COM name of the object we want to access. ' Note that this always accesses the most recent version ' of Civil 3D installed. Const sCivilAppName = "AeccXUiLand.AeccApplication.6.0" Dim oCivilApp As AeccApplication Set oCivilApp = oAcadApp.GetInterfaceObject(sCivilAppName) ' Now we can use the AeccApplication object. ' Get the AeccDocument representing the currently ' active drawing. Dim oDocument As AeccDocument Set oDocument = oCivilApp.ActiveDocument ' Set the viewport of the current drawing so that all ' drawing elements are visible. oCivilApp.ZoomExtents

This sample gets the objects from AutoCAD Civil 3D 2009. To gain access to the libraries of an older version, use the version number of the desired libraries to the COM object name. For example, to make a program that works with AutoCAD Civil 3D 2007, replace:
Const sCivilAppName = "AeccXUiLand.AeccApplication.4.0"

with the following line of code:

Const sCivilAppName = "AeccXUiLand.AeccApplication.6.0"

The application object contains references to all open documents in the AeccApplication.Documents collection and the AeccApplication.ActiveDocument property. AeccDocument is inherited from the AutoCAD object AcadDocument. See the AutoCAD ObjectARX documentation for information on all inherited methods and properties.

Using Collections Within the Document Object

The document object not only contains collections of all AutoCAD Civil 3D drawing elements (such as surfaces and alignments) but all objects that modify those elements (such as styles and label styles). These collections have the same core set of methods: Count, Item, Remove, and Add. Count represents the number of items in the collection. Item returns an object from the collection, usually specified by the identification number or the name for the object. Remove deletes a specified item from the collection. Add creates a new item, adds it to the collection, and returns a reference to the newly created item. This item is already set with default values as defined by the document ambient settings. This example creates a new point style:

10 | Chapter 1 Root Objects and Common Concepts

Dim oPointStyle As AeccPointStyle Set oPointStyle = oAeccDocument.PointStyles.Add("Name") ' Now a new point style is added to the collection of styles, ' and we can modify it by setting the properties ' of the oPointStyle object. oPointStyle.Elevation = 114.6

If you attempt to add a new element with properties that match an already existing element, try to access an item that does not exist, or remove an item that does not exist or is in use, an error will result. You should trap the error and respond accordingly. The following sample demonstrates one method of dealing with such errors:
' Try to access the style named "Name". Dim oPointStyle As AeccPointStyle On Error Resume Next Set oPointStyle = oAeccDocument.PointStyles.Item("Name") ' Turn off error handling as soon as we no longer need it. On Error Goto 0 ' If there was a problem retrieving the item, then ' the oPointStyle object will remain empty. Check if that ' is the case. If so, it is most likely because the item ' does not exist. Try making a new one. If (oPointStyle Is Nothing) Then Set oPointStyle = oAeccDocument.PointStyles.Add("Name") End If

Accessing and Using the Database Object

Each document has an associated database object of type AeccDatabase that is accessed through the AeccDocument.Database property. The database object is inherited from the AutoCAD ObjectARX object AcadDatabase. The AeccDatabase object contains references to all the same AutoCAD Civil 3D entities as the AeccDocument object. However, it is the only object that contains references to base AutoCAD entities. See the AutoCAD ObjectARX documentation for more information.
' Add a polyline to the drawing's collection of objects. Dim oPolyline As AcadPolyline Dim dPoints(0 To 8) As Double dPoints(0) = 1000: dPoints(1) = 1000: dPoints(2) = 0 dPoints(3) = 1000: dPoints(4) = 4000: dPoints(5) = 0 dPoints(6) = 4000: dPoints(7) = 4000: dPoints(8) = 0 ' The database is where all such objects are stored. Set oPolyline = oDocument.Database.ModelSpace.AddPolyline(dPoints) oPolyline.Closed = True

The AeccDatabase object also has an AddEvent() method, that lets you send an event to the Event Viewer in the AutoCAD Civil 3D user interface:
Dim oAeccApp As AeccApplication Set oAeccApp = ThisDrawing.Application.GetInterfaceObject("AeccXUiLand.AeccApplication.6.0") oAeccApp.Init ThisDrawing.Application Dim oDatabase As AeccDatabase Set oDatabase = oAeccApp.ActiveDocument.Database oDatabase.AddEvent aeccEventMessageError, "PipeLengthRule", "Parameter Bad"

Accessing and Using the Database Object | 11

Ambient Settings
This section explains the purpose and use of the document settings objects, and covers changing general and specific settings.

Object Hierarchy

Ambient Settings Object Model

Changing General and Specific Settings

Ambient settings are default properties and styles that apply to the drawing as a whole or to objects when they are first created. The documents settings are accessed through the properties of the AeccSettingsRoot object, which is obtained from the AeccDocument.Settings property. There are settings for objects and commands. The object properties define the settings for items in general, or of particular classes of items, such as alignments, gradings, parcels, points, profiles, profile views, sample lines, sections, section views, and surfaces. Although each of these objects are unique, they all share some common features: Property Name
StyleSettings

Description
Specifies the default styles and label styles.

12 | Chapter 1 Root Objects and Common Concepts

Property Name
LabelStyleDefaults

Description
Specifies the common attributes for labels. Specifies the standard pattern of names. Specifies which units of measurement are used and displayed. Not on all objects. Optional. Specifies item-specific default values.

NameTemplate

AmbientSettings

CreationSettings

The command settings apply to commands, and correspond to the settings in the Commands folder for each item in the AutoCAD Civil 3D Toolspace Settings Tab. The following sample determines what angle units are used for all displays related to points:
Dim Set Dim Set Dim Set oPointSettings as AeccSettingsPoint oPointSettings = oDocument.Settings.PointSettings oAmbientSettings as AeccSettingsAmbient oAmbientSettings = oPointSettings.AmbientSettings oAngleUnit as AeccAngleUnitType oAngleUnit = oAmbientSettings.AngleSettings.Unit.Value

If (oAngleUnit = aeccAngleUnitDegree) Then ' Units are displayed in degrees ElseIf (oAngleUnit = aeccAngleUnitRadian) Then ' Units are displayed in radians Else ' Units are displayed in gradians End If

Label Styles
This section explains common features of label styles. It covers creating a new label style object, defining a label style, and using property fields in label style text strings. Details specific to each construct are covered in the appropriate chapters.

Label Styles | 13

Object Hierarchy

Label Style Object Model

Creating a Label Style Object

All types of annotation for AutoCAD Civil 3D elements are governed by label styles, which are objects of type AeccLabelStyle. A label style can include any number of text labels, tick marks, lines, markers, and direction arrows. The following example creates a new label style object that can be used with points:
Dim oLabelStyle As AeccLabelStyle Set oLabelStyle = oDocument.PointLabelStyles.Add _ ("New Label Style for Points")

Defining a Label Style

A label style consists of collections of different features of a label. The properties containing these collections are: AeccLabelStyle.BlockComponents for symbols, AeccLabelStyle.DirectionArrowComponents for direction arrows, AeccLabelStyle.LineComponents for lines, AeccLabelStyle.TextComponents for text, and AeccLabelStyle.TickComponents for both major and minor tick marks. Not all of these may have meaning depending on the label style type. For example, adding a tick mark component to a label style meant for a point has no visible effect. Label styles also depend on graphical objects that may or may not be part of the current document. For example, if the style references a block that is not part of the current document, then the specified block or tick components are not shown.

14 | Chapter 1 Root Objects and Common Concepts

To add a feature to a label style, add a new component to the corresponding collection. Then set the properties of that component to the appropriate values. Always make sure to set the Visible property to True.
' Add a line to the collection of lines in our label style. Dim oLabelStyleLineComponent As AeccLabelStyleLineComponent Set oLabelStyleLineComponent = oLabelStyle.LineComponents _ .Add("New Line") ' Now the line can be changed to suit our purpose. oLabelStyleLineComponent.Visibility = True oLabelStyleLineComponent.color = 40 ' orange-yellow oLabelStyleLineComponent.Angle = 2.094 ' radians, = 120 deg ' Negative lengths are allowed. They mean the line ' is drawn in the opposite direction of the angle ' specified. oLabelStyleLineComponent.Length = -0.015 oLabelStyleLineComponent.StartPointXOffset = 0.005 oLabelStyleLineComponent.StartPointYOffset = -0.005

When first created, the label style object is set according to the ambient settings. Because of this, a new label style object may already contain features. If you are creating a new label style object, be sure to check for such existing features or your style might contain unintended elements.
' Check to see if text components already exist in the ' collection. If any do, just modify the first text ' feature instead of making a new one. Dim oLabelStyleTextComponent As AeccLabelStyleTextComponent If (oLabelStyle.TextComponents.Count > 0) Then Set oLabelStyleTextComponent = oLabelStyle _ .TextComponents.Item(0) Else Set oLabelStyleTextComponent = oLabelStyle _ .TextComponents.Add("New Text") End If

The ambient settings also define which units are used. If you are creating an application designed to work with different drawings, you should take ambient settings into account or labels may demonstrate unexpected behavior in each document.

Using Property Fields in Label Style Text

Text within a label is designated by the AeccLabelStyleTextComponent.Contents property, a string value. Of course, text labels are most useful if they can provide some sort of information that is unique to each particular item being labeled. This is accomplished by specifying property fields within the string. These property fields are of the form <[Property name(modifier 1|[..] modifier n)]>. Modifier values are optional and can be in any order. Any number of property fields can be combined with normal text in the Contents property. In this example, a string component of a label is modified to show design speeds and station values for a point along an alignment:

Using Property Fields in Label Style Text | 15

Dim oTextComponent As AeccLabelStyleTextComponent Set oTextComponent = oLabelStyle.TextComponents.Item(0) oTextComponent.Contents = "SPD=<[Design Speed(P0|RN|AP|Sn)]>" oTextComponent.Contents = oTextComponent.Contents & _ "STA=<[Station Value(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]>"

Valid property fields for each element are listed in the appropriate chapter.

Sharing Syles Between Drawings

Label styles, like all style objects, can be shared between drawings. To do this, call the styles exportTo method, targeting the drawing you want to add the style to. In this example, the first style in the MajorStationLabelStyles collection is exported from the active drawing to another open drawing named Drawing1.dwg:
Dim oDocument As AeccDocument Set oDocument = oCivilApp.ActiveDocument Dim dbDestination As AeccDatabase Set dbDestination = oCivilApp.Documents("Drawing1.dwg").Database Call oDocument.AlignmentLabelStyles.MajorStationLabelStyles(0).ExportTo(dbDestination)

16 | Chapter 1 Root Objects and Common Concepts

Survey

Object Hierarchy

Survey Object Model

Root Objects
This section describes how to gain access to the survey-specific versions of the root document and database objects. It covers the use of ambient settings, user settings, and the equipment database. It also describes the creation of survey projects, which contain networks and figures, and provide access to survey points.

Obtaining Survey-Specific Root Objects

Applications that perform survey operations require special versions of the base objects representing the application and document. The AeccSurveyApplication object is identical to the AeccApplication it is inherited from except that its AeccSurveyApplication.ActiveDocument property returns an object of type AeccSurveyDocument instead of AeccDocument. The AeccSurveyDocument object contains collections of

18 | Chapter 2 Survey

survey-related items, such as projects and equipment databases in addition to all of the methods and properties of AeccDocument. When using survey root objects, be sure to reference the Autodesk Civil Engineering Survey 6.0 Object Library (AeccXSurvey.tlb) and Autodesk Civil Engineering UI Survey 6.0 Object Library (AeccXUISurvey.tlb) libraries. This sample demonstrates how to retrieve the survey root objects:
Dim oApp As AcadApplication Set oApp = ThisDrawing.Application Dim sAppName As String sAppName = "AeccXUiSurvey.AeccSurveyApplication" Dim oSurveyApplication As AeccSurveyApplication Set oSurveyApplication = oApp.GetInterfaceObject(sAppName) ' Get a reference to the currently active document. Dim oSurveyDocument As AeccSurveyDocument Set oSurveyDocument = oSurveyApplication.ActiveDocument

Changing Survey-Specific Ambient Settings

Ambient settings for a survey document are held in the AeccSurveyDocument.Settings property, an object of type AeccSurveySettingsRoot. AeccSurveySettingsRoot inherits all the properties of the AeccSettingsRoot class from which it is derived. Ambient settings allow you to get and set the units and default property settings of survey objects. This is done through the AeccSurveySettingsRoot.SurveySettings, which contains a standard AeccSettingsAmbient object.

Changing Survey User Settings

The survey document also provides access to the survey user settings object. User settings are not specific to a particular document but are tied to a particular user, and all documents a user creates or loads will use the same settings. Survey user settings manage the visibility and appearance of prism sites, backsight lines, foresight lines, and baselines. Survey user settings also control how network and figure previews are shown, and under what conditions points, figures, and observations are automatically erased or exported. These settings also allow you to determine or set which figure prefix database, equipment database, or item of equipment is currently in use. The survey user settings object is retrieved through the AeccSurveyDocument.GetUserSettings method, which returns an AeccSurveyUserSettings object. To apply any changes made to the user settings, pass the modified AeccSurveyUserSettings object to the AeccSurveyDocument.UpdateUserSettings method.

Changing Survey-Specific Ambient Settings | 19

Dim oUserSettings As AeccSurveyUserSettings Set oUserSettings = oSurveyDocument.GetUserSettings ' Modify and examine the current settings. With oUserSettings .ShowBaseline = True Dim oColor As New AcadAcCmColor oColor.SetRGB 255, 165, 0 ' bright orange Set .BaselineColor = oColor .EraseAllFigures = False Debug.Print "Default layer:"; .DefaultFigureLayer End with ' Save the changes to the user settings object. oSurveyDocument.UpdateUserSettings oUserSettings

Using the Equipment Database

The equipment database contains a list of equipment used to gather surveying data. The information about each item of equipment is used in least squares and other computations. A collection of all equipment lists is contained in the AeccSurveyDocument.EquipmentDatabases property. Each equipment database is a collection of individual items of equipment. An equipment database is an object of type AeccSurveyEquipmentDatabase, and contains methods for searching the list of equipment and for copying lists from other databases. Each item of equipment is represented by an AeccSurveyEquipment object, which contains properties describing aspects of the equipment, including the name and description, how the instrument measures angles, the unit types for angle and distance, Electronic Distance Meter settings, prism accuracy and offset, and the accuracy of the instrument. This sample program displays selected information about each equipment item in the documents database:

20 | Chapter 2 Survey

Dim oEquipDatabases As AeccSurveyEquipmentDatabases Dim oEquipDatabase As AeccSurveyEquipmentDatabase Dim oEquipment As AeccSurveyEquipment Set oEquipDatabases = oSurveyDocument.EquipmentDatabases For Each oEquipDatabase In oEquipDatabases Debug.Print "Database: "; oEquipDatabase.Name Debug.Print For Each oEquipment In oEquipDatabase With oEquipment Debug.Print "----" Debug.Print "Item: "; .Name; " Id: "; .Id Debug.Print " Description: "; .Description Debug.Print " Angle Type: "; .AngleType Debug.Print " Angle Unit: "; .AngleUnit Debug.Print " Azimuth Std: "; .AzimuthStandard Debug.Print " Wave Constant: "; .CarrierWaveConstant Debug.Print " Center Standard: "; .CenterStandard Debug.Print " Circle Standard: "; .CircleStandard Debug.Print " Coordinate Std: "; .CoordinateStandard Debug.Print " Distance Unit: "; .DistanceUnit Debug.Print " Edm Error: "; .EdmMmError; "mm" Debug.Print " Edm Error: "; .EdmPpmError; "ppm" Debug.Print " Edm Offset: "; .EdmOffset Debug.Print " Elevation Std: "; .ElevationStandard Debug.Print " H Collimation: "; .HorizontalCollimation Debug.Print " Is Prism Tilted: "; CStr(.IsTiltedPrism) Debug.Print " Measuring Device: "; .MeasuringDevice Debug.Print " Pointing Std: "; .PointingStandard Debug.Print " Prism Constant: "; .PrismConstant Debug.Print " Prism Offset: "; .PrismOffset Debug.Print " Prism Std: "; .PrismStandard Debug.Print " Revision: "; .Revision Debug.Print " Target Std: "; .TargetStandard Debug.Print " Theodolite Std: "; .TheodoliteStandard Debug.Print " Vertical Angle Type: "; .VerticalAngleType Debug.Print " V Collimation: "; .VerticalCollimation Debug.Print End With Next Next

Creating a Survey Project

The survey database is the high-level construct that contains collections of networks and figures, and provides access to survey points. Throughout the API, survey databases are called projects. The collection of all projects in a document are held in the AeccSurveyDocument.Projects property. Once created, a project cannot be removed from this collection using API methods. The only way to remove a survey project is to delete the Project folder and refresh the collection. When a new project is created, a unique GUID identifying the project is generated. This sample creates a new survey project with the name Proj01:

Creating a Survey Project | 21

Dim oSurveyProject As AeccSurveyProject Set oSurveyProject = oSurveyDocument.Projects.Create("Proj01") ' Print the next available survey point Id available. Debug.Print "Next available Id:"; _ oSurveyProject.GetNextWritablePointNumber()

Adjusting Survey Project Settings

A survey project has a group of properties accessed through the survey project settings object. Survey project settings define what measurement units are used, what angle types are used, and the precision of each measurement. It records what kinds of adjustments are made to observations, and the types and accuracy of traverse analyses and angle balancing. It also has methods for converting between metric units and the units of the ambient settings, and between easting and northing and longitude and latitude. The project settings object is retrieved through the AeccSurveyProject.GetProjectSettings method, which returns an AeccSurveyProjectSettings object. To apply any changes made to the project settings, pass the modified AeccSurveyProjectSettings object to the AeccSurveyProject.UpdateProjectSettings method.
Dim oProjectSettings As AeccSurveyProjectSettings Set oProjectSettings = oSurveyProject.GetProjectSettings() ' Modify and examine the current settings. With oProjectSettings .AngleType = aeccSurveyAngleTypeAzimuth Debug.Print "Sea level correction? :"; .SeaLevelCorrection End With ' Save the changes to the project settings object. oSurveyProject.UpdateProjectSettings oProjectSettings

Accessing Extended Properties

Survey root objects can have extended properties associated with them. LandXML extended properties are used to import and export Survey LandXML attributes or collections of elements. For example, in the LandXML schema, a CgPoint element (a SurveyPoint) within a CgPoints collection (a SurveyPointGroup), may contain a DTMAttribute where its enumeration value can be used to aid the user in determining whether the point should be included in a surface definition. User-defined extended properties can be used to define additional attributes beyond those defined by the LandXML schema. For an example of standard LandXML extended properties, see the C:\Documents and Settings\All Users\Application Data\Autodesk\C3D 2009\enu\Survey\LandXML - Standard.sdx_def file. The AeccSurveyFigure, AeccSurveyNetwork, AeccSurveyPoint, and AeccSurveyProject objects each have a LandXMLXPropertiesRoot property, which gives you access to the AeccSurveyLandXMLXPropertiesRoot for that object. Those objects also each have a UserDefinedXProperties object, which gives you access to the AeccSurveyUserDefinedXProperties for that object.

Survey Network
A network represents the spatial framework of a survey. Each network contains a collection of control points, directions, setups, and non-control points. It also contains information on how these objects are related, such as how the control points and setups are connected relative to one another.

22 | Chapter 2 Survey

Creating a Survey Network

Survey networks are created through the Create method of the AeccSurveyProject.Networks collection.
Dim oSurveyNetwork As AeccSurveyNetwork Set oSurveyNetwork = oSurveyProject.Networks.Create("Net_01")

Adding Control Points to a Network

Control points are the known or fixed locations that other survey points are based from. The collection of control points in a network is held in the AeccSurveyNetwork.ControlPoints property. New control points can be added to the network through the collections Create method. Create adds a new point with the specified features to the AeccSurveyControlPoints collection and returns a reference to the newly created AeccSurveyControlPoint object.
' Get collection of all control points. Dim oControlPoints As AeccSurveyControlPoints Set oControlPoints = oSurveyNetwork.ControlPoints ' Create a control point with an id number of 3001 at ' the location 5000.0m, 5000.0m, elevation 100.0m. Dim oControlPoint As AeccSurveyControlPoint Set oControlPoint = oControlPoints.Create( _ 3001, _ "ControlPoint_01", _ "Description of control point", _ 5000#, _ 5000#, _ 100#)

Adding Directions to a Network

A direction is a known or fixed direction (either azimuth or bearing) from a control point to another point reference. The point reference may be observed at a later time in the survey, or it may never actually be occupied by a setup. This can happen if the reference point is a mountain top or tower or some other location where survey equipment cannot physically be placed but the direction from the control point to that location is known. An entire survey network can be defined from a single control point and a single direction. The collection of directions in a network is held in the AeccNetwork.Directions property. New directions can be added to the network through the collections Create method. Create adds a new direction between two points at the specified angle to the AeccSurveyDirections collection and returns a reference to the newly created AeccSurveyDirection object.

Creating a Survey Network | 23

' Get collection of all directions. Dim oDirections As AeccSurveyDirections Set oDirections = oSurveyNetwork.Directions ' Create a direction from point 3001 to the (not yet ' existing) point 3004 at an angle of 45.0 degrees azimuth. Dim oDirection As AeccSurveyDirection ' 0.785398163 = 40 degrees in radians Set oDirection = oDirections.Create( _ 3001, _ 3004, _ 0.785398163, _ aeccSurveyDirectionTypeAzimuth)

Adding Setups to a Network

A setup represents a survey instrument session made in the field. The instrument is set up on a control point or a previously observed point, and a reference direction (backsight) is made to another point. Locations on the Earths surface are then determined with surveying methods relative to the setup and the direction of the backsight. These locations are called observations, and are represented by an AeccSurveyObservation object. Each setup object contains a collection of observation objects. An observation object is composed of any or all of the following measurements: angle, distance, vertical, latitude, longitude, northing, easting, or elevation. The observation object also has a series of properties describing the nature of the observation equipment. The collection of setups in a network is held in the AeccNetwork.Setups property. New setups can be added to the network through the collections Create method. Create adds a new setup at the specified location to the AeccSurveySetups collection and returns a reference to the newly created AeccSurveySetup object. This sample creates a setup at the location of point 3001 using the location of point 3004 as the backsight. It then creates an observation to another location, which is given the identification 3002.

24 | Chapter 2 Survey

Dim oSetups As AeccSurveySetups Dim oSetup1 As AeccSurveySetup Set oSetups = oSurveyNetwork.Setups ' Create a setup at 3001 with a backsight at 3004 (the ' backsight direction should be calculated automatically). Set oSetup1 = oSetups.Create(3001, 3004) Debug.Print "Direction:"; oSetup1.BacksightDirection Debug.Print "Orientation:"; oSetup1.BacksightOrientation ' Now any observation angle is based on the line ' from 3001 to 3004. Dim oObservations As AeccSurveyObservations Set oObservations = oSetup1.Observations Dim oObservation1 As AeccSurveyObservation ' On setup "Station:3001, Backsight:3004" create an observation ' of point 3002. ' Angle = 90 degrees (1.57079633 radians) ' Angle Type = Angle ' Distance = 100# ' Distance Type = Slope ' Vertical = 90 degrees (1.57079633 radians) ' Vertical Type = Vertical Angle ' Target Height = 0# ' Target Type = Prism Set oObservation1 = oObservations.Create( _ 3002, _ aeccSurveyAngleTypeAngle, _ 1.57079633, _ aeccSurveyDistanceTypeSlope, _ 100#, _ aeccSurveyVerticalTypeVerticalAngle, _ 1.57079633, _ aeccSurveyTargetTypePrism, _ 0#, _ "From setup <Station:3001, Backsight:3004> to Point 3002") ' From this survey equipment data, the location of point ' 3002 can be determined: Debug.Print "Point 3002 at:"; oObservation1.Easting; Debug.Print ", "; oObservation1.Northing

Adding Non-control Points to a Network

A survey network also contains a collection of non-control points, which represent points within a survey network whose location is determined by observation, but are not connected to other survey observations and remain unaffected by a network analysis. These non-control points are represented by objects of type AeccNonControlPoint, and are defined by an easting, northing, and an optional elevation. The collection of all non-control points in a survey network are held in the AeccSurveyNetwork.NonControlPoints property.

Adding Non-control Points to a Network | 25

' Create a non-control point with an id number of 3006 at ' the location 4950.0, 5000.0, elevation 100.0. Dim oNonControlPt As AeccSurveyNonControlPoint Set oNonControlPt = oSurveyNetwork.NonControlPoints.Create( _ 3006, "NonControlPoint_01", "Description of non-control point", 4950#, 5000#, 100#)

A non-control point may be promoted to a control point if you reference the point as a control point when creating a traverse, or reference the point as a setup to make observations to other points that may affect locations during an analysis.

Creating Paths for Traverse Analysis

A traverse is a path through survey points. A traverse starts at a control point, continues through other survey points, and either returns to the original control point (a closed loop) or ends at another control point (an open loop). These paths are used for traverse analysis, which are methods for determining the amount of error in the locations and directions of survey points. The API provides methods for creating and examining traverse paths, but it does not provide methods for performing a traverse analysis. The collection of all traverses in a network are stored in the AeccSurveyNetwork.Traverses property. A single traverse is represented by an object of type AeccSurveyTraverse. New traverses are created using the collections Create method. This method requires the identification number of the starting control point, a backsight for that point, the final control point reached, and an array of the identification numbers of all intermediate points. This sample creates a traverse starting at control point 3001, continuing though points 3002, 3003, and 3004, and finishing back at the starting control point 3001. The user can then perform a traverse analysis based on this closed loop.
Dim oTraverse As AeccSurveyTraverse Dim lStations(0 To 2) As Long lStations(0) = 3002: lStations(1) = 3003; lStations(2) = 3004 Set oTraverse = oSurveyNetwork.Traverses.Create( _ "Traverse_01", _ 3001, _ 3004, _ 3001, _ lStations)

Adding Survey Data to the Drawing

Adding elements or modifying information in a survey network object changes the survey database but does not automatically change the drawing. After you are done adding points, directions, and other elements that have a graphical element, call the AeccSurveyNetwork.AddToDrawing method to create AutoCAD elements that correspond to the survey network data. This is equivalent to the AutoCAD Civil 3D command Insert Into Drawing.
oSurveyNetwork.AddToDrawing

26 | Chapter 2 Survey

Getting Survey Network Drawing Objects

You can get and manipulate the AutoCAD drawing objects that make up a survey network from the AutoCAD Civil 3D user interface. The drawing objects are represented by the AeccSurveyNetworkEntity object. For example, this code prompts the user to select the survey network, tests whether it is the survey network object, and then prints some information about it:
Dim objPart As AeccSurveyNetworkEntity Dim objEnt As AcadObject Dim objAcadEnt As AcadEntity Dim varPick As Variant ThisDrawing.Utility.GetEntity objEnt, varPick, "Select the Survey Network" If TypeOf objEnt Is AeccSurveyNetworkEntity Then Set objPart = objEnt Debug.Print objPart.Name, TypeName(objPart) ElseIf TypeOf objEnt Is AcadEntity Then Set objAcadEnt = objEnt Debug.Print objAcadEnt.Name, TypeName(objAcadEnt) End If

Figures
Figures are a group of connected lines and arcs that have meaning within a survey. A figure can represent a fence, building, road, parcel, or similar object. Unlike a normal polyline, a vertex in a figure can reference a survey point. If a referenced survey point is moved, vertices in the figure are moved as well. The first line or arc added to the figure sets the location all other lines and arcs will be drawn from. Each line and arc added to a figure is in turn based on the endpoint of the previous element. The position of the last endpoint can be determined from the read-only properties AeccSurveyFigure.LastPointX and AeccSurveyFigure.LastPointY.

Creating a Figure Object

A collection of all figures in the survey database are stored in the AeccSurveyProject.Figures property. New figures are made using the collections Create method.
Dim oFigure As AeccSurveyFigure Set oFigure = oSurveyProject.Figures.Create("Figure_01")

Adding Lines to a Figure

Each line added to a figure is drawn from the endpoint of the previous line or arc. The new line can be drawn to a particular point location, for a distance along an absolute azimuth, or for a distance along an azimuth relative to the direction of the previous line. If the figure has no lines or arcs, then the first line added will only set the point that the next line or arc is drawn from.

AddLineByPoint
AddLineByPoint adds a line to the figure to the specified point location. An optional parameter can specify

a survey point to reference so that whenever it changes the figure vertex will change as well.

Getting Survey Network Drawing Objects | 27

' Draw a line to the location of survey point 3001. Dim oPoint1 As AeccSurveyPoint Set oPoint1 = oSurveyProject.GetPointByNumber(3001) oFigure.AddLineByPoint oPoint1.Easting, oPoint1.Northing, 3001

AddLineByAzimuthDistance
AddLineByAzimuthDistance adds a line to the figure of the specified length and of the specified angle from

the major axis of the survey project.

' Draw a line 30 meters long at 10 degrees from the major axis. oFigure.AddLineByAzimuthDistance 0.17453, 30

AddLineByDeltaAzimuthDistance
AddLineByDeltaAzimuthDistance adds a line to the figure of the specified length and of the specified angle

from the endpoint of the previous line.

' Draw a line 20 meters long at 270 degrees from the ' previous line. oFigure.AddLineByDeltaAzimuthDistance 4.7124, 20

Adding Arcs to a Figure

Each arc added to a figure is drawn from the endpoint of the previous line or arc. AddArc adds a segment of a circle to the figure to the specified point location. The shape of the arc is defined by the Radius, Bulge, and CenterX and CenterY parameters. The Bulge parameter defines what fraction of a circle the arc comprises. If the Radius parameter is zero or negative the arc is curved in the clockwise direction, otherwise the arc is curved in the counter-clockwise direction. An optional parameter can specify a survey point to reference so that whenever it changes the arc endpoint will change as well.
' Create a clockwise arc comprising of roughly half a circle ' that ends at survey point 3001. oFigure.AddArc 10, 1.7, 0, 0, oPoint1.Easting, _ oPoint1.Northing, , 3001

Adding Figures to the Drawing

Adding lines and arcs to a figure changes the survey database but does not automatically change the drawing. After you are done adding elements to the figure, call the AeccSurveyFigure.AddToDrawing method to create AutoCAD elements that correspond to the figure. This is equivalent to the AutoCAD Civil 3D command Insert Into Drawing.

Figures and AutoCAD Civil 3D

A figure can influence AutoCAD Civil 3D objects such as parcels and TIN surfaces. If the AeccSurveyFigure.IsLotLine property is set to True, then parcel segments are created for each figure line and arc when the figure is added to the drawing. If any set of parcel segments creates closed figures, then a parcel is formed. You can assign the parcel segments to a particular site by setting the AeccSurveyFigure.Site property - otherwise, a new site named Survey Site is created automatically. The figure still remains in the survey database, and deleting the figure removes all associated parcel segments from the drawing.

28 | Chapter 2 Survey

A figure can also form a breakline that defines how surfaces are triangulated. This is accomplished by setting the AeccSurveyFigure.IsBreakline property to True

Creating a Figure Style

A figure style controls the visual appearance of figures. The AeccSurveyFigureStyle object has AeccDisplayStyle properties for controlling the color, line type, and visibility of lines and of markers at the figure endpoints, the figure midpoint, at line vertices. The types of markers used are controlled by separate AeccMarkerStyle properties for the start, mid, and end points of the figure, and for all vertexes. Markers can also be drawn at a normal alignment to the orientation of the figure by setting the IsAlignAdditionalMarkersWithFigure, IsAlignMidPointMarkersWithFigure, IsAlignStartAndEndPointMarkersWithFigure, and IsAlignVertexMarkersWithFigure properties to True for the appropriate type of marker. Additional markers can also be placed along the figure. The nature of these additional markers is set by the AeccSurveyFigureStyle.AdditionalMarkersPlacementMethod property. If the placement method is set for interval placement, then a new marker is placed every n units apart where n is the value of the AeccSurveyFigureStyle.AdditionalMarkersInterval property. If the placement method is set for divided placement, then the figure is divided into n parts of equal length where n is the value of the AeccSurveyFigureStyle.AdditionalMarkersDivideFigureBy property. A marker is placed at each part, including the figure start and end points. If the placement method is set for continuous, then the markers are placed exactly one markers width apart along the length of the figure. You can determine the style of figure drawing by examining the FigureDisplayMode property. There are three ways a figure can be visualized: using figure elevations, flattening the figure to a single elevation, or exaggerating figure elevations. If the figure is flattened to a single elevation, the elevation can be read from the FlattenFigureElevation property. If the figure elevations are exaggerated when displayed, the amount of exaggerations is held in the read-only FigureElevationScaleFactor property. All figure styles are stored in the AeccSurveyDocument.FigureStyle collection. The figure objects AeccSurveyFigure.Style property takes the string name of the style to use. This sample creates a new figure style object and adjusts some of the style settings:

Creating a Figure Style | 29

Dim Dim Set Set

oFigureStyles As AeccSurveyFigureStyles oFigureStyle As AeccSurveyFigureStyle oFigureStyles = oSurveyDocument.FigureStyles oFigureStyle = oFigureStyles.Add(sStylename)

' Set the style so that additional markers are visible, ' blue, and drawn every 20 units along the figure. With oFigureStyle .AdditionalMarkersDisplayStylePlan.Visible = True .AdditionalMarkersDisplayStylePlan.Color = 150 ' blue .AdditionalMarkersPlacementMethod = _ aeccSurveyAdditionalMarkerPlacementMethodAtInterval .AdditionalMarkersInterval = 20 End With ' Assign the style to a figure. oFigure.Style = oFigureStyle.Name

Using the Figure Prefix Database

A figure read from a fieldbook file can have a letter prefix signifying what object or concept the figure represents. This figure prefix describes the style and property settings to use with the figure. A list of figure prefixes is stored in AeccSurveyFigurePrefixDatabase objects. The collection of all databases in the document are stored in the AeccSurveyDocument.FigurePrefixDatabases property. New figure prefixes and databases are added through the parent collections Create method. Once a prefix or database is created, it becomes a permanent part of the figure prefix database and it is not lost upon loading a new document or running a new instance of AutoCAD Civil 3D. Because of this, it is important to check for existing prefix databases and prefixes by name before trying to create new ones. The AeccSurveyFigurePrefixDatabases.FindItem method can be used to search for an existing database id or name. NOTE The similarly named AeccSurveyFigurePrefixDatabase.FindItem can only be used to search for the identification numbers of prefixes within a database - to find a prefix by name, use the AeccSurveyFigurePrefixDatabase.GetMatchedFigurePrefix method. This sample creates a new figure prefix database and a new figure prefix. It switches the current database to the newly created one, and sets an existing figure to use the new prefixs style.

30 | Chapter 2 Survey

' Get a reference to all the prefix databases. Dim oPrefixDatabases As AeccSurveyFigurePrefixDatabases Set oPrefixDatabases = oSurveyDocument.FigurePrefixDatabases ' See if our database already exists. If it does not, ' create a new one. Dim oPrefixDatabase As AeccSurveyFigurePrefixDatabase Set oPrefixDatabase = oPrefixDatabases.FindItem("NewDB") If (oPrefixDatabase Is Nothing) Then Set oPrefixDatabase = oPrefixDatabases.Create("NewDB") End If ' See if our figure prefix already exists. If it does not, ' create a new figure prefix. Dim oSurveyFigurePrefix As AeccSurveyFigurePrefix On Error Resume Next Set oSurveyFigurePrefix = _ oPrefixDatabase.GetMatchedFigurePrefix("BV") On Error GoTo 0 If (oSurveyFigurePrefix Is Nothing) Then Set oSurveyFigurePrefix = oPrefixDatabase.Create("BV") End If ' Set the properties of the prefix. oSurveyFigurePrefix.Style = _ oSurveyDocument.FigureStyles(0).Name oSurveyFigurePrefix.IsLotLine = True oSurveyFigurePrefix.IsBreakline = True oSurveyFigurePrefix.Layer = "0" oSurveyFigurePrefix.Save

You can set a figure to use a prefix style manually by using the AeccSurveyFigure.InitializeFromFigurePrefix method. It searches through the current prefix database for a prefix name that matches the first part of the name of the figure. For example, a figure with the name BV 01 matches a prefix with the name BV. The current prefix database can be determined through the CurrentFigurePrefixDatabase property of the documents survey user settings. The following code shows the correct method for doing this:
Dim oUserSettings As AeccSurveyUserSettings Dim CurrentDatabase As String Set oUserSettings = oSurveyDocument.GetUserSettings CurrentDatabase = oUserSettings.CurrentFigurePrefixDatabase

You can change the current database by setting the CurrentFigurePrefixDatabase property to the new name and then updating the survey user settings:
oUserSettings.CurrentFigurePrefixDatabase = "NewDB" oSurveyDocument.UpdateUserSettings oUserSettings

Sample Program
SurveySample.dvb
<installation-directory>\Sample\Civil 3D API\Vba\Survey\SurveySample.dvb This sample creates a simple survey from hard-coded data using control points, setups, directions, and figures. A survey style is created and applied. The ambient settings and other global settings are demonstrated.

Sample Program | 31

Points

Object Hierarchy

Points Object Model

Points
This section covers the collection of all points in a document, accessing points stored in a file, and the use of the point object.

Using the Points Collection

All points in a document are held in the AeccDocument.Points property, an object of type AeccPoints. Besides the usual collection properties and methods, the Points object also has methods for dealing with large numbers of points at once. An array of positions can be added using the AeccPoints.AddMultiple method.

The following example adds a series of points to the AeccDocument.Points collection using AddMultiple and then accesses points in the collection directly:
' This adds an array of point locations to the document's ' points collection. Dim lNumAdded As Long Const NUM_LOCATIONS As Long = 3 ' One dimensional array, 3 for each point location. Dim dLocations(0 To (3 * NUM_LOCATIONS) - 1) As Double ' One point per line dLocations(0) = 4927: dLocations(1) = 3887: dLocations(2) = 150 dLocations(3) = 5101: dLocations(4) = 3660: dLocations(5) = 250 dLocations(6) = 5144: dLocations(7) = 3743: dLocations(8) = 350 lNumAdded = oPoints.AddMultiple(NUM_LOCATIONS, dLocations, 0) ' This computes the average elevation of all points in a document. Dim oPoints As AeccPoints Dim i As Long Dim avgElevation As Double Set oPoints = g_oAeccDocument.Points For i = 0 To oPoints.Count - 1 avgElevation = avgElevation + oPoints.Item(i).Elevation Next i avgElevation = avgElevation / oPoints.Count MsgBox "Average elevation: "& avgElevation & _ vbNewLine & "Number of points: " & oPoints.Count

Accessing Points in a File

The AeccPoints object also has methods for reading and writing point locations in a file. The AeccPoints.ImportPoints method creates points from locations stored in a text file. The AeccPoints.ExportPoints method writes point locations to a text file. The second parameter of the ImportPoints and ExportPoints methods is a string that describes how the point values are stored in the file. The following table lists some commonly available file formats. You can create other formats by using the Point File Format dialog box. Point File Formats String Literal
ENZ (comma delimited) NEZ (space delimited) NEZ (comma delimited) PENZ (space delimited) PENZ (comma delimited) PENZD (space delimited) PENZD (comma delimited)

Format of values in the file

Easting, Northing, Elevation Northing Easting Elevation Northing, Easting, Elevation Point# Easting Northing Elevation Point#, Easting, Northing, Elevation Point# Easting Northing Elevation Description Point#, Easting, Northing, Elevation, Description

34 | Chapter 3 Points

String Literal
PNE (space delimited) PNE (comma delimited) PNEZ (space delimited) PNEZ (comma delimited) PNEZD (space delimited) PNEZD (comma delimited) ENZ (space delimited) Autodesk Uploadable File

Format of values in the file

Point# Northing Easting Point#, Northing, Easting Point# Northing Easting Elevation Point#, Northing, Easting, Elevation Point# Northing Easting Elevation Description Point#, Northing, Easting, Elevation, Description Easting Northing Elevation Point# Northing Easting Elevation Description

The third parameter of the ImportPoints method is an object of type AeccPointImportOptions, which can be set to perform actions as the data is being loaded. For example, you can add offsets to the point positions or elevations, determine which points to read from the file, or specify the point group where the points are placed. The third parameter of the ExportPoints method is of the similar AeccPointExportOptions type. This example demonstrates the ImportPoints and ExportPoints methods:
Dim Dim Dim Dim Dim oPoints As AeccPoints oImportOptions As New AeccPointImportOptions sFilename As String sFileFormat As String iCount As Integer

Set oPoints = oDocument.Points sFilename = "C:\My Documents\SamplePointFile.txt" sFileFormat = "PENZ (space delimited)" oImportOptions.PointDuplicateResolution = aeccPointDuplicateOverwrite iCount = oPoints.ImportPoints(sFilename, sFileFormat, oImportOptions) ' Export the files to a separate file. Dim oExportOptions As New AeccPointExportOptions sFilename = "C:\My Documents\SamplePointFile2.txt" oExportOptions.ExpandCoordinateData = True oPoints.ExportPoints sFilename, sFileFormat, oExportOptions

NOTE When you add points using the ImportPoints method, it is possible that the point numbers will conflict with those that already exist in the drawing. In such cases, the user is given an option to renumber the point numbers from the file, or to cancel the operation which will result with a Visual Basic error. An application that uses ImportPoints should take this into account.

Using Points
Each individual point is represented by an object of type AeccPoint. The point object contains the identification number, description, and location for the point. The identification number, held in the

Using Points | 35

Point.Number property, is unique and is automatically assigned when the point is first created. It cannot be changed. The read-only Point.FullDescription property is only meaningful when the point is read from

a file that contains description information. You can access the local position through either the AeccPoint.Easting and AeccPoint.Northing properties or by using the AeccPoint.Location property, a three-element array containing the easting, northing, and elevation. The points location can also be specified by using the AeccPoint.Grideasting and AeccPoint.GridNorthing properties or the AeccPoint.Latitude and AeccPoint.Longitude properties, depending on the coordinate settings of the drawing. This sample adds a new point to the documents collection of points and sets some of its properties.
Dim oPoints As AeccPoints Set oPoints = g_oAeccDocument.Points Dim oPoint1 As AeccPoint Dim dLocation(0 To 2) As Double dLocation(0) = 4958 dLocation(1) = 4078 Set oPoint1 = oPoints.Add(dLocation) oPoint1.Name = "point1" oPoint1.RawDescription = "Point Description"

Point User-Defined Properties

Point objects can have user-defined properties associated with them, and the properties can be organized into user-defined classifications, or are put into an Unclassified classification. You can create new classifications and user-defined properties via the API, though you cant access the values of existing user-defined properties attached to points. For more information about user-defined properties and classifications, see User-Defined Property Classifications in the AutoCAD Civil 3D User Guide. This sample creates a new user-defined property classification for points called Example, and then adds a new user-defined property with upper and lower bounds and a default value:
Dim oApp As AcadApplication Set oApp = ThisDrawing.Application ' NOTE - Always specify the version number. Const sAppName = "AeccXUiLand.AeccApplication.6.0" Set g_vCivilApp = oApp.GetInterfaceObject(sAppName) Set g_oDocument = g_vCivilApp.ActiveDocument Set g_oAeccDb = g_oDocument.Database Dim oUDPClass As AeccUserDefinedPropertyClassification Dim oUDPProp As AeccUserDefinedProperty 'Create a user-defined parcel property classification Set oUDPClass = g_oAeccDb.PointUserDefinedPropertyClassifications.Add("Example") ' Add a Property to our new classification An integer using upper ' and lower bound limits of 10 and 20 with a default value of 15 Set oUDPProp = oUDPClass.UserDefinedProperties.Add("Extra Data", _ "Some Extra Data", aeccUDPPropertyFieldTypeInteger, True, False, 10, True, _ False, 20, True, 15, Null)

Style
This section covers the creation of point styles and point-specific features of the point label style object. It also explains point description keys, which are used to assign styles to points read from a text file.

36 | Chapter 3 Points

Creating Point Styles

A point style is a group of settings that define how a point is drawn. These settings include marker style, marker color and line type, and label color and line type. Point objects can use any of the point styles that are currently stored in the document. Styles are assigned to a point through the points AeccPoint.Style property. Existing point styles are stored in the documents AeccDocument.PointStyles property. You can also create custom styles and add them to the documents collection of point styles. First, add a new style to the documents list of styles using the AeccDocument.PointStyles.Add method. This method returns a new style object that is set with all the properties of the default style. You can then make the changes to the style object you require. This sample creates a new points style, adjusts the style settings, and the assigns the style to point Point1:
' Create the style objects to use. Dim oPointStyles As AeccPointStyles Dim oPointStyle As AeccPointStyle Set oPointStyles = oDocument.PointStyles ' Add the style to the document's collection of point styles. Set oPointStyle = oPointStyles.Add("Sample Point Style") ' This style substitutes the normal point marker ' with a dot with a circle around it. oPointStyle.MarkerType = aeccUseCustomMarker oPointStyle.CustomMarkerStyle = aeccCustomMarkerDot oPointStyle.CustomMarkerSuperimposeStyle = _ aeccCustomMarkerSuperimposeCircle ' Now set the point to use this style. oPoint1.Style = oPointStyle

Creating Point Label Styles

Any text labels or graphical markers displayed at the point location are set by assigning a label style object to the AeccPoint.LabelStyle property. The collection of these label styles is accessed through the AeccDocument.PointLabelStyle property. Point label styles can use the following property fields in the contents of any text components: Valid property fields for AeccLabelStyleTextComponent.Contents
<[Name(CP)]> <[Point Number]> <[Northing(Uft|P4|RN|AP|Sn|OF)]> <[Easting(Uft|P4|RN|AP|Sn|OF)]> <[Raw Description(CP)]>

Creating Point Styles | 37

Valid property fields for AeccLabelStyleTextComponent.Contents

<[Full Description(CP)]> <[Point Elevation(Uft|P3|RN|AP|Sn|OF)]> <[Latitude(Udeg|FDMSdSp|P6|RN|DPSn|CU|AP|OF)]> <[Longitude(Udeg|FDMSdSp|P6|RN|DPSn|CU|AP|OF)]> <[Grid Northing(Uft|P4|RN|AP|Sn|OF)]> <[Grid Easting(Uft|P4|RN|AP|Sn|OF)]> <[Scale Factor(P3|RN|AP|OF)]> <[Convergence(Udeg|FDMSdSp|P6|RN|AP|OF)]> <[Survey Point]>

Label styles are described in detail in the chapter 1 section Label Styles (page 13).

Using Point Description Keys

Point description keys are a method for attaching style, label style, and orientation to point locations in a drawing - possibly imported from a text file which lacks such information. Keys are objects of type AeccPointDescriptionKey. The AeccPointDescriptionKey.Name property is a pattern matching code. If any new points are created with a description that matches the name of an existing key, the point is assigned all the settings of that key. The wildcards ? and * are allowed in the name. Keys can contain either constant scale or rotation values for points or can assign orientation values depending on parameters passed through the description string. Point description keys are held in sets, objects of type AeccPointDescriptionKeySet. The collection of all sets in a document are held in the documents AeccDocument.PointDescriptionKeySets property.

38 | Chapter 3 Points

' Create a key set in the document's collection ' of sets. Dim oPointDescriptionKeySet As AeccPointDescriptionKeySet Set oPointDescriptionKeySet = _ oDocument.PointDescriptionKeySets.Add("Sample Key Set") ' Create a new key in the set we just made. Match with ' any description beginning with "SMP". Dim oPointDescriptionKey As AeccPointDescriptionKey Set oPointDescriptionKey = oPointDescriptionKeySet.Add("SAMP*") ' Assign chosen styles and label styles to the key. oPointDescriptionKey.PointStyle = oPointStyle oPointDescriptionKey.OverridePointStyle = True oPointDescriptionKey.PointLabelStyle = oLabelStyle oPointDescriptionKey.OverridePointLabelStyle = True ' Turn off the scale override, and instead scale ' to whatever is passed as the first parameter. oPointDescriptionKey.OverrideScaleParameter = False oPointDescriptionKey.UseDrawingScale = False oPointDescriptionKey.ScaleParameter = 1 oPointDescriptionKey.ScaleXY = True ' And turn on the rotation override, and rotate ' all points using this key 45 degrees clockwise. oPointDescriptionKey.OverrideFixedRotation = True oPointDescriptionKey.FixedRotation = 0.785398163 ' radians oPointDescriptionKey.ClockwiseRotation = True

The following is the contents of a text file in PENZD (comma delimited) format with point information, a description, and parameter. This creates two points using the previously defined SAMP* description key, resulting in point markers four times normal size.
2000,3700.0,4900.0,150.0,SAMPLE 4 2001,3750.0,4950.0,150.0,SAMPLE 4

When a text file is loaded using Points.ImportPoints, the first alphanumeric element in a points description is compared to the names of all point description keys. If a match is found, the points settings are adjusted to match the description key. Any parameters to pass to the key are added after the description, separated by spaces. If using parameters, use a comma delimited file format or else any parameters will be ignored. This process only takes place when points are read from a file - after a point is created, setting the AeccPoint.RawDescription property does nothing to change the points style.

Point Groups
This section explains the creation and use of point groups, which is a named subset of the points in a document.

Creating Point Groups

A point group is a collection that contains a subset of the points in a document. A collection of all point groups is held in a documents AeccDocument.PointGroups property. Add a new point group by using the

Point Groups | 39

AeccDocument.PointGroups.Add method and specifying a unique identifying string name. A new empty

point group is returned.

' Get the collection of all point groups from the document. Dim oPtGroups As AeccPointGroups Dim oPtGroup As AeccPointGroup Set oPtGroups = oAeccDocument.PointGroups ' Add our group to the collection of groups. Set oPtGroup = oPtGroups.Add("Sample point group")

Adding Points to a Point Group Using QueryBuilder

Points can be placed into a point group by using the QueryBuilder, which is a mechanism for selecting from among all the points in the document. The AeccPointGroup.QueryBuilder property is an object of type AeccPointGroupQueryBuilder, and contains many different properties that allow including or excluding points based on a specific criteria. These properties are:
InlcudeElevations ExcludeElevations

IncludeFullDescriptions

ExcludeFullDescriptions

IncludeNames

ExcludeNames

IncludeNumbers

ExcludeNumbers

IncludeRawDescriptions

ExcludeRawDescriptions

IncludePointGroups

Each of these properties is a string that describes the selection criteria used. As many properties may be used as needed to make your selection. Any property left blank has no affect on the selection. The properties that query string properties of points (FullDescription, Name, RawDescription) consist of a comma-separated list of possible strings to match against. Each element in that list may contain the wildcards ? and *. The properties that deal with number properties of points consist of a comma delineated list of specific numbers or ranges of numbers (two values separated by a hyphen, such as 100-200). The properties that deal with elevation consist of a comma delineated list of specific elevations, ranges of elevation, upper limits (a less-than symbol followed by a value, such as <500), or lower limits (a greater-than symbol followed by a value, such as >100).

40 | Chapter 3 Points

' Add points to the point group using the QueryBuilder. ' Add point 1 and point 2 to the point group. oPtGroup.QueryBuilder.IncludeNames = "po?nt1,point2" ' Add point 3 to the point group by using its number. oPtGroup.QueryBuilder.IncludeNumbers = "3" ' You can also use wildcards. The following would ' select all points with a name beginning with "poi". oPtGroup.QueryBuilder.IncludeNames = "poi*" ' Exclude those points with an elevation above 300. oPtGroup.QueryBuilder.ExcludeElevations = ">300" ' And include those points with identification numbers ' 100 through 200 inclusive, and point number 206. oPtGroup.QueryBuilder.IncludeNumbers = "100-200,206"

To create a group that contains every point in the document, set the boolean AeccPointGroup.InlcudeAllPoints property to True.

Using Point Groups

Once a point group has been created, you can perform actions upon all the points in that group in a single operation. You can override point elevations, descriptions, styles, and label styles.
' Check to see if a particular point exists in the group. If (oPtGroup.ContainsPoint(oPoint1.Number) = False) Then Debug.Print oPoint1.Name & " is not in the point group." End If ' Set the elevation of all the points in the group to 100. oPtGroup.Elevation = 100 oPtGroup.OverrideElevation = True

Point groups can also be used to define or modify a TIN surface. The AeccTinSurface.PointGroups property is a collection of point groups. When a point group is added to the collection, every point in the point group is added to the TIN surface.
' oTinSurf is a valid object of type AeccTinSurface. ' oPointGroup is a valid object of type AeccPointGroup. oTinSurf.PointGroups.Add oPointGroup

Sample Program
SurfacePointsSample.dvb
<installation-directory>\Sample\Civil 3D API\Vba\SurfacePoints\SurfacePointsSample.dvb The sample code from this section can be found in context in the SurfacePointsSample.dvb program. The Points module contains functions that load points from a text file, create points manually, use description keys, deal with point groups, and use points to modify a surface. The PointStyles module demonstrates the creation of a point style and a point label style.

Using Point Groups | 41

Surfaces

Object Hierarchy

Using the Surfaces Collection

All surfaces in a drawing are located in the AeccDocument.Surfaces collection. Each surface in the collection can be accessed through the AeccSurfaces.Item method, which takes either an integer index or the string name of the surface. The AeccSurfaces.Item method returns a generic reference of type AeccSurface, so you need to check the AeccSurface.Type property to actually determine what kind of surface it is. This sample examines each surface in the drawing and reports what kind of surface it is:
Dim oSurface As AeccSurface Dim i As Integer For i = 0 To oAeccDocument.Surfaces.Count - 1 Set oSurface = oAeccDocument.Surfaces.Item(i) Select Case (oSurface.Type) Case aecckGridSurface: Dim oGridSurface As AeccGridSurface Set oGridSurface = oSurface Debug.Print oGridSurface.Name & ": Grid" Case aecckTinSurface: Dim oTinSurface As AeccTinSurface Set oTinSurface = oSurface Debug.Print oTinSurface.Name & ": TIN" Case aecckGridVolumeSurface: Dim oGridVolume As AeccGridVolumeSurface Set oGridVolume = oSurface Debug.Print oGridVolume.Name & ": Grid Volume" Case aecckTinVolumeSurface: Dim oTinVolume As AeccTinVolumeSurface Set oTinVolume = oSurface Debug.Print oTinVolume.Name & ": TIN Valume" End Select Next i

Creating a Surface
This section covers the various methods for creating surfaces. Loading surfaces from LandXML files, .TIN files, or DEM files is explained. It also demonstrates creating new TIN, grid, and volume surfaces.

Creating a Surface From a LandXML File

A surface saved as a LandXML file can be loaded using the AeccSurfaces.ImportXML method. The file also describes the kind of surface to be created, so you do not need to know beforehand. After the surface has been loaded, you can examine the AeccSurface.Type property and assign the generic surface reference to a more specific type.

44 | Chapter 4 Surfaces

Dim oSurface As AeccSurface Dim sFileName As String sFileName = "C:\My Documents\EG.xml" Set oSurface = oAeccDocument.Surfaces.ImportXML(sFileName) Dim oTinSurface as AeccTinSurface If (oSurface.Type = aecckTinSurface) Then Set oTinSurface = oSurface End If

Creating a TIN Surface

Creating a Surface From a .tin File
The AeccSurfaces.ImportTIN method can create a new TIN surface from a binary .tin file.
Dim oTinSurface As AeccTinSurface Dim sFileName As String sFileName = "C:\My Documents\EG.tin" oTinSurface = oAeccDocument.Surfaces.ImportTIN(sFileName)

Creating a Surface Using AddTinSurface

You can also create empty TIN surfaces by adding to the documents collection of surfaces through the AeccSurfaces.AddTinSurface method. This method requires preparing an object of type AeccTinCreationData. It is important to specify every property of the AeccTinCreationData object to avoid errors.
' Create a blank surface using the first layer in the ' document's collection of layers and the first ' surface style in the document's collection of ' surface styles. Dim oTinSurface As AeccTinSurface Dim oTinData As New AeccTinCreationData oTinData.Name = "EG" oTinData.Description = "Sample TIN Surface" oTinData.Layer = oAeccDocument.Layers.Item(0).Name oTinData.BaseLayer = oAeccDocument.Layers.Item(0).Name oTinData.Style = oAeccDocument.SurfaceStyles.Item(0).Name Set oTinSurface = oAeccDocument.Surfaces .AddTinSurface(oTinData)

Creating a Grid Surface

Creating a Surface From a DEM File
A grid surface can be generated from a DEM file using the AeccSurfaces.ImportDEM method. NOTE The conversion process between the raster information and a surface can be slow. Be sure to indicate this to the user.

Creating a TIN Surface | 45

Dim oGridSurface As AeccGridSurface Dim sFileName As String sFileName = "C:\My Documents\file.dem" oGridSurface = oAeccDocument.Surfaces.ImportDEM(sFileName)

Creating a Surface From AddGridSurface

A blank grid surface can be created using the AeccSurfaces.AddGridSurface method. Before you can use this method you need to prepare an object of type AeccGridCreationData, which describes the nature of the surface to be created. It is important to specify every property of the AeccGridCreationData object to avoid errors. Units for XSpacing, YSpacing and Orientation are specified in the ambient settings.
Dim oGridSurface As AeccGridSurface Dim oGridCreationData As New AeccGridCreationData oGridData.Name = "Sample Grid Surface" oGridData.Description = "Grid Surface" oGridData.BaseLayer = oAeccDocument.Layers.Item(0).Name oGridData.Layer = oAeccDocument.Layers.Item(0).Name oGridData.Orientation = 0# oGridData.XSpacing = 100# oGridData.YSpacing = 100# oGridData.Style = oAeccDocument.SurfaceStyles.Item(0).Name Set oGridSurface = oAeccDocument.Surfaces _ .AddGridSurface(oGridData)

Creating a Volume Surface

A volume surface represents the mathematical difference between two TIN surfaces or between two grid surfaces in the document. It is created using the AeccSurfaces.AddTinVolumeSurface or AeccSurfaces.AddGridVolumeSurface methods. Each of these methods require the creation of objects (AeccGridVolumeCreationData or AeccTinVolumeCreationData) that describe the new volume surface. It is important to specify every property of these objects to avoid errors. Units for XSpacing, YSpacing and Orientation are specified in the ambient settings. This sample demonstrates the creation of a TIN volume surface from two existing surfaces, oTinSurfaceL and oTinSurfaceH:

46 | Chapter 4 Surfaces

' Get the names of the layer and style to be used. Dim sLayerName as String sLayerName = g_oAeccDocument.Layers.Item(0).Name Dim sStyleName as String sStyleName = oAeccDocument.SurfaceStyles.Item(0).Name ' Create a AeccTinVolumeCreationData object and set all its ' properties. Dim oTinVolumeCreationData As New AeccTinVolumeCreationData oTinVolumeCreationData.Name = "VS" oTinVolumeCreationData.BaseLayer = sLayerName oTinVolumeCreationData.Layer = sLayerName Set oTinVolumeCreationData.BaseSurface = oTinSurfaceL Set oTinVolumeCreationData.ComparisonSurface = oTinSurfaceH oTinVolumeCreationData.Style = oTinVolumeCreationData.Description = "Volume Surface" ' Create a new TIN volume surface. Dim oTinVolumeSurface As AeccTinVolumeSurface Set oTinVolumeSurface = oAeccDocument.Surfaces _ .AddTinVolumeSurface(oTinVolumeCreationData)

Working with Surfaces

This section covers the various methods for modifying or examining all types of surfaces. This includes adding a boundary, adding information to an existing surface from a DEM file, and using snapshots to improve surface performance.

Adding a Boundary
A boundary is a closed polyline that defines the visibility of surface triangles within it. A boundary can hide all triangles outside it, hide all triangles inside it, or show triangles inside it that would otherwise be hidden. Boundaries also change surface statistics such as area and number of triangles. Boundaries can either be destructive (totally hiding triangles that cross the boundary) or non-destructive (clipping triangle edges at the point where they cross the boundary). Normally, TIN surfaces use non-destructive boundaries, while grid surfaces can only have destructive boundaries:

Working with Surfaces | 47

Non-destructive Boundary

Destructive Boundary

All boundaries applied to a surface are stored in the AeccSurface.Boundaries collection. The boundary itself is defined by an AutoCAD entity such as a closed POLYLINE or POLYGON. The height of the entity plays no part in how surface triangles are clipped, so you can use 2D entities. This entity can also contain curves, but the boundary always consists of lines. How these lines are tessellated is defined by the mid-ordinate distance, which is the maximum distance between a curve and the lines that are generated to approximate it:

Mid-ordinate Distance

This sample adds a square outside boundary to a surface:

48 | Chapter 4 Surfaces

' First we need an AutoCAD entity (in this case a polyline) ' which describes the boundary location. Dim oPoly As AcadPolyline Dim dPoints(0 To 11) As Double dPoints(0) = 1000: dPoints(1) = 1000: dPoints(2) = 0 dPoints(3) = 1000: dPoints(4) = 4000: dPoints(5) = 0 dPoints(6) = 4000: dPoints(7) = 4000: dPoints(8) = 0 dPoints(9) = 4000: dPoints(10) = 1000: dPoints(11) = 0 Set oPoly = oAeccDocument.Database.ModelSpace _ .AddPolyline(dPoints) oPoly.Closed = True ' The name of the boundary object. Dim sName as String sName = "Sample Boundary" ' The third parameter describes what the boundary does ' to triangles inside it. The fourth parameter is True ' if you want non-destructive boundary or false otherwise. ' The final parameter is the mid-ordinate distance. Dim oNewBoundary As AeccSurfaceBoundary Set oNewBoundary = oSurface.Boundaries.Add(oPoly, sName, _ aeccBoundaryOuter, True, 10.5)

NOTE Any operation that causes the formation of new triangles (such as adding points or breaklines to a TIN surface) may result in triangles that cross existing boundary lines. Boundaries should always be added after every other operation that adds points to a surface.

Adding Data from DEM Files

Any number of DEM files can be added to existing grid and TIN surfaces. When a DEM file is added to the AeccGridSurface.DEMFiles or AeccTinSurface.DEMFiles collection, its information is converted to an evenly spaced lattice of triangles that is added to the surface.
oTinSurface.DEMFiles.Add("C:\My Documents\file.dem")

Improving Performance By Using Snapshots

A surface is made up of all the operations that modified the surfaces triangles. If you rebuild the surface, re-performing all these operations can be slow. Snapshots can improve performance by recording all the triangles in a surface. Subsequent rebuilds start from the data of the snapshot, thus saving time by not performing complicated calculations that have already been done once. Surfaces have CreateSnapshot, RebuildSnapshot, and RemoveSnapshot methods. Both CreateSnapshot and RebuildSnapshot will overwrite an existing snapshot. TIP RebuildSnapshot will cause an error if the snapshot does not exist. CreateSnapshot and RebuildSnapshot can also cause errors if the surface is out-of-date.

Finding Intersections
When working with surfaces, it can be useful to determine where a vector intersects with a surface, which you can do with the surfaces IntersectPointWithSurface() method. For example, you can determine if

Adding Data from DEM Files | 49

the top of a structure is visible from a point on the surface, or whether one point on the surface is visible from another point. This example tests whether a vector starting at (20424.7541, 20518.0409, 100) pointing in direction (0.6, 0.4, -0.5) intersects with the first surface in the drawing, and if it does, it prints out the intersection location:
Dim objSurf As AeccSurface Dim varStartPt As Variant, varDir As Variant, varIntPt As Variant Dim darrStart(2) As Double Dim darrDir(2) As Double darrStart(0) = 20424.7541 darrStart(1) = 20518.0409 darrStart(2) = 100 darrDir(0) = 0.6 darrDir(1) = 0.4 darrDir(2) = -0.5 varStartPt = darrStart varDir = darrDir Set objSurf = g_oAeccDoc.Surfaces(0) varIntPt = objSurf.IntersectPointWithSurface(varStartPt, varDir) If UBound(varIntPt) = 2 Then Debug.Print varIntPt(0), varIntPt(1), varIntPt(2) End If

Working with TIN Surfaces

This section covers the various methods for modifying or examining existing TIN surfaces. This includes adding new point data directly, adding breaklines, and adding contours.

Adding Point Data to a TIN Surface

There are two techniques for adding points that are unique to TIN surfaces: using point files and using point groups.

Adding Points Using Point Files

The AeccTinSurface.PointFiles collection contains the names of text files that contain point information. These text files must consist only of lines containing the point number, easting, northing, and elevation delineated by spaces. Except for comment lines beginning with #, any other information will result in an error. Unlike TIN or LandXML files, text files do not contain a list of faces - the points are automatically joined into a series of triangles based on the settings of the AeccTinSurface.DefinitionProperties property.
' Add points from a .txt file to an existing TIN surface. sFileName = "C:\My Documents\points.txt" oTinSurface.PointFiles.Add sFileName

Adding Points Using Point Groups

You can manually add points to a TIN surface by adding point groups to the AeccTinSurface.PointGroups collection.

50 | Chapter 4 Surfaces

' Make a surface consisting of 30 random points. To do ' this, first add 30 points to the document's collection ' of points, then make a point group from those points. ' Finally, add that point group to the surface. Dim i As Integer For i = 0 To 29 Dim pt(0 To 2) As Double pt(0) = Int(5000 * Rnd()) pt(1) = Int(5000 * Rnd()) pt(2) = Int(200 * Rnd()) Dim oPoint As AeccPoint Set oPoint = oAeccDocument.Points.Add(pt) oPoint.Name = "Point" & CStr(i) Next i Dim oPtGroup As AeccPointGroup Set oPtGroup = oAeccDocument.PointtGroups.Add("Random group") ' Add all points with a name beginning with "Point" oPtGroup.QueryBuilder.IncludeNames = "point*" ' Add the point group to the surface. oTinSurface.PointGroups.Add oPtGroup oTinSurface.Update

You can also add points to a surface by adding contour lines. See Adding Contours to a TIN Surface (page 53). All points that make up a surface can be retrieved from the read-only AeccTinSurface.Points property, which is an array of locations.
' Print the location (easting, northing, and elevation) ' of the 1000th point. Dim vLocation as Variant vLocation = oTinSurface.Points(1000) ' Now vLocation contains a 3 element array of doubles. Debug.Print "Easting:"; vLocation(0) Debug.Print "Northing:"; vLocation(1) Debug.Print "Elevation:"; vLocation(2)

Adding a Breakline to a TIN Surface

Breaklines are used to shape the triangulation of a TIN surface. Each TIN surface has a collection of breaklines contained in the AeccTinSurface.Breaklines property. There are different kinds of breaklines, and each is created in a slightly different way. NOTE For more information about breaklines, see Breaklines in the AutoCAD Civil 3D Users Guide.

Adding a Standard Breakline

A standard breakline consists of an array of 3D lines or polylines. Each line endpoint becomes a point in the surface and surface triangles around the breakline are redone. If the polyline contains curves, then the curve is tessellated based on the mid-ordinate distance parameter.

Adding a Breakline to a TIN Surface | 51

' Create the polyline basis for the breakline. Dim o3DPoly as Acad3DPolyline Dim dPoints(0 To 8) As Double dPoints(0) = 1200: dPoints(1) = 1200: dPoints(2) = 150 dPoints(3) = 2000: dPoints(4) = 3000: dPoints(5) = 120 dPoints(6) = 3000: dPoints(7) = 2000: dPoints(8) = 100 Set o3DPoly = oAeccDocument.Database.ModelSpace _ .Add3DPoly(dPoints) o3DPoly.Closed = False Dim oBreakline As AeccSurfaceBreakline Dim vBLines As Variant ' This has to be an array, even if we only have one entity. Dim oEntityArray(0) As AcadEntity Set oEntityArray(0) = oAeccDocument.Database.ModelSpace _ .Add3DPoly(dPoints) Set oBreakline = oTinSurface.Breaklines.AddStandardBreakline _ (oEntityArray, "Sample Standard Break", 1#)

Adding a Proximity Breakline

A proximity breakline does not add new points to a surface. Instead, the nearest surface point to each breakline endpoint is used. The triangles that make up a surface are then recomputed making sure those points are connected. A proximity breakline is created using the same fashion as standard breaklines except you call AeccSurfaceBreaklines.AddProximityBreakline instead of AeccSurfaceBreaklines.AddStandardBreakline.
Set oBreakline = oTinSurface.Breaklines.AddProximityBreakline( _ oEntityArray, _ "Sample Proximity Break", _ 1#)

Adding a Non-destructive Breakline

A non-destructive breakline does not remove any triangle edges. It places new points along the breakline at each intersection with a triangle edge and new triangles are computed. Again, it is created like standard breaklines are created except you call the AeccSurfaceBreaklines.AddNonDestructiveBreakline method.
Set oBreakline = oTinSurface.Breaklines _ .AddNonDestructiveBreakline( _ oEntityArray, _ "Sample Non-Destructive Break", _ 1#)

Adding a Wall Breakline

A wall breakline is used when the height of the surface on one side of the breakline is different than the other side. This method creates two breaklines, one for the top of the wall and one for the bottom. However, you cannot have a perfectly vertical wall in a TIN surface. The first breakline is placed along the path specified by the BreaklineEntities parameter, and the second breakline is very slightly offset to one side and raised or lowered by a relative elevation. Among the parameters of the wall breakline creation method are an array of wall elevations and an array describing to which side the height-adjusted breakline is placed. The wall at

52 | Chapter 4 Surfaces

each entity endpoint is offset to the right if the value is set to True and to the left of the value is set to False where right and left refer to directions as you walk along the breakline from the start point to the end.
' This is an array of arrays of elevations, one array of ' elevations per entity. Dim vElevations(0) As Variant ' These are the elevations of the wall at each endpoint in ' the polyline entity. Dim dElevations(3) As Double ' This is an array of ooleans, one for each entity. Dim bOffsets(0) As Boolean dElevations(0) = 30.5: dElevations(1) = 93.3 dElevations(2) = 93.3: dElevations(3) = 46.2 vElevations(0) = dElevations ' Raise the surface at the right side of the breakline. bOffsets(0) = True: bOffsets(1) = True bOffsets(2) = True: bOffsets(3) = True Set oBreakline = oTinSurf.Breaklines.AddWallBreakline _ (oEntityArray, _ "Sample Wall Break", _ 1#, _ vElevations, _ bOffsets)

Importing Breaklines from a File

You can import breaklines from a file in .FLT format, using AeccSurfaceBreaklines.AddBreaklineFromFile(). When you import the file, you need to specify whether to maintain the file link, or break the link:
aeccBreaklineFileMaintainLink: Reads the breaklines from the FLT file when they are added and when

the surface is rebuilt.

aeccBreaklineFileBreakLink: All breaklines in the FLT file are copied into the surface as Add Breakline

operations. For more information about these options, see Importing Breaklines from a File in the AutoCAD Civil 3D Users Guide. This sample shows how to import breaklines from a file named eg1.flt, and to get the first newly created breakline:
Dim oBrkLine As AeccSurfaceBreakline Set oBrkLine = brkLines.AddBreaklineFromFile("New Breakline", "C:\eg1.flt", 10#, aeccBreak lineFileBreakLink)(0)

Adding Contours to a TIN Surface

A contour is an open or closed entity that describes the altitude of the surface along the entity. Contours must have a constant altitude. The z value of the first point of the entity is used as the altitude of entire entity, no matter what is specified in the following points. Contours also have settings that can adjust the number of points added to the surface - when you create a contour, you specify a weeding distance, a weeding angle, and a distance parameter. Points in the contour are removed if the distance between the points before and after is less than the weeding distance and if the angle between the lines before and after is less than

Adding Contours to a TIN Surface | 53

the weeding angle. Each line segment is split into equal sections with a length no greater than the supplemental distance parameter. Any curves in the entity are also tessellated according to the mid-ordinate distance, just like breaklines. The supplemental distance value has precedence over the weeding values, so it is possible that the final contour will have line segments smaller than the weeding parameters specify. For more information about weeding and countours, see Weeding and Supplementing Factors for Contours in the AutoCAD Civil 3D Users Guide. A TIN surface has a collection of contours in the AeccTinSurface.Contours property. The following sample demonstrates adding a contour to a surface:
Dim dPoints(0 To 8) As Double ' 3 points Dim o3DPoly As AcadPolyline dPoints(0) = 2500: dPoints(1) = 1500: dPoints(2) = 100 dPoints(3) = 2600: dPoints(4) = 1600: dPoints(5) = 100 ' It does not matter that we specify a Z value of 50. It ' is still located at an altitude of 100, just like ' the first point. dPoints(6) = 2400: dPoints(7) = 1600: dPoints(8) = 50 Set o3DPoly = oAeccDocument.Database.ModelSpace _ .AddPolyline(dPoints) o3DPoly.Closed = False Dim oEntities(0) As AcadEntity Set oEntities(0) = o3DPoly Dim dWeedDist as Double Dim dWeedAngle as Double Dim dDist as Double Dim dMidOrdDist as Double dWeedDist = 55.5 dWeedAngle = 0.0698 ' 0.0698 radians = 4 degrees dDist = 85.5 dMidOrdDist = 1# Dim oNewContour As AeccSurfaceContour Set oNewContour = oTinSurf.Contours.Add(oEntities, _ "Sample Contour", dWeedDist, dWeedAngle, dDist, dMidOrdDist)

Extracting Contours from a TIN Surface

You can extract a contour (or contours) from a surface in a given elevation range as AutoCAD entities. This example extracts the contours between 90 and 95, and prints out the entity type for each one. NOTE The contours that you wish to extract must be visible in the drawing for this example to work.

54 | Chapter 4 Surfaces

... Dim z As Double Dim objSurf As AeccSurface Set objSurf = g_oAeccDoc.Surfaces(0) Dim varObjects As Variant Dim objEnt As AcadEntity Dim iCtr As Integer, iLow As Integer, iHigh As Integer varObjects = objSurf.ExtractContour(aeccDisplayOrientationPlan, aeccSFMajorContours, 90, 95) iLow = LBound(varObjects) iHigh = UBound(varObjects) For iCtr = iLow To iHigh Set objEnt = varObjects(iCtr) Debug.Print TypeName(objEnt) Next iCtr

Surface Style
This section explains the creation and application of surface styles.

Creating a Style
All surface styles are stored in the AeccDocument.SurfaceStyles collection, an object of type AeccSurfaceStyles. To create a new style, call the AeccSurfaceStyles.Add method with the name of your new style. It is initially set according to the documents ambient settings.
Dim oSurfaceStyle As AeccSurfaceStyle oSurfaceStyle = oDocument.SurfaceStyles.Add("New Style")

Changing a Surface Style

A surface style consists of different objects governing the appearance of boundaries, contours, direction analysis, elevation analysis, grids, points, slope arrows, triangles, and watershed analysis. Usually a single style only displays some of these objects. When initially created, a style is set according to the documents ambient settings and may show some unwanted style elements. Always set the visibility properties of all style elements to ensure the style behaves as you expect.

Surface Style | 55

' Change the style so that it displays surface triangles, ' major contour lines, and any boundaries along the outside ' edge, but nothing else. oSurfaceStyle.TriangleStyle.DisplayStylePlan.Visible = True oSurfaceStyle.BoundaryStyle.DisplayExteriorBoundaries = True oSurfaceStyle.BoundaryStyle.DisplayStylePlan.Visible = True oSurfaceStyle.ContourStyle.MajorContourDisplayStylePlan _ .Visible = True oSurfaceStyle.PointStyle.DisplayStylePlan.Visible = False oSurfaceStyle.BoundaryStyle.DisplayInteriorBoundaries = False oSurfaceStyle.ContourStyle.MinorContourDisplayStylePlan _ .Visible = False oSurfaceStyle.ContourStyle.UserContourDisplayStylePlan _ .Visible = False oSurfaceStyle.GridStyle.DisplayStylePlan.Visible = False oSurfaceStyle.DirectionStyle.DisplayStylePlan.Visible = False oSurfaceStyle.ElevationStyle.DisplayStylePlan.Visible = False oSurfaceStyle.SlopeStyle.DisplayStylePlan.Visible = False oSurfaceStyle.SlopeArrowStyle.DisplayStylePlan.Visible = False oSurfaceStyle.WatershedStyle.DisplayStylePlan.Visible = False ' This must be repeated for all Model display styles as well.

Assigning a Style to a Surface

Set the AeccSurface.Style property to the name of the style you wish to use.
' The surface is displayed according to the ' oSurfaceStyle style we have just created. oSurface.Style = oSurfaceStyle.Name

Performing Surface Analysis

This section shows you how to perform an elevation analysis and a watershed analysis.

Creating an Elevation Analysis

An elevation analysis creates a 2-dimensional projection of a surface and then add bands of color indicating ranges of altitude. The analysis is managed by an object of type AeccSurfaceAnalysisElevation, located in the AeccSurface.SurfaceAnalysis.ElevationAnalysis property. This object contains a method for creating elevation regions and a read-only collection containing these regions. The method, CalculateElevationRegions, creates a series of contiguous regions each representing a portion of the surfaces total elevation. Each time it is called it discards all existing elevation regions for the surface and creates a new collection of regions. The collection, ElevationRegions, lets you modify the color, minimum elevation, and maximum elevation of each region. Always check the number of regions through the AeccSurfaceAnalysisElevation.ElevationRegions.Count property as CalculateElevationRegions may create fewer regions than specified by the first parameter.
CalculateElevationRegions creates regions according to the statistical method specified in the AeccSurfaceStyle.ElevationStyle.GroupValuesBy property. The elevation style object also contains other

means of modifying how elevation analyses are made, such as using one of the preset color schemes.

56 | Chapter 4 Surfaces

This sample creates an elevation analysis for a surface using shades of green:
Dim oSurfaceAnalysisElevation As AeccSurfaceAnalysisElevation Set oSurfaceAnalysisElevation = oSurface.SurfaceAnalysis _ .ElevationAnalysis Dim oElevationRegions As AeccElevationRegions Set oElevationRegions = oSurfaceAnalysisElevation _ .CalculateElevationRegions(6, False) ' See exactly how many regions were created. Debug.Print oSurfaceAnalysisElevation.ElevationRegions.Count oElevationRegions.Item(0).Color oElevationRegions.Item(1).Color oElevationRegions.Item(2).Color oElevationRegions.Item(3).Color oElevationRegions.Item(4).Color = = = = = 80 ' bright green 82 84 86 88 ' dark green

' Adjust the range of one of the regions. oElevationRegions.Item(2).MaximumElevation = _ oElevationRegions.Item(2).MaximumElevation - 5

Many elevation analysis features can be modified through the surface style - see the Surface Style (page 55) section. For example, you can choose from among a number of pre-set color schemes.

Creating a Watershed Analysis

A watershed analysis predicts how water will flow over and off a surface. The analysis is managed by an object of type AeccSurfaceAnalysisWatershed held in the AeccSurface.SurfaceAnalysis.WatershedAnalysis property. The analysis is created by calling the AeccSurfaceAnalysisWatershed.CalculateWatersheds method. This splits the surface into separate regions, each with its own drain target or targets. The set of all these regions are held in the AeccSurfaceAnalysisWatershed.WatershedRegions collection. You have some control over how the regions are split. If the boolean AeccSurfaceAnalysisWatershed.MergeAdjacentBoundaries property is set to True, then regions along the boundary are merged into one region if their boundary points or segments touch. If a depression on the surface has a minimum average depth smaller than the value of the AeccSurfaceAnalysisWatershed.MergeDepression property, then the depression does not become its own region and is combined with the region it drains into.
oSurface.SurfaceAnalysis.WatershedAnalysis _ .MergeAdjacentBoundaries = True oSurface.SurfaceAnalysis.WatershedAnalysis _ .MergeDepression = 10.65

Types of Watershed Regions

Depending on the nature of the drain target, each watershed region is a different type derived from AeccWatershedRegion. (For more information about watershed region types, see Types of Watersheds in the AutoCAD Civil 3D Users Guide). By checking the Type property of each object in the AeccSurfaceAnalysisWatershed.WatershedRegions collection, you can then determine the specific type of each region.

Creating a Watershed Analysis | 57

' Compute water drainage over the surface. oSurface.SurfaceAnalysis.WatershedAnalysis _ .CalculateWatersheds ' Extract information from each watershed region. ' Loop through all the regions in the WatershedRegions ' collection. For each region, determine its ' specific type. Once we cast each region object to this ' specific type, we can learn how water drains over the ' surface. Dim oWSAnalysis As AeccWatershedRegions Set oWSAnalysis = oSurface.SurfaceAnalysis.WatershedAnalysis _ .WatershedRegions Dim i as Integer For i = 0 To oWSAnalysis.Count - 1 Select Case (oWSAnalysis.Item(i).Type) Case aeccWatershedBoundaryPoint Dim oWSPoint As AeccWatershedRegionBoundaryPoint Set oWSPoint = oWSAnalysis.Item(i) Case aeccWatershedBoundarySegment Dim oWSSegment As AeccWatershedRegionBoundarySegment Set oWSSegment = oWSAnalysis.Item(i) Case aeccWatershedDepression Dim oWSDepression As AeccWatershedRegionDepression Set oWSDepression = oWSAnalysis.Item(i) Case aeccWatershedFlat Dim oWSFlat As AeccWatershedRegionFlat Set oWSFlat = oWSAnalysis.Item(i) Case aeccWatershedMultiDrain Dim oWSMulti As AeccWatershedRegionMultiRegionDrain Set oWSMulti = oWSAnalysis.Item(i) Case aeccWatershedMultiDrainNotch Dim oWSNotch As AeccWatershedRegionMultiRegionDrainNotch Set oWSNotch = oWSAnalysis.Item(i) Case Else 'aeccWatershedUnknownSink End Select Next i

Objects derived from AeccWatershedRegion have other common features. They all have an identification number in the AeccWatershedRegion.Id property. They also have a AeccWatershedRegion.Boundary property, which contains a 2-dimensional array containing the points of a closed polygon enclosing the region.

58 | Chapter 4 Surfaces

Dim vBound As Variant vBound = oWSAnalysis.Item(i).BoundaryLine For j = 0 To UBound(vBound) ' Print the X, Y and Z coordinates of a border point. Debug.Print vBound(j, 0), vBound(j, 1), vBound(j, 2) Next j

Boundary Point Regions

In a region of type AeccWatershedBoundaryPoint, water reaches the boundary of a surface at a single point. The X, Y, and Z coordinates of this point are held in a variant array in the AeccWatershedBoundaryPoint.BoundaryDrainPoint property.
Dim oWSPoint As AeccWatershedRegionBoundaryPoint Set oWSPoint = oWSAnalysis.Item(i) Dim vDrainPoint As Variant vDrainPoint = oWSPoint.BoundaryDrainPoint Debug.Print "This region drains to point: " & vDrainPoint(0) _ & ", " & vDrainPoint(1) & ", " & vDrainPoint(2)

Boundary Segment Regions

Regions of type aeccWatershedBoundarySegment represent areas where water flows out of a surface along a series of line segments. The end points of these line segments are held in a 2-dimensional array of doubles in the aeccWatershedBoundarySegment.BoundaryDrainSegment property. The first dimension of this array represents each point and the second dimension are the X, Y, and Z coordinates of the points.
Dim oWSSegment As AeccWatershedRegionBoundarySegment Set oWSBoundarySegment = oWSAnalysis.Item(i) Dim vDrainSegments as Variant vDrainSegments = oWSBoundarySegment.BoundaryDrainSegment Dim j as Integer Debug.Print "This region drains through the following" Debug.Print "line segments:" For j = 0 To UBound(vDrainSegments, 1) - 1 Debug.Print vDrainSegments(j, 0) & ", " _ & vDrainSegments(j, 1) & ", " _ & vDrainSegments(j, 2) & " to "; Debug.Print vDrainSegments(j + 1, 0) & ", " _ & vDrainSegments(j + 1, 1) _ & ", " & vDrainSegments(j + 1, 2) Next j

Depression Regions
A region of type aeccWatershedDepression represents an area of the surface that water does not normally leave. It is possible for the depression to fill and then drain into other regions. The lowest points on the region edge where this overflow may take place and the regions that the water drains into are kept in the aeccWatershedDepression.Drains collection.

Creating a Watershed Analysis | 59

Dim Set Dim Set

oWSDepression As AeccWatershedRegionDepression oWSDepression = oWSAnalysis.Item(i) oDrains As AeccWatershedDrains oDrains = oWSDepression.Drains

For j = 0 To oDrains.Count - 1 ' See what kind of drain targets we have. If (UBound(oDrains.Item(j).Targets) = -1) Then ' This depression drains outside the surface. Debug.Print "Drain through point: " & _ oDrains.Item(j).Location(0) & ", " & _ oDrains.Item(j).Location(1) & ", " & _ oDrains.Item(j).Location(2) & _ " to the surface boundary." Else ' This depression can drain into other regions. Dim lTargets() As Long lTargets = oDrains.Item(j).Targets sTargets = CStr(lTargets(0)) Dim k as Integer For k = 1 To UBound(lTargets) sTargets = sTargets & ", " & CStr(lTargets(k)) Next k Debug.Print "Drain through point: " & _ oDrains.Item(j).Location(0) & ", " & _ oDrains.Item(j).Location(1) & ", " & _ oDrains.Item(j).Location(2) & _ " into the following regions: " & sTargets Endif Next j

Flat Regions
A flat area that only drains into one region is combined into that region. If a flat surface drains into multiple regions, then it is created as a separate region of type AeccWatershedRegionFlat. The only feature of flat regions is an array of all drain targets.
Dim oWSFlat As AeccWatershedRegionFlat Set oWSFlat = oWSAnalysis.Item(i) varDrainsInto = oWSFlat.DrainsInto sTargets = CStr(varDrainsInto(0)) For k = 1 To UBound(varDrainsInto) sTargets = sTargets & ", " & CStr(varDrainsInto(k)) Next k Debug.Print "This region drains into regions " & sTargets

Multiple Drain Regions (Point)

A region of the surface may drain through a point into many different regions. Such regions are represented by an object of type AeccWatershedRegionMultiRegionDrain. These regions have properties containing the point water drains through and a collection of all regions into which water flows.

60 | Chapter 4 Surfaces

Dim oWSMulti As AeccWatershedRegionMultiRegionDrain Set oWSMulti = oWSAnalysis.Item(i) ' vDrainPoint is a single point, like BoundaryPoint vDrainPoint = oWSMulti.DrainPoint ' varDrainsInto is an array of variants, each a region ID. varDrainsInto = oWSMulti.DrainsInto sTargets = CStr(varDrainsInto(0)) For k = 1 To UBound(varDrainsInto) sTargets = sTargets & ", " & CStr(varDrainsInto(k)) Next k Debug.Print "This region drains to point: " & vDrainPoint(0) _ & ", " & vDrainPoint(1) & ", " & vDrainPoint(2) _ & " and into the following regions: " & sTargets

Multiple Drain Regions (Notch)

A region can also drain into many other regions through a series of line segments. These regions are represented by an object of type AeccWatershedRegionMultiRegionDrainNotch and they keep both a list of all regions this region drains into and a list of all segments this region drains through.
Dim oWSNotch As AeccWatershedRegionMultiRegionDrainNotch Set oWSNotch = oWSAnalysis.Item(i) ' vDrainSegments is a 2-dimensional array, like BoundarySegment. Dim vDrainSegments As Variant vDrainSegments = oWSNotch.DrainSegment ' varDrainsInto is an array of region IDs. Dim varDrainsInto As Variant varDrainsInto = oWSNotch.DrainsInto sTargets = CStr(varDrainsInto(0)) For k = 1 To UBound(varDrainsInto) sTargets = sTargets & ", " & CStr(varDrainsInto(k)) Next k Debug.Print "This region drains through these segments: " For j = 0 To UBound(vDrainSegments, 1) - 1 Debug.Print vDrainSegments(j, 0) & ", " _ & vDrainSegments(j, 1) & ", " _ & vDrainSegments(j, 2) & " to "; Debug.Print vDrainSegments(j + 1, 0) & ", " _ & vDrainSegments(j + 1, 1) _ & ", " & vDrainSegments(j + 1, 2) Next j ' Display each region this drains into. Debug.Print "and into the following regions: " & sTargets

Sample Programs
SurfacePointsSample.dvb
<installation-directory>\Sample\Civil 3D API\Vba\SurfacePoints\SurfacePointsSample.dvb

Sample Programs | 61

This sample program demonstrates the creation of surfaces using point data loaded from a file and through use of point groups. Surface styles are created and applied.

SurfaceOperations.dvb
<installation-directory>\Sample\Civil 3D API\Vba\SurfaceOperations\SurfaceOperationsSample.dvb This sample demonstrates the elevation analysis and watershed analysis features. The watershed analysis includes a full report of all watershed regions. Breaklines of all kinds, contours, and borders are applied to the surfaces as well.

CorridorSample.dvb
<installation-directory>\Sample\Civil 3D API\Vba\Corridor\CorridorSample.dvb A TIN volume surface is created between the corridor datum surface and the ground surface. Cut and fill information is obtained from this volume surface.

62 | Chapter 4 Surfaces

Sites and Parcels

Object Hierarchy

Sites
This section explains the creation and use of sites, which are used as containers for parcels and alignments (for information about alignments, see Chapter 6: Alignments (page 71)).

Creating Sites
All sites in a document are held in the AeccDocument.Sites collection, an object of type AeccSites. The AeccSites.Add method creates a new empty site with the specified name.
' Create a new site. Dim oSites As AeccSites Set oSites = oAeccDocument.Sites Dim oSite As AeccSite Set oSite = oSites.Add("Sample Site")

Using Sites
A site represents a distinct group of alignments and parcels. Besides containing collections of parcels and alignments, the AeccSite object also contains properties describing how the site objects are numbered and displayed.
' NextAutoCounterParcel sets the starting identification ' number for newly created parcels. The first parcel ' created from parcel segments will be 300, the next 301, ' and so on. oSite.NextAutoCounterParcel = 300

Parcels
This section covers the creation and use of parcels. Parcel segments, parcel loops, and parcel styles and label styles are also explained.

Creating Parcels with Parcel Segments

While a site contains a collection of parcels, this collection has no Add method. Instead, parcels are automatically generated from the parcel segments added to the AeccSite.ParcelSegments collection. A parcel segment is a 2-dimensional line, curve, or AutoCAD entity. Once a closed structure can be formed from the segments in the site, a parcel is automatically formed. Each additional parcel segment that forms new closed structures creates additional parcels. This may affect the shape of existing parcels - if an existing parcel is bisected by a new segment, the existing parcel is reduced in size and a new parcel is formed.

64 | Chapter 5 Sites and Parcels

Dim oSegments as AeccParcelSegments Set oSegments = oSite.ParcelSegments ' Parcel 1 Call oSegments.AddLine(0, 0, 0, 200) Call oSegments.AddCurve(0, 200, -0.5, 200, 200) Call oSegments.AddLine(200, 200, 200, 0) Call oSegments.AddLine(200, 0, 0, 0) ' Parcel 2 Call oSegments.AddCurve2(200, 200, 330, 240, 400, 200) Call oSegments.AddLine(400, 200, 400, 0) ' This will complete parcel 2, as well as form parcel 3. Dim oPolyline As AcadPolyline Dim dPoints(0 To 8) As Double dPoints(0) = 400: dPoints(1) = 0: dPoints(2) = 0 dPoints(3) = 325: dPoints(4) = 25: dPoints(5) = 0 dPoints(6) = 200: dPoints(7) = 0: dPoints(8) = 0 Set oPolyline = oAeccDocument.Database.ModelSpace_ .AddPolyline(dPoints) oPolyline.Closed = True ' Passing True as the second parameter deletes the ' polyline entity once the parcel segment has been created. Call oSegments.AddFromEntity(oPolyline, True)

About Parcel Segments

Each parcel segment is a collection of parcel segment elements, which are represented by objects derived from the AeccParcelSegmentElement base class. A segment element is an undivided part of a segment that can be used to create a parcel. When an element is intersected by another parcel segment, the element is split into two contiguous elements:
Dim oSegments as AeccParcelSegments Set oSegments = oSite.ParcelSegments Dim oSegment1 as AeccParcelSegment ' Segment1 consists of 1 element, a line with endpoints ' at 500,100 to 600,100 Set oSegment1 = oSegments.AddLine(500, 100, 600, 100) ' We can tell this by looking at the number of elements: Debug.Print oSegment1.Count ' returns 1 ' If we cross the segment element with another segment, ' then the elements get split. Call oSegments.AddLine(550, 150, 550, 50) Debug.Print oSegment1.Count ' returns 2

The AeccParcelSegment.Item method returns each element as an object of type AeccParcelSegmentElement. This object has no Type property, so to determine what kind of element it represents you need to directly check the object type with the TypeOf operator:

About Parcel Segments | 65

' Loop through all elements of the parcel segment "oSegment" Dim i as Integer For i = 0 to oSegment.Count - 1 Dim oElement As AeccParcelSegmentElement Set oElement = oSegment.Item(i) Debug.Print "Element " & i & ": " _ & oElement.StartX & "," & oElement.StartY & " to " _ & oElement.EndX & ", " & oElement.EndY If (TypeOf oElement Is AeccParcelSegmentLine) Then Dim oSegmentLine As AeccParcelSegmentLine Set oSegmentLine = oElement Debug.Print " is a line. " ElseIf (TypeOf oElement Is AeccParcelSegmentCurve) Then Dim oSegmentCurve As AeccParcelSegmentCurve Set oSegmentCurve = oElement Debug.Print " is a curve with a radius of:" _ & oSegmentCurve.Radius End If Next i

Determining Parcel Loops

You can determine which parcel segment elements make up a parcel by using the AeccParcel.ParcelLoops collection. This collection stores objects of type AeccParcelSegmentElement. Each parcel segment element contains a reference to the parent segment, so you can also determine which segments are used to create a parcel.

66 | Chapter 5 Sites and Parcels

' Loop through all elements used to make parcel "oParcel" Dim i as Integer For i = 0 to oParcel.ParcelLoops.Count - 1 Dim oElement As AeccParcelSegmentElement Set oElement = oParcel.ParcelLoops.Item(i) Debug.Print "Element " & i _ & " of segment " & oElement.ParcelSegment.Name & ": " _ & oElement.StartX & "," & oElement.StartY & " to " _ & oElement.EndX & ", " & oElement.EndY If (TypeOf oElement Is AeccParcelSegmentLine) Then Dim oSegmentLine As AeccParcelSegmentLine Set oSegmentLine = oElement Debug.Print " is a line. " ElseIf (TypeOf oElement Is AeccParcelSegmentCurve) Then Dim oSegmentCurve As AeccParcelSegmentCurve Set oSegmentCurve = oElement Debug.Print " is a curve with a radius of:" _ & oSegmentCurve.Radius End If Next i

Parcel Style and Parcel Segment Style

The collection of all parcel styles is held in the AeccDocument.ParcelStyles collection. The parcel style controls how a parcel and the parcel segments are displayed. Among the features is an option to only fill the area close to a parcels borders. A parcel style can be assigned to a parcel through the AeccParcel.Style property. This sample creates a parcel style, sets the style properties, and assigns the style to the parcel object oParcel:
Dim oParcelStyles As AeccParcelStyles Set oParcelStyles = oDocument.ParcelStyles Dim oParcelStyle As AeccParcelStyle Set oParcelStyle = oParcelStyles.Add("Sample Style") oParcelStyle.ObservePatternFillDistance = True oParcelStyle.PatternFillDistance = 20 oParcelStyle.SegmentsDisplayStylePlan.color = 20 ' red-orange oParcelStyle.AreaFillDisplayStylePlan.color = 20 oParcelStyle.AreaFillDisplayStylePlan.Visible = True oParcelStyle.AreaFillDisplayStylePlan.Lineweight = 20 oParcelStyle.AreaFillHatchDisplayStylePlan.UseAngleOfObject = True oParcelStyle.AreaFillHatchDisplayStylePlan.ScaleFactor = 3.8 oParcelStyle.AreaFillHatchDisplayStylePlan.Spacing = 1.5 oParcelStyle.AreaFillHatchDisplayStylePlan.Pattern = "AR-SAND" oParcelStyle.AreaFillHatchDisplayStylePlan.HatchType = aeccHatchPreDefined ' Assign the "Sample Style" style to a single parcel. oParcel.Style = oParcelStyle.Name

The style of individual parcel segments depends on the style of the parent parcel, but segments may be shared by different parcels. This conflict is decided by the AeccParcels.Properties.SegmentDisplayOrder property, which is a collection of all parcel styles currently in use. These styles are arranged according to priority level. When two parcels with different styles share a segment, the segment is displayed with the

Parcel Style and Parcel Segment Style | 67

higher priority style. Among these styles is the global site parcel style, set through the AeccParcels.Properties.SiteParcelStyle property. The site parcel style defines the outside boundary style of parcels within the site, given a high enough priority. This sample displays the current order of parcel styles in the site and then modifies the order:
' List all styles used by parcels in this site with their ' priority Dim oSegmentDisplayOrder As AeccSegmentDisplayOrder Set oSegmentDisplayOrder = _ oSite.Parcels.Properties.SegmentDisplayOrder Debug.Print "Number styles used:"; oSegmentDisplayOrder.Count Debug.Print "Priority of each style for affecting segments:" Dim i as Integer For i = 0 To oSegmentDisplayOrder.Count - 1 Debug.Print i; " & oSegmentDisplayOrder.Item(i).Name Next i ' Set the style with the highest priority to the lowest ' priority. Dim lLowestPosition as Long lLowestPosition = oSegmentDisplayOrder.Count - 1 oSegmentDisplayOrder.SetPriority 0, lLowestPosition

Parcel Label Style

The style of text labels or graphical markers displayed with parcels and parcel segments are set by assigning a label style object to the AeccParcel.AreaLabelStyle property. All such label styles are held in the AeccDocument.ParcelLabelStyles.AreaLabelStyles property, a collection of AeccLabelStyle objects. Parcel label styles can use the following property fields in the contents of any text component: Valid property fields for AeccLabelStyleTextComponent.Contents
<[Name(CU)]> <[Description(CP)]> <[Parcel Area(Usq_ft|P2|RN|AP|Sn|OF)]> <[Parcel Number(Sn)]> <[Parcel Perimeter(Uft|P3|RN|AP|Sn|OF)]> <[Parcel Address(CP)]> <[Parcel Site Name(CP)]> <[Parcel Tax ID(Sn)]>

Label styles are described in detail in the chapter 1 section Label Styles (page 13).

68 | Chapter 5 Sites and Parcels

Parcel User-Defined Properties

Parcel objects can have user-defined properties associated with them, and the properties can be organized into user-defined classifications, or are put into an Unclassified classification. You can create new classifications and user-defined properties via the API, though you cant access the values of existing user-defined properties attached to parcels. For more information about user-defined properties and classifications, see User-Defined Property Classifications in the AutoCAD Civil 3D User Guide. This sample creates a new user-defined property classification for parcels called Example, and then adds a new user-defined property with upper and lower bounds and a default value:
Dim oApp As AcadApplication Set oApp = ThisDrawing.Application ' NOTE - Always specify the version number. Const sAppName = "AeccXUiLand.AeccApplication.6.0" Set g_vCivilApp = oApp.GetInterfaceObject(sAppName) Set g_oDocument = g_vCivilApp.ActiveDocument Set g_oAeccDb = g_oDocument.Database Dim oUDPClass As AeccUserDefinedPropertyClassification Dim oUDPProp As AeccUserDefinedProperty 'Create a user-defined parcel property classification Set oUDPClass = g_oAeccDb.ParcelUserDefinedPropertyClassifications.Add("Example") ' Add a Property to our new classification An integer using upper ' and lower bound limits of 10 and 20 with a default value of 15 Set oUDPProp = oUDPClass.UserDefinedProperties.Add("Extra Data", _ "Some Extra Data", aeccUDPPropertyFieldTypeInteger, True, False, 10, True, _ False, 20, True, 15, Null)

Accessing Daylight Feature Lines

The AeccSite:FeatureLines property is a collection of grading feature lines in the drawing. This collection only contains the types of feature lines available through the Prospector on the AutoCAD Civil 3D user interface. The collection doesnt contain daylight or projection feature lines. However, you can still get information about these types of feature lines programmatically by prompting the user to select feature line object in a drawing. This code sample prompts the user to select a feature line, and then prints out the number of points it contains:

Parcel User-Defined Properties | 69

Dim objPart As AeccLandFeatureLine Dim objEnt As AcadObject Dim objAcadEnt As AcadEntity Dim varPick As Variant ThisDrawing.Utility.GetEntity objEnt, varPick, "Select the polyline/feature line" If TypeOf objEnt Is AeccLandFeatureLine Then Set objPart = objEnt Debug.Print TypeName(objPart) Dim varArray As Variant varArray = objPart.GetPoints() Debug.Print "Number of points = " & UBound(varArray) ElseIf TypeOf objEnt Is AcadEntity Then Set objAcadEnt = objEnt Debug.Print TypeName(objAcadEnt) If (g_oAeccDoc.Sites.Count = 0) Then g_oAeccDoc.Sites.Add "TestSite" End If Set objPart = g_oAeccDoc.Sites(0).FeatureLines.AddFromPolyline(objAcadEnt.ObjectID, "Standard") End If

Sample Program
ParcelSample.dvb
<installation-directory>\Sample\Civil 3D API\Vba\Parcel\ParcelSample.dvb This sample program accesses the active document, creates a site, and then creates three parcels by adding line segments, curve segments, and entity segments. A new parcel style is composed and applied to one of the parcels.

70 | Chapter 5 Sites and Parcels

Alignments

Object Hierarchy

Alignment Object Model

Basic Alignment Operations

Creating an Alignment
Alignments are usually created in existing sites. Each AeccSite object has its own collection of alignments held in an AeccAlignments object in the AeccSite.Alignments property. There is also a collection of alignments that are not associated with a site in the AeccDocument.AlignmentsSiteless property.

Creating a New Alignment

The AeccAlignments object provides two ways of creating new alignments. The AeccAlignments.Add method takes an alignment name, a layer to draw to, an alignment style object, and an alignment label style object

72 | Chapter 6 Alignments

as parameters and returns a new empty alignment. The AeccAlignments.AddFromPolyline method takes the same parameters as well as an AutoCAD polyline entity and flags indicating whether curves should be added between the separate line segments and whether the polyline entity should be erased after the alignment is created. This code creates an alignment from a 2D polyline, using existing styles:
' Create an alignment style with default settings. Dim oAlignmentStyle as AeccAlignmentStyle Set oAlignmentStyle = oDocument.AlignmentStyles _ .Add("Sample style") ' Create an alignment label style with default settings. Dim oAlignmentLabelStyleSet As AeccAlignmentLabelStyleSet Set oAlignmentLabelStyleSet = oAeccDocument.AlignmentLabelStyleSets _ .Add("Sample label style") ' Get the collection of all siteless alignments. Dim oAlignments as AeccAlignments Set oAlignments = oDocument.AlignmentsSiteless ' Create an empty alignment that draws to layer 0. Dim oAlignment as AeccAlignment Set oAlignment = oAlignments.Add("Sample Alignment", "0", _ oAlignmentStyle.Name, oAlignmentLabelStyleSet.Name)

' Create a simple 2D polyline. Dim oPoly As AcadLWPolyline Dim dPoints(0 To 5) As Double dPoints(0) = 0: dPoints(1) = 600 dPoints(2) = 600: dPoints(3) = 0 dPoints(4) = 1200: dPoints(5) = 600 Set oPoly = oDocument.Database.ModelSpace _ .AddLightWeightPolyline(dPoints) ' Create an alignment from the polyline object. Draw to ' layer 0, erase the polyline when we are done, and ' insert curves between line segments. Set oAlignment = oAlignments.AddFromPolyline( _ "Sample Alignment from Polyline", _ "0", _ oPoly.ObjectID, _ oAlignmentStyle.Name, _ oAlignmentLabelStyleSet.Name, _ True, _ True)

Creating an Alignment Offset From Another Alignment

Alignments can also be created based on the layout of existing alignments. The AeccAlignment.Offset method creates a new alignment with a constant offset and adds it to the same parent site as the original alignment. The new alignment has the same name (followed by a number in parenthesis) and the same style as the original, but it does not inherit any station labels, station equations, or design speeds from the original alignment.

Creating an Alignment | 73

' Add an offset alignment 10.5 units to the left of the ' original. oAlignment.Offset -10.5

Defining an Alignment Path Using Entities

An alignment is made up of a series of entities, which are individual lines, curves, and spirals that make up the path of an alignment. A collection of entities is held in the AeccAlignment.Entities collection. This collection has a wide array of methods for creating new entities. The following code sample demonstrates some of the entity creation methods:
' Define the points used to create the entities. Dim point1(0 To 2) As Double Dim point2(0 To 2) As Double Dim point3(0 To 2) As Double point1(0) = 200: point1(1) = 800: point1(2) = 0 point2(0) = 600: point1(1) = 400: point1(2) = 0 point3(0) = 1000: point1(1) = 800: point1(2) = 0 ' Create a line segment entity that connects two points. Dim oAlignmentTangent As AeccAlignmentTangent Set oAlignmentTangent = oAlignment.Entities _ .AddFixedLine1(point1, point2) ' Print the length of the line segment. Debug.Print oAlignmentTangent.Length ' Create a curve entity that connects the second endpoint ' of the fixed line to another point. The radius of the ' curve depends on the direction of the fixed line and the ' location of the second endpoint. Dim oAlignmentArc As AeccAlignmentArc Set oAlignmentArc = oAlignment.Entities _ .AddFloatingCurve6(oAlignmentTangent.id, point3) ' Print the angle of direction at the second endpoint. Debug.Print oAlignmentArc.EndDirection

Determining Entities Within an Alignment

Each of the entities in the AeccAlignment.Entities collection is a type derived from the AeccAlignmentEntity. By checking the AeccAlignmentEntity.Type property, you can determine the specific type of each entity and cast the reference to the correct type. The following sample loops through all entities in an alignment, determines the type of entity, and prints one of its properties.

74 | Chapter 6 Alignments

Debug.Print "Number of Entities: "; oAlignment.Entities.Count Dim i as Integer For i = 0 To oAlignment.Entities.Count - 1 Select Case (oAlignment.Entities.Item(i).Type) Case aeccTangent Dim oTangent As AeccAlignmentTangent Set oTangent = oAlignment.Entities.Item(i) Debug.Print "Tangent length:" & oTangent.Length Case aeccArc Dim oArc As AeccAlignmentArc Set oArc = oAlignment.Entities.Item(i) Debug.Print "Arc radius:" & oArc.Radius Case aeccSpiral Dim oSpiral As AeccAlignmentSpiral Set oSpiral = oAlignment.Entities.Item(i) Debug.Print "Spiral A value:" & oSpiral.A Case aeccSpiralCurveSpiralGroup Dim oSCSGroup As AeccAlignmentSCSGroup Set oSCSGroup = oAlignment.Entities.Item(i) Debug.Print "Radius of curve in SCS group:" _ & oSCSGroup.Arc.Radius ' And so on for AeccAlignmentSTSGroup, ' AeccAlignmentSTGroup, AeccAlignmentTSGroup ' AeccAlignmentSCGroup, and AeccAlignmentCSGroup types. End Select Next i

Each entity has an identification number contained in its AeccAlignmentEntity.Id property. Each entity knows the numbers of the entities before and after it in the alignment, and you can access specific entities by identification number through the AeccAlignmentEntities.EntityAtId method.

Stations
Modifying Stations with Station Equations
A station is a point along an alignment a certain distance from the start of the alignment. By default the station at the start point of an alignment is 0 and increases contiguously through its length. This can be changed by using station equations, which can renumber stations along an alignment. A station equation is an object of type AeccStationEquation which contains a location along the alignment, a new station number basis, and a flag describing whether station values should increase or decrease from that location on. A collection of these station equations is contained in the AeccAlignment.StationEquations property. The following code changes an alignment so that at a point 80 units from the beginning, stations will start being numbered from the value 720:
Dim oStationEquation As AeccStationEquation Set oStationEquation = oAlignment.StationEquations _ .Add(80, 0, 720, aeccIncreasing)

NOTE Some functions, such as AeccAlignment.InstantaneousRadius, require a raw station value without regard to modifications made by station equations.

Stations | 75

Creating Station Sets

Alignment stations are usually labeled at regular intervals. You can compute the number, location, and geometry of stations taken at regular spacings by using the AeccAlignment.GetStations method. This function returns a collection of stations based on the desired interval of major and minor stations and the type of station requested. Unless the type of station requested is aeccEquation, station values ignore any station equations.
Dim oStations As AeccAlignmentStations ' If we were to label major stations placed every 100 units ' and minor stations placed every 20, how many labels ' would this alignment have? Set oStations = oAlignment.GetStations(aeccAll, 100#, 20#) Debug.Print "Number of labels: " & oStations.Count ' Print the location of each major station in the set. Dim i as Integer For i = 0 To oStations.Count - 1 If (oStations.Item(i).Type = aeccMajor) Then Dim j As Integer Dim x As Integer Dim y As Integer j = oStations.Item(i).Station x = oStations.Item(i).Easting y = oStations.Item(i).Northing Debug.Print "Station " & j & " is at:" & x & ", " & y End If Next i

Specifying Design Speeds

You can assign design speeds along the length of an alignment to aid in the future design of a roadway based on the alignment. The collection of speeds along an alignment are contained in the AeccAlignment.DesignSpeeds property. Each item in the collection is an object of type AeccDesignSpeed, which contains a raw station value, a speed to be used from that station on until the next design speed specified or the end of the alignment, and an optional string comment.

76 | Chapter 6 Alignments

Dim oDesignSpeed As AeccDesignSpeed ' Starting at station 0 + 00.00 Set oDesignSpeed = oAlignment.DesignSpeeds.Add(0#) oDesignSpeed.Value = 45 oDesignSpeed.Comment = "Straightaway" ' Starting at station 4 + 30.00 Set oDesignSpeed = oAlignment.DesignSpeeds.Add(430#) oDesignSpeed.Value = 30 oDesignSpeed.Comment = "Start of curve" ' Starting at station 14 + 27.131 to the end. Set oDesignSpeed = oAlignment.DesignSpeeds.Add(1427.131) oDesignSpeed.Value = 35 oDesignSpeed.Comment = "End of curve" ' Make Alignment speed-based oAlignment.DesignSpeedBased = True

Superelevation
Another setting that can be applied to certain stations of an alignment is the superelevation, used to adjust the angle of roadway section components for corridors based on the alignment. The inside and outside shoulders and road surfaces can be adjusted for both the left and right sides of the road. The collection of all superelevation information for an alignment is stored in the AeccAlignment.SuperelevationData property. Note that, unlike most Civil 3D API collections, the Add method does not return a new default entity but instead passes a reference to the new object through the second parameter. An individual superelevation data element (type AeccSuperelevationDataElement) can be accessed through the AeccAlignment.SuperelevationAtStation method. This code creates a new superelevation data element at station 11+00.00 and sets the properties of that element:

Superelevation | 77

Dim oSuperElevationData As AeccSuperElevationData Dim oSuperElevationElem As AeccSuperElevationDataElem ' Create an element at station 11+00.0. A new default ' superelevation data element is assigned to our ' oSuperElevationElem variable. Set oSuperElevationData = oAlignment.SuperelevationData oSuperElevationData.Add 1100, oSuperElevationElem oSuperElevationElem.SegmentCrossSlope _ (aeccSuperLeftOutShoulderCrossSlope) = 0.05 oSuperElevationElem.SegmentCrossSlope _ (aeccSuperLeftOutLaneCrossSlope) = 0.02 oSuperElevationElem.SegmentCrossSlope _ (aeccSuperLeftInLaneCrossSlope) = 0.01 oSuperElevationElem.SegmentCrossSlope _ (aeccSuperLeftInShoulderCrossSlope) = 0.03 oSuperElevationElem.SegmentCrossSlope _ (aeccSuperRightInShoulderCrossSlope) = 0.03 oSuperElevationElem.SegmentCrossSlope _ (aeccSuperRightInLaneCrossSlope) = 0.01 oSuperElevationElem.SegmentCrossSlope _ (aeccSuperRightOutLaneCrossSlope) = 0.02 oSuperElevationElem.SegmentCrossSlope _ (aeccSuperRightOutShoulderCrossSlope) = 0.05 oSuperElevationElem.TransPointType = aeccSuperManual oSuperElevationElem.TransPointDesc = "Manual adjustment" oSuperElevationElem.RawStation = 1100

Each superelevation data element represents a point in the transition of the roadway cross section. A single transition from normal to full superelevation and back is a zone. A collection of data elements representing a single zone can be retrieved by calling the AeccAlignment.SuperelevationZoneAtStation method. This sample retrieves the data elements that are part of the superelevation zone starting at station 0+00.00, and prints all their descriptions:
Set oSuperElevationData = _ oAlignment.SuperelevationZoneAtStation(0) For Each oSuperElevationElem In oSuperElevationData Debug.Print oSuperElevationElem.TransPointDesc Next

Alignment Style
Creating an Alignment Style
A style governs many aspects of how alignments are drawn, including direction arrows and curves, spirals, and lines within an alignment. All alignment styles are contained in the AeccDocument.AlignmentStyles collection. Alignment styles must be added to this collection before being used by an alignment object. A style is normally assigned to an alignment when it is first created, but it can also be assigned to an existing alignment through the AeccAlignment.Style property.

78 | Chapter 6 Alignments

Dim oAlignmentStyle As AeccAlignmentStyle Set oAlignmentStyle = oAeccDocument.AlignmentStyles _ .Add("Sample alignment style") ' Do not show direction arrows. oAlignmentStyle.ArrowDisplayStylePlan.Visible = False oAlignmentStyle.ArrowDisplayStyleModel.Visible = False ' Show curves in violet. oAlignmentStyle.CurveDisplayStylePlan.color = 200 ' violet oAlignmentStyle.CurveDisplayStyleModel.color = 200 ' violet ' Show straight sections in blue. oAlignmentStyle.LineDisplayStylePlan.color = 160 ' blue oAlignmentStyle.LineDisplayStyleModel.color = 160 ' blue ' Assign the style to an existing alignment. oAlignment.Style = oAlignmentStyle.Name

Alignment Label Styles

The style of text labels and graphical markers displayed along an alignment are set by passing an AeccAlignmentLabelSet object when the alignment is first created with the AeccAlignments.Add and AeccAlignments.AddFromPolyline methods or by assigning the label set object to the AeccAlignment.LabelStyle property. The AeccAlignmentLabelSet object consists of separate sets of styles to be placed at major stations, minor stations, and where the alignment geometry, design speed, or station equations change. Labels at major stations are described in the AeccAlignmentLabelSet.MajorStationLabelSet property, which is a collection of AeccLabelMajorStationSetItem objects. Each AeccLabelMajorStationSetItem object consists of a single AeccLabelStyle object and a number of properties describing the limits of the labels and the interval between labels along the alignment. Labels at minor stations are described in the AeccAlignmentLabelSet.MinorStationLabelSet property, which is a collection of AeccLabelMinorStationSetItem objects. Each AeccLabelMinorStationSetItem object consists of a single AeccLabelStyle object and a number of properties describing the limits of the labels and the interval between labels along the alignment. When a new AeccLabelMinorStationSetItem is created it must reference a parent AeccLabelMajorStationSetItem object. Labels may be placed at the endpoints of each alignment entity. Such labels are controlled through the AeccAlignmentLabelSet.GeometryPointLabelSet property, an AeccLabelSet. The label set is a collection of AeccLabelStyle objects. Labels at each change in alignment design speeds and station equations (the AeccAlignmentLabelSet.GeometryPointLabelSet and AeccAlignmentLabelSet.GeometryPointLabelSet properties respectively) are also AeccLabelSet objects. All label styles at alignment stations can draw from the following list of property fields: Valid property fields for AeccLabelStyleTextComponent.Contents
<[Station Value(Uft|FS|P0|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Raw Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Northing(Uft|P4|RN|AP|Sn|OF)]> <[Easting(Uft|P4|RN|AP|Sn|OF)]>

Alignment Label Styles | 79

Valid property fields for AeccLabelStyleTextComponent.Contents

<[Design Speed(P3|RN|AP|Sn|OF)]> <[Instantaneous Direction(Udeg|FDMSdSp|MB|P4|RN|DSn|CU|AP|OF)]> <[Perpendicular Direction(Udeg|FDMSdSp|MB|P4|RN|DSn|CU|AP|OF)]> <[Alignment Name(CP)]> <[Alignment Description(CP)]> <[Alignment Length(Uft|P3|RN|AP|Sn|OF)]> <[Alignment Start Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Alignment End Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]>

Label styles for minor stations, geometry points, design speeds, and station equations can also use the following property fields:
<[Offset From Major Station(Uft|P3|RN|AP|Sn|OF)]> <[Geometry Point Text(CP)]> <[Geometry Point Entity Before Data(CP)]> <[Geometry Point Entity After Data(CP)]> <[Design Speed Before(P3|RN|AP|Sn|OF)]> <[Station Ahead(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Station Back(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Increase/Decrease(CP)]> Minor stations Geometry points Geometry points Geometry points Design speeds Station equations Station equations Station equations

Label styles are described in detail in the chapter 1 section Label Styles (page 13).

Sample Program
AlignmentSample.dvb
<installation-directory>\Sample\Civil 3D API\Vba\Alignment\AlignmentSample.dvb The sample code from this chapter can be found in context in the AlignmentSample.dbp project. This project can create alignments based on AutoCAD polyline entities or through layout commands. It demonstrates using styles, label styles, station equations, design speeds, and superelevation.

80 | Chapter 6 Alignments

Profiles

Object Hierarchy

Profile Object Model

Profiles
This section covers the creation and style of profiles. Profiles are the vertical analogue to alignments. Together, an alignment and a profile represent a 3D path.

82 | Chapter 7 Profiles

Creating a Profile From a Surface

A profile is an object consisting of elevations along an alignment. Each alignment contains a collection of profiles in its AeccAlignment.Profiles property. The AeccProfiles.AddFromSurface creates a new profile and derives its elevation information from the specified surface along the path of the alignment.
Dim oProfiles As AeccProfiles Set oProfiles = oAlignment.Profiles Dim oProfile As AeccProfile ' Add a new profile for the alignment "oAlignment" based ' on the elevations of the surface "oSurface". Set oProfile = oProfiles.AddFromSurface( _ "Profile01", _ aeccExistingGround, _ oProfileStyle.Name, _ oSurface.Name, _ oAlignment.StartingStation, _ oAlignment.EndingStation, _ "0")

Creating a Profile Using Entities

The AeccProfiles.Add method creates a new profile with no elevation information. The vertical shape of a profile can then be specified using entities. Entities are geometric elements - tangents or symmetric parabolas. The collection of all entities that make up a profile are contained in the AeccProfile.Entities collection. AeccProfile.Entities also contains all the methods for creating new entities. This sample creates a new profile along the alignment oAlignment and then adds three entities to define the profile shape. Two straight entities are added at each end and a symmetric parabola is added in the center to join them and represent the sag of a valley.

Creating a Profile From a Surface | 83

Dim oProfiles As AeccProfiles Set oProfiles = oAlignment.Profiles Dim oProfile As AeccProfile ' NOTE: The second parameter (aeccFinishedGround) indicates ' that the shape of the profile is not drawn from the existing ' surface. We will define the profile ourselves. Set oProfile = oProfiles.Add _ ("Profile03", _ aeccFinishedGround, _ oProfileStyle.Name) ' Now add the entities that define the profile. ' NOTE: Profile entity points are not x,y,z point, but ' station-elevation locations. Dim dLoc1(0 To 1) As Double Dim dLoc2(0 To 1) As Double Dim oProfileTangent1 As aeccProfileTangent dLoc1(0) = oAlignment.StartingStation: dLoc1(1) = -40# dLoc2(0) = 758.2: dLoc2(1) = -70# Set oProfileTangent1 = oProfile.Entities.AddFixedTangent _ (dLoc1, dLoc2) Dim oProfileTangent2 As aeccProfileTangent dLoc1(0) = 1508.2: dLoc1(1) = -60# dLoc2(0) = oAlignment.EndingStation: dLoc2(1) = -4# Set oProfileTangent2 = oProfile.Entities.AddFixedTangent _ (dLoc1, dLoc2) Dim dCrestLen As Double dCrestLen = 900.1 Call oProfile.Entities.AddFreeSymmetricParabolaByLength _ (oProfileTangent1.Id, _ oProfileTangent2.Id, _ aeccSag, _ dCrestLen, _ True)

Editing Points of Vertical Intersection

The point where two adjacent tangents would cross (whether they actually cross or not) is called the point of vertical intersection, or PVI. This location can be useful for editing the geometry of a profile because this one point controls the slopes of both tangents and any curve connecting them. The collection of all PVIs in a profile are contained in the AeccProfile.PVIs property. This object lets you access, add, and remove PVIs from a profile, which can change the position and number of entities that make up the profile. Individual PVIs (type AeccProfilePVI) do not have a name or id, but are instead identified by a particular station and elevation. The collection methods AeccProfilePVIs.ItemAt and AeccProfilePVIs.RemoveAt access or delete the PVI closest to the station and elevation parameters so you do not need the exact location of the PVI you want to modify. This sample identifies the PVI closest to a specified point. It then adds a new PVI to profile created in the Creating a Profile Using Entities (page 83) topic and adjusts its elevation.

84 | Chapter 7 Profiles

Dim oPVI As AeccProfilePVI ' Find the PVI close to station 1000 elevation -70. Set oPVI = Nothing Set oPVI = oProfile.PVIs.ItemAt(1000, -70) Debug.Print "PVI closest to station 1000 is at station: "; Debug.Print oPVI.Station ' Add another PVI and slightly adjust its elevation. Set oPVI = oProfile.PVIs.Add(607.4, -64.3, aeccProfileTangent) oPVI.Elevation = oPVI.Elevation - 2#

Creating a Profile Style

The profile style, an object of type AeccProfileStyle, defines the visual display of profiles. The collection of all such styles in a document are stored in the AeccDocument.LandProfileStyles property. The style contains objects of type AeccDisplayStyle which govern the display of arrows showing alignment direction and of the lines, line extensions, curves, parabolic curve extensions, symmetrical parabolas and asymmetrical parabolas that make up a profile. The properties of a new profile style are defined by the documents ambient settings.
Dim oProfileStyle As AeccProfileStyle Set oProfileStyle = oDocument.LandProfileStyles .Add("Profile Style 01") ' For all profiles that use this style, line elements ' will be yellow, curve elements will be shades of green, ' and extensions will be dark grey. No arrows will be shown. With oProfileStyle .ArrowDisplayStyleProfile.Visible = False .LineDisplayStyleProfile.Color = 50 ' yellow .LineDisplayStyleProfile.Visible = True .LineExtensionDisplayStyleProfile.Color = 251 ' grey .LineExtensionDisplayStyleProfile.Visible = True .CurveDisplayStyleProfile.Color = 80 ' green .CurveDisplayStyleProfile.Visible = True .ParabolicCurveExtensionDisplayStyleProfile.Color = 251 ' grey .ParabolicCurveExtensionDisplayStyleProfile.Visible = True .SymmetricalParabolaDisplayStyleProfile.Color = 81 ' green .SymmetricalParabolaDisplayStyleProfile.Visible = True .AsymmetricalParabolaDisplayStyleProfile.Color = 83 ' green .AsymmetricalParabolaDisplayStyleProfile.Visible = True End With ' Properties for 3d display should also be set.

Profile Views
This section describes the creation and display of profile views. A profile view is a graph displaying the elevation of a profile along the length of the related alignment.

Creating a Profile Style | 85

Creating a Profile View

A profile view, an object of type AeccProfileView, is a graphical display of profiles within a graph. A collection of profile views is contained in each alignments AeccAlignment.ProfileViews property.
Dim dOriginPt(0 To 2) As Double dOriginPt(0) = 6000 ' X location of profile view dOriginPt(1) = 3500 ' Y location dOriginPt(2) = 0 ' Z location ' Use the first profile view style in the document. Dim oProfileViewStyle As AeccProfileViewStyle Set oProfileViewStyle = oDocument.ProfileViewStyles.Item(0) Dim oProfileView as AeccProfileView Set oProfileView = oAlignment.ProfileViews.Add( _ "Profile Style 01", _ "0", _ dOriginPt, _ oProfileViewStyle, _ Nothing) ' "Nothing" means do not include data bands.

Creating Profile View Styles

The profile view style, an object of type AeccProfileViewStyle, governs all aspects of how the graph axes, text, and titles are drawn. Within AeccProfileViewStyle are objects dealing with the top, bottom, left, and right axes; lines at geometric locations within profiles; and with the graph as a whole. All profile view styles in the document are stored in the AeccDocument.ProfileViewStyles collection. New styles are created using the collections Add method with the name of the new style.
Dim oProfileViewStyle As AeccProfileViewStyle Set oProfileViewStyle = oDocument.ProfileViewStyles _ .Add("Profile View style 01")

Setting Profile View Styles

The profile view style object consists of separate objects for each of the four axes, one object for the graph overall, and an AeccDisplayStyle object for grid lines displayed at horizontal geometry points. The axis styles and graph style also contain subobjects for specifying the style of tick marks and titles.

Setting the Axis Style

86 | Chapter 7 Profiles

Valid property fields for AeccAxisTitleStyle.Text

<[Profile View Maximum Elevation(Uft|P3|RN|AP|Sn|OF)]> <[Profile View Start Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Profile View End Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]>

Axis Tick Marks

Within each axis style are properties for specifying the tick marks placed along the axis. Both major tick marks and minor tick marks are represented by objects of type AeccTickStyle. AeccTickStyle manages the location, size, and visual style of tick marks through its Interval, Size and DisplayStylePlan properties. Note that while most style properties use drawing units, the Interval property uses the actual ground units of the surface. The AeccTickStyle object also sets what text is displayed at each tick, including the following property fields: Valid property fields for AeccTickStyle.Text
<[Station Value(Uft|FS|P0|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Raw Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Graph View Abscissa Value(Uft|P4|RN|AP|Sn|OF)]> <[Profile View Point Elevation(Uft|P1|RN|AP|Sn|OF)]> <[Graph View Ordinate Value(Uft|P3|RN|AP|Sn|OF)]>

Axis
horizontal horizontal horizontal vertical vertical

Setting the Graph Style

The graph is managed by an object of type AeccGraphStyle. This object can be used to change the grid and the title of the graph. The grid is controlled by the AeccGraphStyle.GridStyle property, an object of type AeccGridStyle. The grid style sets the amount of empty space above and below the extents of the section through the AeccGridStyle.GridsAboveMaxElevation and AeccGridStyle.GridsBelowDatum properties. The grid style also manages the line styles of major and minor vertical and horizontal gridlines with the AeccGridStyle properties MajorVerticalDisplayStylePlan, MajorHorizontalDisplayStylePlan, MinorVerticalDisplayStylePlan, and MinorHorizontalDisplayStylePlan. The AeccGridLines.VerticalPosition and AeccGridLines.HorizontalPosition properties tell which axis to use to position the grid lines.

Setting Profile View Styles | 87

Valid property fields for AeccGraphTitleStyle.Text

<[Parent Alignment(CP)]> <[Drawing Scale(P4|RN|AP|OF)]> <[Graph View Vertical Scale(P4|RN|AP|OF)]> <[Graph View Vertical Exageration(P4|RN|AP|OF)]> <[Profile View Start Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Profile View End Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Profile View Minimum Elevation(Uft|P2|RN|AP|Sn|OF)]> <[Profile View Maximum Elevation(Uft|P3|RN|AP|Sn|OF)]>

Profile View Style Example

This example takes an existing profile view style and modifies its top axis and title:

88 | Chapter 7 Profiles

' Get the first style in the document's collection of styles. Dim oProfileViewStyle as AeccProfileViewStyle Set oProfileViewStyle = oDocument.ProfileViewStyles.Item(0) ' Adjust the top axis. Put station information here, with ' the title at the far left. With oProfileViewStyle.TopAxis .DisplaySyle2d.Visible = True ' Modify the text to display meters in decimal ' format. .MajorTickStyle.Text = "<[Station Value(Um|FD|P1)]> m" .MajorTickStyle.Interval = 164.041995 Dim dPoint(0 To 2) As Double dPoint(0) = 0.13 dPoint(1) = 0# .TitleStyle.Offset = dPoint .TitleStyle.Text = "Meters" .TitleStyle.Position = aeccStart End With ' Adjust the title to show the alignment name. oProfileViewStyle.GraphStyle.TitleStyle.Text = _ "Profile View of:<[Parent Alignment(CP)]>"

Sample Programs
ProfileSample.dvb
<installation-directory>\Sample\Civil 3D API\Vba\Profile\ProfileSample.dvb This sample creates a surface from a file and an alignment using entities. It creates a profile based on the existing surface along the alignment. It then creates a second profile using entities and points of vertical intersection. A profile view is made displaying both profiles. The style and label style of the profile view are set with custom styles. Data bands are added to the profile view.

CorridorSample.dvb
<installation-directory>\Sample\Civil 3D API\Vba\Corridor\CorridorSample.dvb The CreateCorridor method of the Corridor module shows the creation of a profile using entities.

Sample Programs | 89

Sections

Object Hierarchy

Sample Lines
This section covers the creation and use of sample lines. Sample lines are line segments placed at regular intervals across an alignment. They can be used to define the location and orientation of surface cross sections that can be studied through section views.

Creating a Sample Line

Sample lines are line segments placed along an alignment, usually perpendicular to the alignment path and at regular intervals. Sample lines represent the location and orientation of surface cross sections that can be studied through section views. Sample lines are created in groups. All sample line groups for an alignment are held in the AeccAlignment.SampleLineGroups collection. The Add method for this collection creates a new empty group, and takes as parameters the name of the group, the layer the group will be drawn to, a style object for how groups of graphs are organized, a style object for the sample lines, and a label style object.

92 | Chapter 8 Sections

' Get all the styles we will need for our sample line object. ' We will use whatever default styles the document contains. Dim oGroupPlotStyle As AeccGroupPlotStyle Set oGroupPlotStyle = oDocument.GroupPlotStyles.Item(0) Dim oSampleLineStyle As AeccSampleLineStyle Set oSampleLineStyle = oDocument.SampleLineStyles.Item(0) Dim oSampleLineLabelStyle As AeccLabelStyle Set oSampleLineLabelStyle = oDocument _ .SampleLineLabelStyles.Item(0) Dim oSampleLineGroups As AeccSampleLineGroups Set oSampleLineGroups = oAlignment.SampleLineGroups ' Create a sample line group using the above styles and drawn ' to layer "0". Dim sLayerName as String sLayerName = "0" Dim oSampleLineGroup As AeccSampleLineGroup Set oSampleLineGroup = oSampleLineGroups.Add( _ "Example Sample Line Group", _ sLayerName, _ oGroupPlotStyle, _ oSampleLineStyle, _ oSampleLineLabelStyle)

Defining Sample Lines

Setup
The first step in creating sample lines along an alignment is to specify the surface or surfaces being sampled. This is accomplished by adding surfaces to the AeccSampleLineGroup.SampledSurfaces collection. The AeccSampledSurfaces.AddAllSurfaces method adds one AeccSampledSurface object to the collection for each surface in the document. The AeccSampledSurfaces.Add method takes a specific surface object and an AeccSectionStyle object and returns a reference to the added AeccSampledSurface object. It is important to then set the boolean AeccSampledSurface.Sample property to True. NOTE If no SampledSurface object added to the AeccSampledSurfaces collection has the Sample property set to True, then no sections will be generated for that sample line. This sample demonstrates how to add a single surface to a sample line group and how to add all surfaces in the drawing to a sample line group:

Defining Sample Lines | 93

' Get the section style we need for our sampled surface ' object. We use the default style of the document. Dim oSectionStyle As AeccSectionStyle Set oSectionStyle = oDocument.SectionStyles.Item(0) ' Get the surface object we will be sampling from. ' Assume there is a surface with the name "EG". Dim oSurface as AeccSurface Set oSurface = oDocument.Surfaces.Item("EG") ' This section demonstrates adding a single surface to ' the sample line group. An AeccSampleSurface object is ' returned, which needs some properties set. Dim oSampledSurface As AeccSampledSurface Set oSampledSurface = oSampleLineGroup.SampledSurfaces _ .Add(oSurface, oSectionStyle) oSampledSurface.UpdateMode = aeccSectionStateDynamic ' We need to set the Sample property of the ' SampledSurface object. Otherwise the sampled surface ' will not be used in creating sections. oSampledSurface.Sample = True

' This section demonstrates adding all surfaces in the ' document to the sample line group. oSampleLineGroup.SampledSurfaces.AddAllSurfaces oSectionStyle ' We need to set the Sample property of each ' SampledSurface object. Otherwise the sampled surfaces ' will not be used in creating sections. Dim i As Integer For i = 0 To oSampleLineGroup.SampledSurfaces.Count - 1 oSampleLineGroup.SampledSurfaces.Item(i).Sample = True Next i

At this point you can define sample lines. Sample lines are held in the AeccSampleLineGroup.SampleLines collection. There are three methods to add sample lines to the collection: AeccSampleLines.AddByPolyline, AeccSampleLines.AddByStation, and AeccSampleLines.AddByStationRange. The AeccSampledSurfaces collection can contain objects other than surfaces to be sampled in section views, such as pipe networks or corridors. These objects can be added from the AutoCAD Civil 3D user interface. (Currently you can only add surfaces to the AeccSampledSurfaces collection via the API.) Accessing these non-surface objects with the AeccSampledSurface.Surface property throws an exception, so you need to use the AeccSampledSurface.AcadEntity property, as in this example, where the second item in the collection is a pipe network:

94 | Chapter 8 Sections

Dim SampledSurfaces As AeccSampledSurfaces SampledSurfaces = aeccdb.Sites.Item(0).Alignments.Item(1).SampleLineGroups.Item(0).Sampled Surfaces Dim s1 As AeccSurface Dim e1 As AcadEntity Dim s2 As AeccPipeNetwork s1 = SampledSurfaces.Item(0).Surface e1 = SampledSurfaces.Item(1).AcadEntity ' Surface would throw exception MessageBox.Show(e1.ObjectName) s2 = e1 MessageBox.Show(s2.Name)

Adding a Sample Line from a Polyline

AddByPolyline lets you specify the location of a sample line based on an AutoCAD lightweight polyline

entity. This gives you great flexibility in designing the sample line. It can consist of many line segments at any orientation, and it does not have to be perpendicular to the alignment or even cross the alignment at all. The AddByPolyline method also lets you delete the polyline entity once the sample line has been created. AddByPolyline returns the AeccSampleLine object created.
Dim oPoly As AcadLWPolyline Dim dPoints(0 To 3) As Double ' Assume these coordinates are in one of the surfaces ' in the oSampleLineGroup.SampledSurfaces collection. dPoints(0) = 4750: dPoints(1) = 4050 dPoints(2) = 4770: dPoints(3) = 3950 Set oPoly = ThisDrawing.ModelSpace _ .AddLightWeightPolyline(dPoints) ' Now that we have a polyline, we can create a sample line ' with those coordinates. Delete the polyline when done. Call oSampleLineGroup.SampleLines.AddByPolyline _ ("Sample Line 01", oPoly, True)

Add a Sample Line at a Station

AddByStation creates a single sample line perpendicular to a particular alignment station. The AddByStation

method takes as parameters the name of the sample line, the station the line crosses, and the length of the line to the left and right sides of the alignment. AddByStation returns the AeccSampleLine object created.

Defining Sample Lines | 95

Dim dSwathWidthLeft As Double Dim dSwathWidthRight As Double Dim dStation As Double dSwathWidthRight = 45.5 dSwathWidthLeft = 35.5 dStation = 1100.5 Call oSampleLineGroup.SampleLines.AddByStation( _ "Sample Line 02", _ dStation, _ dSwathWidthLeft, _ dSwathWidthRight)

Add a Range of Sample Lines

AddByStationRange creates a series of sample lines along the alignment. The characteristics of the sample lines are defined by an object of type AeccStationRange. When first created, the AeccStationRange object

properties are set to default values, so be sure to set every property to the values you require. NOTE The AeccStationRange.SampleLineStyle property must be set to a valid object or the AddByStationRange method will fail. The AeccStationRange object is then passed to the AddByStationRange method along with a flag describing how to deal with duplicates. The sample lines are then generated and added to the AeccSampleLineGroup.SampleLines collection. This method has no return value. This sample adds a series of sample lines along a section of an alignment:

96 | Chapter 8 Sections

' Specify where the sample lines will be drawn. Dim oStationRange As New AeccStationRange oStationRange.UseSampleIncrements = True oStationRange.SampleAtHighLowPoints = False oStationRange.SampleAtHorizontalGeometryPoints = False oStationRange.SampleAtSuperelevationCriticalStations = False oStationRange.SampleAtRangeEnd = True oStationRange.SampleAtRangeStart = True oStationRange.StartRangeAtAlignmentStart = False oStationRange.EndRangeAtAlignmentEnd = False ' Only sample for 1000 units along part of the ' alignment. oStationRange.StartRange = 10# oStationRange.EndRange = 1010# ' sample every 200 units along straight lines oStationRange.IncrementTangent = 200# ' sample every 50 units along curved lines oStationRange.IncrementCurve = 50# ' sample every 50 units along spiral lines oStationRange.IncrementSpiral = 50# ' 50 units to either side of the station oStationRange.SwathWidthLeft = 50# oStationRange.SwathWidthRight = 50# oStationRange.SampleLineDefaultDirection = _ aeccDirectionFromBaseAlignment Set oStationRange.SampleLineStyle = oSampleLineStyle oSampleLineGroup.SampleLines.AddByStationRange _ "Sample Line 03", _ aeccSampleLineDuplicateActionOverwrite, _ oStationRange

Creating Sample Line Styles

In creating sample lines, you need to work with three different style objects that control how sample lines are displayed.

Group Plot Styles

The AeccGroupPlotStyle style controls how groups of section view graphs are drawn. The style changes the row and column orientation and spacing between multiple graphs. The collection of all AeccGroupPlotStyle styles is contained in the AeccDocument.GroupPlotStyles property.
Dim oGroupPlotStyle As AeccGroupPlotStyle Set oGroupPlotStyle = oDocument.GroupPlotStyles _ .Add("Example group plot style")

Sample Line Styles

The AeccSampleLineStyle style controls how sample lines are drawn on a surface. The collection of all AeccSampleLineStyle styles is contained in the AeccDocument.SampleLineStyles property.

Creating Sample Line Styles | 97

Dim oSampleLineStyle As AeccSampleLineStyle Set oSampleLineStyle = oDocument.SampleLineStyles _ .Add("Example sample line style") ' This style just changes the display of the sample line. oSampleLineStyle.LineDisplayStyleSection.color = 140 ' slate

Section Styles
The AeccSectionStyle style controls how surface cross sections are displayed in the section view graphs. The collection of all AeccSectionStyle styles is contained in the AeccDocument.SectionStyles property.
Dim oSectionStyle As AeccSectionStyle Set oSectionStyle = oDocument.SectionStyles _ .Add("Example cross section style") ' This style just changes the display of cross section ' lines. oSectionStyle.SegmentDisplayStyleSection.color = 110 ' green/blue

Creating Sample Line Label Styles

The style of sample line text labels, lines, and marks are controlled by an AeccLabelStyle object. The style can be set through the AeccSampleLine.LabelStyle property or by passing an AeccLabelStyle object when using the AeccSampleLineGroups.Add method. All labels styles for sample lines are stored in the AeccDocument.SampleLineLabelStyles collection. See the Root Objects chapter for more detailed information about the AeccLabelStyle class. Text labels for sample lines can use any of the following property fields: Valid property fields for AeccLabelStyleTextComponent.Contents
<[Sample Line Name(CP)]> <[Sample Line Number(Sn)]> <[Left Swath Width(Uft|P3|RN|AP|Sn|OF)]> <[Right Swath Width(Uft|P3|RN|AP|Sn|OF)]> <[Distance from Previous Sample Line(Uft|P3|RN|AP|Sn|OF)]> <[Sample Line Parent Alignment Name(CP)]> <[Sample Line Group(CP)]> <[Sample Line Station Value(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Sample Line Raw Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]>

Label styles are described in detail in the Chapter 1 section Label Styles (page 13).

98 | Chapter 8 Sections

Sections
This section covers the creation and use of sections. A section is a cross section of one or more surfaces along a sample line. A series of sections can be used to analyze the changes in a surface along a path.

Creating Sections
A section is a cross section of one or more surfaces taken along a sample line. You can either create sections one at a time using the AeccSampleLineGroup.CreateSectionsAtSampleLine method, or all at once using the AeccSampleLineGroup.CreateSectionsAtSampleLines method. These methods will cause an error if the sample line group does not reference any surfaces, or if the surface is not located under the sample lines specified.
' Create a section at the first sample line in the sample ' line group. ' oSampleLineGroup is of type AeccSampleLineGroup Dim oSampleLine as AeccSampleLine Set oSampleLine = oSampleLineGroup.SampleLines(0) oSampleLineGroup.CreateSectionsAtSampleLine oSampleLine ' Create a section for each sample line in the sample ' line group. oSampleLineGroup.CreateSectionsAtSampleLines

Using Sections
Each sample line contains a collection of sections that were based on that sample line. Each section is represented by object of type AeccSection and contains methods for retrieving statistics of the surface along the section. While sections initially have styles based on the AeccSectionStyle style passed to the AeccSampledSurfaces.Add method, you can also set the style for each section individually through the AeccSection.Style property.

Sections | 99

Dim oSampleLines as AeccSampleLines Set oSampleLines = oSampleLineGroup.SampleLines ' For each sample line, go through all the sections that ' were created based on it. Dim i As Integer Dim j As Integer For i = 0 To oSampleLines.Count - 1 Dim oSections As AeccSections Set oSections = oSampleLines.Item(i).Sections ' For each section, print its highest elevation and set ' some of its properties. Dim oSection as AeccSection For Each oSection in oSections Debug.Print "Max Elevation of "; oSection.Name; Debug.Print " is: "; oSection.ElevationMax oSection.DataType = aeccSectionDataTIN oSection.StaticDynamic = aeccSectionStateDynamic Next Next i

Section Views
This section describes the creation and display of section views. A section view is a graph of a single section. Usually a series of section views are displayed to demonstrate a range of cross sections.

Creating Section Views

A section view is a graph of the sections for a single sample. Each sample line contains a collection of section views in its AeccSampleLine.SectionViews property. To create a new section view, use the AeccSectionViews.Add method, which takes as parameters the name of the new section view, the layer to draw to, the location, the style of the view, and an optional data band set. Each section view is automatically constructed to display the sections at that sample line in the center of an appropriately sized graph. As each sample line may have different lengths and represent different surface altitudes, each section view may be different in size or in what units are displayed along each graph axis. This sample creates a row of section views from all sample lines in a given alignment:

100 | Chapter 8 Sections

Dim i As Integer Dim j As Integer ' Use the first section view style in the document. Dim oSectionViewStyle As AeccSectionViewStyle Set oSectionViewStyle = oDocument.SectionViewStyles.Item(0) ' Specify the starting location of the row of section ' views. Dim dX As Double Dim dY As Double dX = 6000 dy = 3500 ' We have an alignment with sample lines. Loop through ' all the sample line groups in the alignment. For i = 0 To oAlignment.SampleLineGroups.Count - 1 Dim oSampleLineGroup As AeccSampleLineGroup Set oSampleLineGroup = oAlignment.SampleLineGroups.Item(i) Dim oSampleLines As AeccSampleLines Set oSampleLines = oSampleLineGroup.SampleLines ' Now loop through all the sample lines in the current ' sample line group. For each sample line, we add a ' section view at a unique location with a style and ' a data band that we defined earlier. Dim dOffsetRight As Double dOffsetRight = 0 For j = 0 To oSampleLines.Count - 1 Dim oSectionView As AeccSectionView dOffsetRight = j * 300 Dim dOriginPt(0 To 2) As Double ' To the right of the surface and the previous ' section views. dOriginPt(0) = dX + 200 + dOffsetRight dOriginPt(1) = dY Set oSectionView=oSampleLines.Item(j).SectionViews.Add( _ "Section View" & CStr(j), _ "0", _ dOriginPt, _ oSectionViewStyle, _ Nothing) ' "Nothing" means do not display a data band Next j Next i

Creating Section View Styles

The section view style, an object of type AeccSectionViewStyle, governs all aspects of how the graph axes, text, and titles are drawn. Within AeccSectionViewStyle are objects dealing with the top, bottom, left, center vertical, and right axes and with the graph as a whole. All section view styles in the document are stored in the AeccDocument.SectionViewStyles collection. New styles are created using the collections Add method with the name of the new style.

Creating Section View Styles | 101

Dim oSectionViewStyle As AeccSectionViewStyle Set oSectionViewStyle = oDocument.SectionViewStyles _ .Add("Section View style")

Setting Section View Styles

The section view style object consists of separate objects for each of the four axes, one object for the graph overall, and an AeccDisplayStyle object for sample lines within the views. The axis styles and graph style also contain subobjects for specifying the style of tick marks and titles.

Setting the Axis Style

All axis styles are based on the AeccAxisStyle class. The axis style object controls the display style of the axis itself, tick marks and text placed along the axis, and a text annotation describing the purpose of the axis. The annotation text, location, and size is set through the AeccAxisStyle.TitleStyle property, an object of type AeccAxisTitleStyle. The annotation text can use any of the following property fields: Valid property fields for AeccAxisTitleStyle.Text
<[Section View Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Section View Width(Uft|P2|RN|AP|Sn|OF)]> <[Left Width(Uft|P2|RN|AP|Sn|OF)]> <[Right Width(Uft|P2|RN|AP|Sn|OF)]> <[Elevation Range(Uft|P2|RN|AP|Sn|OF)]> <[Minimum Elevation(Uft|P2|RN|AP|Sn|OF)]> <[Maximum Elevation(Uft|P2|RN|AP|Sn|OF)]>

Axes
top, bottom top, bottom top, bottom top, bottom left, right, center left, right, center left, right, center

Axis Tick Marks

Within each axis style are properties for specifying the tick marks placed along the axis. Both major tick marks and minor tick marks are represented by objects of type AeccTickStyle. AeccTickStyle manages the location, size, and visual style of tick marks through its Interval, Size and DisplayStylePlan properties. NOTE While most style properties use drawing units, the Interval property uses surface units. The AeccTickStyle object also sets what text is displayed at each tick, including any of the following property fields: Valid property fields for AeccTickStyle.Text
<[Section View Point Offset Side(CP)]> <[Section View Point Offset(Uft|P3|RN|Sn|OF|AP)]>

102 | Chapter 8 Sections

Valid property fields for AeccTickStyle.Text

<[Graph View Abscissa Value(Uft|P3|RN|AP|Sn|OF)]>

Setting Graph Styles

The graph is managed by an object of type AeccGraphStyle. This object can be used to change the grid and the title of the graph. The grid is controlled by the AeccGraphStyle.GridStyle property, an object of type AeccGridStyle. The grid style sets the amount of empty space above and below the extents of the section through the AeccGridStyle.GridsAboveMaxElevation and AeccGridStyle.GridsBelowDatum properties. The grid style also manages the line styles of major and minor vertical and horizontal gridlines with the AeccGridStyle properties MajorVerticalDisplayStylePlan, MajorHorizontalDisplayStylePlan, MinorVerticalDisplayStylePlan, and MinorHorizontalDisplayStylePlan. The AeccGridLines.HorizontalPosition and AeccGridLines.VerticalPosition properties tell which tick marks to use to position the grid lines for the axis.

Graph Title
The title of the graph is controlled by the AeccGraphStyle.TitleStyle property, an object of type AeccGraphTitleStyle. The title style object can adjust the position, style, and border of the title. The text of the title can include any of the following property fields: Valid property fields for AeccGraphTitleStyle.Text
<[Section View Description(CP)]> <[Section View Name(CP)]> <[Parent Alignment(CP)]> <[Section View Station(Uft|FS|P3|RN|Sn|OF|AP|B2|TP|EN|W0|DZY)]> <[Section View Datum Value(Uft|P3|RN|AP|Sn|OF)]> <[Section View Width(Uft|P3|RN|AP|Sn|OF)]> <[Left Width(Uft|P3|RN|AP|Sn|OF)]> <[Right Width(Uft|P3|RN|AP|Sn|OF)]> <[Drawing Scale(P3|RN|AP|OF)]> <[Graph View Vertical Scale(P3|RN|AP|OF)]> <[Graph View Vertical Exageration(P3|RN|AP|OF)]> <[Sample Line Name(CP)]>

Setting Section View Styles | 103

Valid property fields for AeccGraphTitleStyle.Text

<[Sample Line Group(CP)]> <[Sample Line Number(Sn)]>

Section View Style Example

This example takes an existing section view style and modifies its top axis and title.

104 | Chapter 8 Sections

' We assume a section view style with the name ' "Section View style" already exists. Dim oSectionViewStyle As AeccSectionViewStyle Set oSectionViewStyle = oDocument.SectionViewStyles _ .Item("Section View style") ''''''''''''''''''''''''''''''''''''' ' Adjust the top axis. With oSectionViewStyle.TopAxis.MajorTickStyle .AnnotationDisplayStylePlan.color = 23 ' light brown .Height = 0.004 ' text height .AnnotationDisplayStylePlan.Visible = True ' show text .Interval = 15 ' Major ticks 15 ground units apart ' Each major tick is marked with distance from the ' centerline in meters. .Text = "<[Section View Point Offset(Um|P1|RN|Sn|AP|OF)]>m" .DisplayStylePlan.Visible = True ' show ticks End With With oSectionViewStyle.TopAxis.TitleStyle .DisplayStylePlan.color = 23 ' light brown .Height = 0.008 ' text height .Text = "Meters" ' Position the title slightly higher. dOffset(0) = 0# dOffset(1) = 0.02 .Offset = dOffset .DisplayStylePlan.Visible = True ' show title End With ''''''''''''''''''''''''''''''''''''' ' Adjust the graph and graph title. With oSectionViewStyle.GraphStyle .VerticalExaggeration = 4.1 ' The lowest grid with any part of the section ' line in it will have one empty grid between ' it and the bottom axis. .GridStyle.GridsBelowDatum = 1 ' Increase the empty space above the section ' line to make room for any section line labels. .GridStyle.GridsAboveMaxElevation = 2 ' Show major lines, but not minor lines. .GridStyle.MajorHorizontalDisplayStylePlan.Visible .GridStyle.MajorVerticalDisplayStylePlan.Visible = .GridStyle.MinorHorizontalDisplayStylePlan.Visible .GridStyle.MinorVerticalDisplayStylePlan.Visible =

= True True = False False

' Move the title above the top axis. dOffset(0) = 0# dOffset(1) = 0.045 .TitleStyle.Offset = dOffset ' Set the title to display the station number of each ' section. Dim sTmp as String sTmp = "EG at Station <[Section View Station(Uft|FS)]>" .TitleStyle.Text = sTmp

Setting Section View Styles | 105

End With

Sample Program
SectionSample.dvb
<installation-directory>\Sample\Civil 3D API\Vba\Section\SectionSample.dvb This sample program creates a surface from a file and an alignment from a polyline. Sample lines (using group sample lines, individual sample lines, and sample lines based on polyline entities) are created across the alignment. Sections are created from each sample line, and section views of each surface cross section are drawn. Styles and label styles for sample lines and section views are created, as are data bands for the section view graphs.

106 | Chapter 8 Sections

Data Bands

Object Hierarchy

Object Model for Data Bands

Defining a Data Band Style

This section explains the creation and definition of data band style objects. These objects are used with profile view and section view graphs and represent a single band of graphical and text information.

107

Data Band Concepts

Data bands are a way to display more information with profile views and section views, including differences between sections, profile geometry, and superelevation along an alignment. Data bands consist of one or more strips at the top or bottom of each graph with tick marks, graphics, and labels describing particular features of the subject of the graph.

The bottom of a profile view with four data bands

A band is described by an object derived from the AeccBandStyle type: AeccBandSegmentDataStyle, AeccBandProfileDataStyle, AeccBandHorizontalGeometryStyle, AeccBandVerticalGeometryStyle, or AeccBandSuperElevationStyle. All such styles in the document are stored in collections depending on the band type: Band Style Type
AeccBandSegmentDataStyle

Collection of Band Style Objects

AeccDocument.SectionViewBandStyles. SectionDataBandStyles AeccDocument.ProfileViewBandStyles. ProfileDataBandStyles AeccDocument.ProfileViewBandStyles. HorizontalGeometryBandStyles AeccDocument.ProfileViewBandStyles. VerticalGeometryBandStyles AeccDocument.ProfileViewBandStyles. SuperElevationBandStyles

AeccBandProfileDataStyle

AeccBandHorizontalGeometryStyle

AeccBandVerticalGeometryStyle

AeccBandSuperElevationStyle

Each collection has an Add method for creating new band styles. The location of information displayed in the band depends on which band style objects are visible. Each data location (for example, at profile stations or at horizontal geometry points) consists of multiple style

108 | Chapter 9 Data Bands

elements (text labels, tick marks, lines, or blocks). Different band styles have different locations where information can be displayed, and will display information with different graphical effects. Each information location is managed by a set of three style objects that control:

The visual style of the text label (properties ending with LabelDisplayStylePlan, objects of type
AeccDisplayStyle).

The contents and nature of the text , tick marks, lines, and blocks (properties ending with LabelStyle, objects of type AeccBandLabelStyle). The visual style of the tick mark (properties ending with TickDisplayStylePlan, objects of type
AeccDisplayStyle).

The display styles have priority over the label style when setting the color or linetype. NOTE If either the display style or the label style element is not set to be visible, then the data element is not visible. A title can be displayed on the left side of each band. The style of the text and box around the text are controlled by the AeccBandStyle.TitleBoxTextDisplayStylePlan and AeccBandStyle.TitleBoxDisplayStylePlan properties, both object of type AeccDisplayStyle. The text of the title and its location are controlled through the AeccBandStyle.TitleStyle property, an object of type AeccBandTitleStyle. The AeccBandTitleStyle.Text property contains the actual string to be displayed, which may include property fields from the following list: Valid property fields for AeccBandTitleStyle.Text
<[Parent Alignment(CP)]> <[Section1 Name(CP)]> <[Section1 Type(CP)]> <[Section1 Left Length(Uft|P3|RN|AP|Sn|OF)]> <[Section1 Right Length(Uft|P3|RN|AP|Sn|OF)]> <[Section2 Name(CP)]> <[Section2 Type(CP)]> <[Section2 Left Length(Uft|P3|RN|AP|Sn|OF)]> <[Section2 Right Length(Uft|P3|RN|AP|Sn|OF)]> <[Sample Line Name(CP)]> <[Sample Line Group(CP)]> <[Sample Line Number(Sn)]> <[Profile1 Name(CP)]>

Data Band Concepts | 109

Valid property fields for AeccBandTitleStyle.Text

<[Profile2 Name(CP)]>

The following code sets the title for a section view data band showing two sections:
oBandSectionDataStyle.TitleStyle.Text = _ "<[Section1 Name(CP)]> and <[Section1 Name(CP)]>"

Profile Data Band Style

Data bands for general information about profiles are defined by the AeccBandProfileDataStyle type. Information in this data band can be displayed at the major and minor grid marks of the base graph, at points where the alignment station equation changes, and at points where the vertical or horizontal geometry change. Each label can use any of the following property fields: Valid property fields for use with AeccBandLabelStyle text components
<[Station Value(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Raw Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Profile1 Elevation(Uft|P2|RN|AP|Sn|OF)]> <[Profile2 Elevation(Uft|P3|RN|AP|Sn|OF)]> <[Profile1 Elevation Minus Profile2 Elevation(Uft|P3|RN|AP|Sn|OF)]> <[Profile2 Elevation Minus Profile1 Elevation(Uft|P3|RN|AP|Sn|OF)]>

This sample demonstrates the creation of a data band style displaying section elevation data at two different locations:

110 | Chapter 9 Data Bands

Dim oBandProfileDataStyle As AeccBandProfileDataStyle Set oBandProfileDataStyle = oDocument.ProfileViewBandStyles _ .ProfileDataBandStyles.Add("Profile Band")

With oBandProfileDataStyle ' Add ticks and labels to each horizontal ' geography location. .HGPLabelDisplayStylePlan.Visible = True .HGPTickDisplayStylePlan.Color = 10 ' red .HGPTickDisplayStylePlan.Visible = True .HGPLabelStyle.TextComponents.Item(0).Contents = _ "<[Station Value(Uft|FS|P0|RN|AP|Sn|TP|B2|EN|W0|OF)]>" .HGPLabelStyle.TextComponents.Item(0).Color = 11 ' red .HGPLabelStyle.TextComponents.Item(0).Visibility = True ' Modify how the title is displayed. .TitleBoxDisplayStylePlan.Color = 10 ' red .TitleBoxDisplayStylePlan.Linetype = "DOT" .TitleBoxDisplayStylePlan.Visible = True .TitleBoxTextDisplayStylePlan.Color = 80 ' green .TitleBoxTextDisplayStylePlan.Visible = True .TitleStyle.Text = "Profile Info" .TitleStyle.TextHeight = 1.0 .TitleStyle.TextBoxWidth = 2.0 ' Hide the rest of the information locations. .VGPLabelStyle.TextComponents.Item(0).Visibility = False .MajorIncrementLabelStyle.TextComponents.Item(0). _ Visibility = False .MajorStationLabelDisplayStylePlan.Visible = False .MajorTickDisplayStylePlan.Visible = False .MinorIncrementLabelStyle.TextComponents.Item(0). _ Visibility = False .MinorStationLabelDisplayStylePlan.Visible = False .MinorTickDisplayStylePlan.Visible = False .VGPLabelDisplayStylePlan.Visible = False .VGPTickDisplayStylePlan.Visible = False .StationEquationLabelStyle.TextComponents.Item(0). _ Visibility = False .StationEquationLabelDisplayStylePlan.Visible = True .StationEquationTickDisplayStylePlan.Visible = True End With

This style produces a data band that looks like this:

Profile Data Band Style | 111

Horizontal Geometry Data Band Style

The AeccBandHorizontalGeometryStyle type is used to display features of the horizontal geometry of alignments in profile views. Tangents and curves in the alignment are displayed as stylized line segments and curve segments, and a label can be displayed over each segment. Each label style can use any of the following property fields: Valid property fields for use with AeccBandLabelStyle text components
<[Length(Uft|P2|RN|Sn|OF|AP)]> <[Tangent Direction(Udeg|FDMSdSp|MB|P6|RN|DSn|CU|AP|OF)]> <[Start Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Start Easting(Uft|P4|RN|AP|Sn|OF)]> <[Start Northing(Uft|P4|RN|AP|Sn|OF)]> <[End Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[End Easting(Uft|P4|RN|AP|Sn|OF)]> <[End Northing(Uft|P4|RN|AP|Sn|OF)]>

This sample demonstrates the creation of a data band style displaying information about alignment geometry with a title:

112 | Chapter 9 Data Bands

Dim oBandProfileDataStyle As AeccBandProfileDataStyle Set oBandProfileDataStyle = oDocument.ProfileViewBandStyles _ .ProfileDataBandStyles.Add("Horizontal Band")

With oBandHorizontalGeometryStyle ' Add displays and labels for alignment tangents. .TangentGeometryDisplayStylePlan.Visible = True .TangentGeometryDisplayStylePlan.Color = 160 ' blue .TangentLabelDisplayStylePlan.Visible = True .TangentLabelStyle.TextComponents.Item(0).Contents = _ "Length = <[Length(Uft|P2|RN|Sn|OF|AP)]>" .TangentLabelStyle.TextComponents.Item(0).Color = 120 .TangentLabelStyle.TextComponents.Item(0). _ Visibility = True ' Add displays and labels for alignment curves. .CurveGeometryDisplayStylePlan.Visible = True .CurveGeometryDisplayStylePlan.Color = 160 ' blue .CurveLabelDisplayStylePlan.Visible = True .CurveLabelStyle.TextComponents.Item(0).Contents = _ "Length = <[Length(Uft|P2|RN|Sn|OF|AP)]>" .CurveLabelStyle.TextComponents.Item(0).Color = 120 .CurveLabelStyle.TextComponents.Item(0). _ Visibility = True ' Add tick marks at each horizontal geometry point, ' the location where different segments of the ' alignment meet. .TickDisplayStylePlan.Color = 10 ' red .TickDisplayStylePlan.Visible = True ' Modify how the title is displayed. .TitleBoxDisplayStylePlan.Color = 10 ' red .TitleBoxDisplayStylePlan.Linetype = "DOT" .TitleBoxDisplayStylePlan.Visible = True .TitleBoxTextDisplayStylePlan.Color = 80 ' green .TitleBoxTextDisplayStylePlan.Visible = True .TitleStyle.Text = "Alignment Geometry" .TitleStyle.TextHeight = 0.0125 .TitleStyle.TextBoxWidth = 0.21 ' Hide the rest of the information locations and ' graphical displays. .SpiralGeometryDisplayStylePlan.Visible = False .SpiralLabelDisplayStylePlan.Visible = False End With

This style produces a data band that looks like this:

Horizontal Geometry Data Band Style | 113

Vertical Geometry Data Band Style

The AeccBandProfileDataStyle type is used to display features of the vertical geometry of alignments in profile views. The style of graphical markers displayed at each curve and tangent segment can be modified, as well as the labels placed at crest, sag, uphill, and downhill segments of the profile. Downhill and uphill labels can use any of the following property fields: Valid property fields for use with AeccBandLabelStyle text components
<[Tangent Horizontal Length(Uft|P2|RN|Sn|OF|AP)]> <[Tangent Slope Length(Uft|P2|RN|AP|Sn|OF)]> <[Tangent Grade(FP|P2|RN|AP|Sn|OF)]> <[Tangent Start Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Tangent Start Elevation(Uft|P2|RN|AP|Sn|OF)]> <[Tangent End Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Tangent End Elevation(Uft|P2|RN|AP|Sn|OF)]> <[Tangent Elevation Change(Uft|P2|RN|AP|Sn|OF)]> <[PVI Before Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[PVI Before Elevation(Uft|P2|RN|AP|Sn|OF)]> <[PVI After Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[PVI After Elevation(Uft|P2|RN|AP|Sn|OF)]>

This sample demonstrates the creation of a data band style displaying the direction of slope for all segments of a profile with a title:

114 | Chapter 9 Data Bands

Dim oBandVerticalGeometryStyle As AeccBandVerticalGeometryStyle Set oBandVerticalGeometryStyle = oDocument.ProfileViewBandStyles _ .VerticalGeometryBandStyles.Add("Vertical Band")

With oBandVerticalGeometryStyle ' Add graphical marks that show the uphill or downhill ' directions and the lengths of the vertical segments ' of the profile. On uphill sections the label of the ' length of the segment will be in white, on downhill ' it will be pale yellow. The graphical element that ' shows direction will be pink. .DownhillTangentLabelStyle.TextComponents.Item(0). Contents = "<[Tangent Horizontal Length(Uft|P2)]>" .DownhillTangentLabelStyle.TextComponents.Item(0). _ Color = 51 ' pale yellow .DownhillTangentLabelStyle.TextComponents.Item(0). _ Visibility = True .UphillTangentLabelStyle.TextComponents.Item(0). Contents = "<[Tangent Horizontal Length(Uft|P2)]>" .UphillTangentLabelStyle.TextComponents.Item(0). _ Color = 255 ' white .UphillTangentLabelStyle.TextComponents.Item(0). _ Visibility = True .TangentGeometryDisplayStylePlan.Color = 220 ' pink .TangentGeometryDisplayStylePlan.Visible = True .TangentLabelDisplayStylePlan.Visible = True .TangentGeometryDisplayStylePlan.Visible = True ' Modify how the title is displayed. .TitleBoxDisplayStylePlan.Color = 10 ' red .TitleBoxDisplayStylePlan.Linetype = "DOT" .TitleBoxDisplayStylePlan.Visible = True .TitleBoxTextDisplayStylePlan.Color = 80 ' green .TitleBoxTextDisplayStylePlan.Visible = True .TitleStyle.Text = "Profile Geometry" .TitleStyle.TextHeight = 0.0125 .TitleStyle.TextBoxWidth = 0.21 ' Hide the rest of the information locations and ' graphical displays. .CurveGeometryDisplayStylePlan.Visible = False .CurveLabelDisplayStylePlan.Visible = False .TickDisplayStylePlan.Visible = False End With

This style produces a data band that looks like this:

Vertical Geometry Data Band Style | 115

Superelevation Data Band Style

An AeccBandProfileDataStyle data band displays information related to the alignment superelevation. It can display slopes of superelevation elements as lines, the distance above or below the centerline representing the amount of slope. The superelevation elements that can be represented this way are:

Left inside pavement Left inside shoulder Left outside pavement Left outside shoulder Right inside pavement Right inside shoulder Right outside pavement Right outside shoulder

You can also display a reference line through the center of the data band to help users interpret the element lines. The data band can also display tick marks and text labels at points of change in the superelevation of the alignment. The following can be marked on the data band:

Full superelevation Level crown Normal crown Reverse crown Shoulder break over Transition segment

The label styles for text labels can use any of the following property fields: Valid property fields for use with AeccBandLabelStyle text components
<[Station Value(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Superelevation critical point text(CP)]> <[Cross slope - Left outside pavement(FP|P2|RN|AP|Sn|OF)]> <[Cross slope - Left inside pavement(FP|P2|RN|AP|Sn|OF)]> <[Cross slope - Right outside pavement(FP|P2|RN|AP|Sn|OF)]> <[Cross slope - Right inside pavement(FP|P2|RN|AP|Sn|OF)]> <[Cross slope - Left outside shoulder(FP|P2|RN|AP|Sn|OF)]>

116 | Chapter 9 Data Bands

Valid property fields for use with AeccBandLabelStyle text components

<[Cross slope - Left inside shoulder(FP|P2|RN|AP|Sn|OF)]> <[Cross slope - Right outside shoulder(FP|P2|RN|AP|Sn|OF)]> <[Cross slope - Right inside shoulder(FP|P2|RN|AP|Sn|OF)]>

This sample demonstrates the creation of a data band style displaying the slopes of the outside shoulders the right shoulder in yellow and the left in blue. A gray reference line is also added.

Superelevation Data Band Style | 117

Dim oBandSuperElevationStyle As AeccBandSuperElevationStyle Set oBandSuperElevationStyle = oDocument.ProfileViewBandStyles _ .SuperElevationBandStyles.Add("Superelevation Band")

With oBandSuperElevationStyle ' Add graphical display of the slope of the left and right ' outside shoulders. If the line is above the centerline, ' then the slope is positive. .LeftOutsideShoulderLineDisplayStylePlan.Visible = True .LeftOutsideShoulderLineDisplayStylePlan.color = 151 ' Color 151 = pale blue .RightOutsideShoulderLineDisplayStylePlan.Visible = True .RightOutsideShoulderLineDisplayStylePlan.color = 51 ' Color 51 = pale yellow ' Add a reference line through the center of the data band. .ReferenceLineDisplayStylePlan.Visible = True .ReferenceLineDisplayStylePlan.color = 252 ' gray ' Modify how the title is displayed. .TitleBoxDisplayStylePlan.color = 10 ' red .TitleBoxDisplayStylePlan.Linetype = "DOT" .TitleBoxDisplayStylePlan.Visible = True .TitleBoxTextDisplayStylePlan.color = 80 ' green .TitleBoxTextDisplayStylePlan.Visible = True .TitleStyle.Text = "Profile Geometry" .TitleStyle.TextHeight = 0.0125 .TitleStyle.TextBoxWidth = 0.21 ' Hide the rest of the information locations and ' graphical displays. .FullSuperLabelDisplayStylePlan.Visible = False .FullSuperTickDisplayStylePlan.Visible = False .LeftInsidePavementLineDisplayStylePlan.Visible = False .LeftInsideShoulderLineDisplayStylePlan.Visible = False .LeftOutsidePavementLineDisplayStylePlan.Visible = False .LevelCrownLabelDisplayStylePlan.Visible = False .LevelCrownTickDisplayStylePlan.Visible = False .NormalCrownLabelDisplayStylePlan.Visible = False .NormalCrownTickDisplayStylePlan.Visible = False .ReverseCrownLabelDisplayStylePlan.Visible = False .ReverseCrownTickDisplayStylePlan.Visible = False .RightInsidePavementLineDisplayStylePlan.Visible = False .RightInsideShoulderLineDisplayStylePlan.Visible = False .RightOutsidePavementLineDisplayStylePlan.Visible = False .ShoulderBreakOverLabelDisplayStylePlan.Visible = False .ShoulderBreakOverTickDisplayStylePlan.Visible = False .TransitionSegmentLabelDisplayStylePlan.Visible = False End With

This style produces a data band that looks like this:

118 | Chapter 9 Data Bands

Section Data Band Style

Data bands for section views are described by an object of type AeccBandSectionDataStyle. Information in this data band can be displayed at major and minor tick marks, at the centerline, at each section grade break, and at each sample line vertex. The centerline is the location where the sample line crosses the alignment. If the sample line does not cross the alignment, the centerpoint is where the sample line would cross the alignment if the sample line were extended. Unless the AeccSampleLines.AddByPolyline method was used to create a multi-segment sample line, placing information at each sample line vertex simply places tick marks and labels at the section endpoints. Each label style can use any of the following property fields: Valid property fields for use with AeccBandLabelStyle text components
<[Distance from Centerline(Uft|P2|RN|Sn|OF|AP)]> <[Distance from Centerline Side(CP)]> <[Offset from Centerline(Uft|P3|RN|AP|Sn|OF)]> <[Offset from Centerline Side(CP)]> <[Section1 Elevation(Uft|P3|RN|AP|Sn|OF)]> <[Section2 Elevation(Uft|P3|RN|AP|Sn|OF)]> <[Section1 Elevation Minus Section2 Elevation(Uft|P3|RN|AP|Sn|OF)]> <[Section2 Elevation Minus Section1 Elevation(Uft|P3|RN|AP|Sn|OF)]> <[Section Segment Grade In(FP|P2|RN|AP|Sn|OF)]> <[Section Segment Grade Out(FP|P2|RN|AP|Sn|OF)]> <[Section Segment Grade Change(FP|P2|RN|AP|Sn|OF)]>

This sample demonstrates the creation of a data band style displaying section elevation data at two different locations:

Section Data Band Style | 119

Dim oBandSectionDataStyle As AeccBandSectionDataStyle Set oBandSectionDataStyle = oDocument.SectionViewBandStyles. _ SectionDataBandStyles.Add("Segment Band")

' Display at every major grid line a tick mark and a label ' that shows the section elevation at that point. With oBandSectionDataStyle .MajorOffsetLabelDisplayStylePlan.Color = 255 ' white .MajorOffsetLabelDisplayStylePlan.Visible = True .MajorOffsetTickDisplayStylePlan.Color = 255 ' white .MajorOffsetTickDisplayStylePlan.Visible = True End With With oBandSectionDataStyle.MajorIncrementLabelStyle. _ TextComponents.Item(0) .Contents = "<[Section1 Elevation(Um|P3|RN|AP|Sn|OF)]>m" .Color = 255 ' white .Visibility = True ' Shift the label to the high side of the band. .YOffset = 0.015 End With

' Display a red tick mark and a red label showing section ' elevation at each vertex endpoint in the sample line. ' Make the tick mark large, and only at the top of the ' band. With oBandSectionDataStyle .SampleLineVertexLabelDisplayStylePlan.Color = 20 ' red .SampleLineVertexLabelDisplayStylePlan.Visible = True .SampleLineVertexTickDisplayStylePlan.Color = 20 ' red .SampleLineVertexTickDisplayStylePlan.Visible = True End With With oBandSectionDataStyle.SampleLineVerticesLabelStyle. _ TextComponents.Item(0) .Contents = "<[Section1 Elevation(Um|P3|RN|AP|Sn|OF)]>m" .Color = 20 ' red .Visibility = True .YOffset = 0.08 End With With oBandSectionDataStyle.SampleLineVerticesLabelStyle. _ TickStyle .IncrementSmallTicksAtTop = True .IncrementSmallTicksAtMiddle = False .IncrementSmallTicksAtBottom = False .SmallTicksAtTopSize = 0.015 End With

' Hide all other data locations in the data band. With oBandSectionDataStyle .CenterLineLabelDisplayStylePlan.Visible = False .CenterLineTickDisplayStylePlan.Visible = False .GradeBreakLabelDisplayStylePlan.Visible = False .GradeBreakTickDisplayStylePlan.Visible = False .MinorOffsetLabelDisplayStylePlan.Visible = False

120 | Chapter 9 Data Bands

.MinorOffsetTickDisplayStylePlan = False End With

This style produces a data band that looks like this:

Creating a Data Band Set

This section explains data band sets, which are groups of individual data bands displayed around a profile view or section view graph.

Creating Data Band Sets for Profile Views

Individual band styles can be grouped together into a set, which can then be assigned to a graph. Profile band sets are AeccProfileViewBandStyleSet objects stored in the AeccDocument.ProfileViewBandStyleSet collection. The following example demonstrates creating a profile band style set and adding a band style to it:
Dim oProfileViewBandStyleSet As AeccProfileViewBandStyleSet Set oProfileViewBandStyleSet = _ oDocument.ProfileViewBandStyleSets.Add("Profile Band set") ' Add a band style we have already created to the ' band set. Call oProfileViewBandStyleSet.Add(oBandProfileDataStyle) ' Now we have a band set consisting of one band.

Data band sets are used when profile views are first created. The following sample code is taken from the topic Creating a Profile View (page 86), but this time a data band set is passed in the last parameter.
Set oProfileView = oAlignment.ProfileViews.Add( _ "Profile Style 01", _ "0", _ dOriginPt, _ oProfileViewStyle, _ oProfileViewBandStyleSet)

Creating Data Band Sets for Section Views

Individual band styles can be grouped together into a set, which can then be assigned to a graph. Band sets for section graphs are objects of type AeccSectionViewBandStyleSet, and all such sets are stored in the AeccDocument.SectionViewBandStyleSet collection. The following example demonstrates creating a section band style set and adding a band style to it:

Creating a Data Band Set | 121

Dim oSectionViewBandStyleSet As AeccSectionViewBandStyleSet Set oSectionViewBandStyleSet = _ oDocument.SectionViewBandStyleSets.Add("Section Band Set") ' Add a band style we have already created to the ' band set. Call oSectionViewBandStyleSet.Add(oBandSectionDataStyle) ' Now we have a band set consisting of one band.

Data band sets are used when section views are first created. The following sample code is taken from the Creating Section Views (page 100) section of the Sections (page 91) chapter, but this time a data band set is passed in the last parameter:
Set oSectionView=oSampleLines.Item(j).SectionViews.Add( _ "Section View" & CStr(j), _ "0", _ dOriginPt, _ oSectionViewStyle, _ oSectionViewBandStyleSet)

Using Data Bands

This section explains how data band sets are added to profile view and section view graphs.

Adding Data Bands to a Profile View

Every profile view contains a collection of bands in its AeccProfileView.BandSet property, an object of type AeccProfileViewBandSet. When a profile view is first created, all band styles from the AeccProfileViewBandStyleSet parameter are added to this collection. Individual band styles can be added to a section view through the AeccProfileViewBandSet collection using its Add or Insert methods. Both of these methods take an AeccProfileDataBandStyle style, a parent alignment, and two AeccProfile objects, allowing comparison between profiles. TIP If you only want to display information from a single profile in the band, pass the same profile object to both parameters. The order of bands in the band set is also the order in which the bands are displayed. AeccProfileViewBandSet.Add places the new band at the bottom of the list while AeccProfileViewBandSet.Insert places the new band at the specified index. TIP You can swap the location of two bands with the AeccProfileViewBandSet.Swap method. This sample adds a data band to a profile view that describes the single profile oProfile based on the alignment oAlignment:

122 | Chapter 9 Data Bands

Dim oProfileViewBandSetItem As AeccProfileViewBandSetItem Set oProfileViewBandSetItem = oProfileView.BandSet.Add( _ oBandStyle, _ oAlignment, _ oProfile, _ oProfile) ' Now oProfileView has another data band.

Adding Data Bands to a Section View

Every section view contains a collection of bands in its AeccSectionView.BandSet property, an object of type AeccSectionViewBandSet. When a section view is first created, all band styles from the AeccSectionViewBandStyleSet parameter are added to this collection. Individual band styles can be added to a section view through the AeccSectionViewBandSet collection using its Add or Insert methods. Both of these methods take an AeccSectionDataBandStyle style and two AeccSection objects, allowing comparison between sections. TIP If you only want to display a single section in the band, pass the same section object to both parameters. The order of bands in the band set is also the order in which the bands are displayed. AeccSectionViewBandSet.Add places the new band at the bottom of the list while AeccSectionViewBandSet.Insert places the new band at the specified index. TIP You can swap the location of two bands with the AeccSectionViewBandSet.Swap method. This sample adds a data band to a section view that describes the single section oSection:
Dim oSectionViewBandSetItem As AeccSectionViewBandSetItem Set oSectionViewBandSetItem = oSectionView.BandSet.Add( _ oBandSectionDataStyle, _ oSection, _ oSection) ' Now oSectionView has another data band.

Sample Programs
Profiles.dvb
<installation-directory>\Sample\Civil 3D API\Vba\Profile\ProfileSample.dvb See the ProfileViewStyle module for an example of the creation of a data band style, the definition of a data band style set, and the use of that data band set with a profile view.

Sections.dvb
<installation-directory>\Sample\Civil 3D API\Vba\Section\SectionSample.dvb See the SectionViewStyle module for an example of the creation of a data band style, the definition of a data band style set, and the use of that data band set with a section view.

Adding Data Bands to a Section View | 123

124

Pipe Networks

Object Hierarchy

Pipe Network Object Model

Base Objects
This section explains how to get the base objects required for using the pipe network API classes.

125

Accessing Pipe Network-Specific Base Objects

Applications that access pipe networks require special versions of the base objects representing the application and document. The AeccPipeApplication object is identical to the AeccApplication it is inherited from except that its AeccPipeApplication.ActiveDocument property returns an object of type AeccPipeDocument instead of AeccDocument. The AeccPipeDocument object contains collections of pipe network-related items, such as pipe networks, pipe styles, and interference checks. It also contains all of the methods and properties of AeccDocument. When using pipe network root objects, be sure to reference the Autodesk Civil Engineering Pipe 6.0 Object Library (AeccXPipe.tlb) and Autodesk Civil Engineering UI Pipe 6.0 Object Library (AeccXUIPipe.tlb) libraries. This sample demonstrates how to retrieve the pipe network root objects:
Dim oApp As AcadApplication Set oApp = ThisDrawing.Application Dim sAppName As String sAppName = "AeccXUiPipe.AeccPipeApplication" Dim oPipeApplication As AeccPipeApplication Set oPipeApplication = oApp.GetInterfaceObject(sAppName) ' Get a reference to the currently active document. Dim oPipeDocument As AeccPipeDocument Set oPipeDocument = oPipeApplication.ActiveDocument

Pipe-Specific Ambient Settings

Ambient settings allow you to get and set the units and default property settings of pipe network objects as well as access the catalog of all pipe and structure parts held in the document. Ambient settings for a pipe document are held in the AeccPipeDocument.Settings property, an object of type AeccPipeSettingsRoot. AeccPipeSettingsRoot inherits all the properties of the AeccSettingsRoot class. Among the properties of AeccPipeSettingsRoot are InterferenceSettings, PipeSettings, and StructureSettings. Each of these properties consist of an AeccSettingsAmbient object, which describes the default units of measurement for interference, pipe, and structure objects. The AeccPipeSettingsRoot.PipeNetworkSettings property contains the name of the default styles for pipe and structure objects as well as the default label placement, units, and naming conventions for pipe networks as a whole.
' Get the default set of pipe rules used in this document. With oSettings.PipeNetworkSettings.RulesSettings Debug.Print "Using pipe rules:"; .PipeDefaultRules.Value End With ' Set the default units used for pipes in this document. With oSettings.PipeSettings.AmbientSettings .AngleSettings.Unit = aeccAngleUnitRadian .CoordinateSettings.Unit = aeccCoordinateUnitFoot .DistanceSettings.Unit = aeccCoordinateUnitFoot End With

The AeccPipeSettingsRoot object also has a PipeNetworkCommandsSettings property, which contains properties that affect pipe network-related commands. Each sub-property contains an AmbientSettings property which describes the default units of measurement for interference, pipe, and structure objects, plus other properties specific to the command.

126 | Chapter 10 Pipe Networks

Listing and Adding Dynamic Part Properties

Each type of pipe and structure has many unique attributes (such as size, geometry, design, and composition) that cannot be stored in the standard pipe and structure properties. To give each part appropriate attributes, pipe and structure objects have sets of dynamic properties. A single property is represented by an AeccPartDataField object. Data fields are held in collections of type AeccPartDataRecord. You can reach these collections through the PartDataRecord property of AeccPartSizeFilter, AeccPipe, and AeccStructure objects. Each data field contains an internal variable name, a text description of the value, a global context used to identify the field, data type, and the data value itself. This sample enumerates all the data fields contained in a pipe object oPipe and displays information from each field.
Dim oPartDataField As AeccPartDataField Debug.Print "All data fields for this pipe:" Debug.Print "======" For Each oPartDataField In oPipe.PartDataRecord Debug.Print "Context name: "; oPartDataField.ContextString Debug.Print "Description: "; oPartDataField.Description Debug.Print "Internal name:"; oPartDataField.Name Debug.Print "Value: "; oPartDataField.Tag Debug.Print "Type of value:"; oPartDataField.Type Debug.Print "------" Next

To create your own dynamic properties, you first create a custom parameter describing the type and name of the property. You do this by using the pipe network catalog definitions object AeccPipeNetworkCatDef, which you access through the ambient property AeccPipeSettingsRoot.PipeNetworkCatDef. The AeccPipeNetworkCatDef object creates new parameters using the AeccPipeNetworkCatDef.DeclareNewParameter method. DeclareNewParameter takes some strings describing the parameter data type:

a global context (the identification string used to access the parameter type) a global context (the identification string used to access the parameter type) a context description (a description of the parameter) a parameter name (the internally used name of the parameter) a parameter description (the public name of the parameter used by the user interface, such as in the Part Properties tab of the Pipe and Structure Properties dialog boxes).

Once a parameter has been created, it can be made into a property available for use in parts through the AeccPipeNetworkCatDef.DeclarePartProperty method. NOTE The parameter name cannot contain spaces or punctuation characters. This sample demonstrates declaring a parameter and making a property based on that parameter available to any pipe objects:

Listing and Adding Dynamic Part Properties | 127

Dim oSettings As AeccPipeSettingsRoot Dim oPipeNetworkCatDef As AeccPipeNetworkCatDef Set oSettings = oPipeDocument.Settings Set oPipeNetworkCatDef = oSettings.PipeNetworkCatDef oPipeNetworkCatDef.DeclareNewParameter _ "Global Context 01", _ "Context Description", _ aeccDoubleGeneral, _ aeccDouble, _ "Test Parameter", _ "TParam", _ "", _ True, _ False oPipeNetworkCatDef.DeclarePartProperty "Global Context 01", aeccDomPipe, 10

You can now choose from among those properties available to the parts domain and create a data field.
' Make a data field based on the "Global Context 01" ' property and add it to a pipe object "oPipe". Set ' the value of the data field to "6.5". Dim oPartDataField As AeccPartDataField Set oPartDataField = oPipe.PartDataRecord.Append ("Global Context 01", 0) oPartDataField.Tag = 6.5

Retrieving the Parts List

AeccPipeSettingsRoot also contains the PartLists property, a read-only collection of all the lists of part types available in the document. Each list is an object of type AeccPartList, a read-only collection of part

families. A part family represents a broad category of parts, and is identified by a GUID (Globally Unique Identification) value. A part family can only contain parts from one domain - either pipes or structures but not both. Part families contain a read-only collection of part filters (AeccPartSizeFilter), which are the particular sizes of parts. A part filter is defined by its AeccPartSizeFilter.PartDataRecord property, a collection of fields describing various aspects of the part. This sample prints the complete listing of all parts in a document.

128 | Chapter 10 Pipe Networks

Dim oSettings As AeccPipeSettingsRoot Set oSettings = oPipeDocument.Settings ' Get a reference to all the parts lists in the drawing. Dim oPartLists As AeccPartLists Set oPartLists = oSettings.PartLists Debug.Print "Number of part lists: "; oPartLists.Count Dim oPartList As AeccPartList For Each oPartList In oPartLists Dim oPartFamily As AeccPartFamily Dim oSizeFilters As AeccPartSizeFilters Dim oSizeFilter As AeccPartSizeFilter Dim sPipeGuid As String Dim sStructureGuid As String Dim oPipeFilter As AeccPartSizeFilter Dim oStructureFilter As AeccPartSizeFilter Debug.Print: Debug.Print Debug.Print "PART LIST - "; oPartList.Name Debug.Print "-------------------------------------------" ' From the part list, looking at only those part families ' that are pipes, print all the individual parts. Debug.Print " Pipes" Debug.Print " =====" For Each oPartFamily In oPartList ' Look for only pipe families. If (oPartFamily.Domain = aeccDomPipe) Then sPipeGuid = oPartFamily.guid Debug.Print " Family: "; oPartFamily.Name ' Go through each part in this family. For Each oPipeFilter In oPartFamily.SizeFilters Debug.Print " Part: "; oPipeFilter.Name Next End If Next ' From the part list, looking at only those part families ' that are structures, print all the individual parts. Debug.Print Debug.Print " Structures" Debug.Print " ==========" For Each oPartFamily In oPartList ' Look for only structure families. If (oPartFamily.Domain = aeccDomStructure) Then sStructureGuid = oPartFamily.guid Debug.Print " Family: "; oPartFamily.Name ' Go through each part in this family. For Each oPipeFilter In oPartFamily.SizeFilters Debug.Print " Part: "; oPipeFilter.Name Next End If Next Next

Creating a Pipe Network | 129

Creating a Pipe Network

A pipe network is a set of interconnected or related parts. The collection of all pipe networks is held in the AeccPipeDocument.PipeNetworks property. A pipe network, an object of type AeccPipeNetwork, contains the collection of pipes and the collection of structures which make up the network. AeccPipeNetwork also contains the method AeccPipeNetwork.FindShortestNetworkPath for determining the path between two network parts. The AeccPipeNetwork.ReferenceAlignment is used by pipe and structure label properties. For example, you can create a label that shows the station and offset from the alignment. The AeccPipeNetwork.ReferenceSurface is used primarily for Pipe Rules. For example, you can have a rule that places the structure rim at a specified elevation from the surface. Labels may also refer to the ReferenceSurface property.
' Get the collection of all networks. Dim oPipeNetworks as AeccPipeNetworks Set oPipeNetworks = oPipeDocument.PipeNetworks ' Create a new pipe network Set oPipeNetwork = oPipeNetworks.Add("Network Name")

Pipes
This section explains the creation and use of pipes. Pipes represent the conduits within a pipe network.

Creating Pipes
Pipe objects represent the conduits of the pipe network. Pipes are created using the pipe networks AeccPipeNetwork.Pipes collection. This collection has methods for creating either straight or curved pipes. Both methods require you to specify a particular part family (using the GUID of a family) and a particular part size filter object as well as the starting and ending points of the pipe. The order of the start and end points may have meaning in describing flow direction. This sample creates a straight pipe between two hard-coded points using the first pipe family and pipe size filter it can find in the part list:

130 | Chapter 10 Pipe Networks

Dim Dim Dim Dim Dim Dim

oPipe as AeccPipe oSettings As AeccPipeSettingsRoot oPartLists As AeccPartLists oPartList As AeccPartList sPipeGuid As String oPipeFilter As AeccPartSizeFilter

' Go through the list of part types and select the first ' pipe found. Set oSettings = oPipeDocument.Settings ' Get all the parts list in the drawing. Set oPartLists = oSettings.PartLists ' Get the first part list found. Set oPartList = oPartLists.Item(0) For Each oPartFamily In oPartList ' Look for a pipe family. If (oPartFamily.Domain = aeccDomPipe) Then sPipeGuid = oPartFamily.guid ' Get the first size filter list from the family. Set oPipeFilter = oPartFamily.SizeFilters.Item(0) Exit For End If Next Dim dStartPoint(0 To 2) As Double Dim dEndPoint(0 To 2) As Double dStartPoint(0) = 100: dStartPoint(1) = 100 dEndPoint(0) = 200: dEndPoint(1) = 100 ' Assuming a valid AeccNetwork object "oNetwork". Set oPipe = oNetwork.Pipes.Add(sPipeGuid, oPipeFilter, dStartPoint, dEndPoint)

Using Pipes
To make a new pipe a meaningful part of a pipe network, it must be connected to structures or other pipes using the AeccPipe.ConnectToStructure or AeccPipe.ConnectToPipe methods, or structures must be connected to it using the AeccStructure.ConnectToPipe method. Connecting pipes together directly creates a new virtual AeccStructure object to serve as the joint. If a pipe end is connected to a structure, it must be disconnected before attempting to connect it to a different structure. After a pipe has been connected to a network, you can determine the structures at either end by using the StartStructure and EndStructure properties or by using the Connections property, which is a read-only collection of network parts. There are methods and properties for setting and determining the flow direction, getting all types of physical measurements, and for accessing collections of user-defined properties for custom descriptions of the pipe.

Using Pipes | 131

' Given a pipe and a structure, join the second endpoint ' of the pipe to the structure. oPipe.ConnectToStructure aeccPipeEnd, oStructure ' Set the flow direction for the pipe. oPipe.FlowDirectionMethod = aeccPipeFlowDirectionMethodBySlope ' Add a custom property to the pipe and assign a value. Call oPipe.ParamsLong.Add("Custom", 9.2) Debug.Print "Custom prop:"; oPipe.ParamsLong.Value("Custom")

Creating Pipe Styles

A pipe style controls the visual appearance of pipes in a document. All pipe style objects in a document are stored in the AeccPipeDocument.PipeStyles collection. Pipe styles have four display methods and three hatch methods for controlling general appearance attributes and three properties for controlling display attributes that are specific to pipes. The methods DisplayStyleModel|Profile|Section|Plan, and HatchStylePlan|Profile|Section all take a parameter describing the feature being modified, and return a reference to the AeccDisplayStyle or AeccHatchDisplayStyle object controlling common display attributes, such as line styles and color. The properties PlanOption and ProfileOption set the size of the inner wall, outer wall, and end lines according to either the physical properties of the pipe, a custom sizes using drawing units, or a certain percentage of its previous drawing size. The HatchOption property sets the area of the pipe covered by any hatching used. A pipe object is given a style by assigning the AeccPipe.Style property to a AeccPipeStyle object. This sample creates a new pipe style object, sets some of its properties, and assigns it to a pipe object:

132 | Chapter 10 Pipe Networks

' Create a new pipe style object. Dim oPipeStyle As AeccPipeStyle Set oPipeStyle = oPipeDocument.PipeStyles.Add("Pipe Style 01") With oPipeStyle.PlanOption ' Set the display size of the pipes in plan view, using ' absolute drawing units for the inside, outside, and ' ends of each pipe. .InnerDiameter = 2.1 .OuterDiameter = 2.4 .EndLineSize = 2.1 ' Indicate that we will use our own measurements for ' the inside and outside of the pipe, and not base ' the drawing on the actual physical measurements of ' the pipe. .WallSizeType = aeccUserDefinedWallSize ' Indicate what kind of custom sizing to use. .WallSizeOptions = aeccPipeUseAbsoluteUnits End With ' Modify the colors of pipes using this style when shown in ' plan view. oPipeStyle.DisplayStylePlan(aeccDispCompPipeOutsideWalls) _ .Color = 40 ' orange oPipeStyle.DisplayStylePlan(aeccDispCompPlanInsideWalls) _ .Color = 255 ' white oPipeStyle.DisplayStylePlan(aeccDispCompPipeEndLine) _ .color = 255 ' white ' Set a pipe to use this style. Set oPipe.Style = oPipeStyle

Creating Pipe Label Styles

The collection of all pipe label styles in a document is found in the AeccPipeDatabase.PipeNetworkLabelStyles.PipeLabelStyles property, which is a standard AeccLabelStyles object. For more information, see Label Styles (page 13). NOTE The label style of a particular pipe cannot be set using the API. Pipe label styles can use the following property fields in the contents of any text component. Valid property fields for AeccLabelStyleTextComponent.Contents in pipes
<[Cross Sectional Shape(CP)]> <[Wall Thickness(Uin|P3|RN|AP|Sn|OF)]> <[Material(CP)]> <[Minimum Curve Radius(Uft|P3|RN|AP|Sn|OF)]>

Creating Pipe Label Styles | 133

Valid property fields for AeccLabelStyleTextComponent.Contents in pipes

<[Manning Coefficient(P3|RN|AP|Sn|OF)]> <[Hazen Williams Coefficient(P3|RN|AP|Sn|OF)]> <[Darcy Weisbach Factor(P3|RN|AP|Sn|OF)]> <[Inner Pipe Diameter(Uin|P3|RN|AP|Sn|OF)]> <[Inner Pipe Width(Uin|P3|RN|AP|Sn|OF)]> <[Inner Pipe Height(Uin|P3|RN|AP|Sn|OF)]> <[Name(CP)]> <[Description(CP)]> <[Network Name(CP)]> <[Reference Alignment Name(CP)]> <[Pipe Start Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Start Offset(Uft|P3|RN|AP|Sn|OF)]> <[Start Offset Side(CP)]> <[Pipe End Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[End Offset Side(Uft|P3|RN|AP|Sn|OF)]> <[End Offset(CP)]> <[Reference Surface Name(CP)]> <[Pipe Slope(FP|P2|RN|AP|Sn|OF)]> <[Pipe Start Structure(CP)]> <[Pipe Start Northing(Uft|P4|RN|AP|Sn|OF)]> <[Pipe Start Easting(Uft|P4|RN|AP|Sn|OF)]> <[Start Invert Elevation(Uft|P3|RN|AP|Sn|OF)]> <[Start Centerline Elevation(Uft|P3|RN|AP|Sn|OF)]>

134 | Chapter 10 Pipe Networks

Valid property fields for AeccLabelStyleTextComponent.Contents in pipes

<[Start Crown Elevation(Uft|P3|RN|AP|Sn|OF)]> <[Pipe End Structure(CP)]> <[Pipe End Northing(Uft|P4|RN|AP|Sn|OF)]> <[Pipe End Easting(Uft|P4|RN|AP|Sn|OF)]> <[End Invert Elevation(Uft|P3|RN|AP|Sn|OF)]> <[End Centerline Elevation(Uft|P3|RN|AP|Sn|OF)]> <[End Crown Elevation(Uft|P3|RN|AP|Sn|OF)]> <[2D Length - Center to Center(Uft|P3|RN|AP|Sn|OF)]> <[3D Length - Center to Center(Uft|P3|RN|AP|Sn|OF)]> <[2D Length - To Inside Edges(Uft|P3|RN|AP|Sn|OF)]> <[3D Length - To Inside Edges(Uft|P3|RN|AP|Sn|OF)]> <[Pipe Bearing(Udeg|FDMSdSp|MB|P6|RN|DSn|CU|AP|OF)]> <[Pipe Start Direction in plan(Udeg|FDMSdSp|MB|P6|RN|DSn|CU|AP|OF)]> <[Pipe End Direction in plan(Udeg|FDMSdSp|MB|P6|RN|DSn|CU|AP|OF)]> <[Pipe Radius(Uft|P3|RN|AP|Sn|OF)]> <[Pipe Chord Length(Uft|P3|RN|AP|Sn|OF)]> <[Radius Point Northing(Uft|P4|RN|AP|Sn|OF)]> <[Radius Point Easting(Uft|P4|RN|AP|Sn|OF)]> <[Minimum Cover(Uft|P3|RN|AP|Sn|OF)]> <[Maximum Cover(Uft|P3|RN|AP|Sn|OF)]> <[Pipe Outer Diameter or Width(Uin|P3|RN|AP|Sn|OF)]> <[Pipe Inner Diameter or Width(Uin|P3|RN|AP|Sn|OF)]> <[Drop Across Span(Uft|P3|RN|AP|Sn|OF)]>

Creating Pipe Label Styles | 135

Valid property fields for AeccLabelStyleTextComponent.Contents in pipes

<[Total Slope Across Span(FP|P2|RN|AP|Sn|OF)]> <[Number of Pipes in Span(Sn)]>

Structures
This section describes the creation and use of structures. Structures are the connectors within a pipe network.

Creating Structures
Structures represent physical objects such as manholes, catch basins, and headwalls. Logically, structures are used as connections between pipes at pipe endpoints. In cases where two pipes connect directly, an AeccStructure object not representing any physical object is still created to serve as the joint. Any number of pipes can connect with a structure. Structures are represented by objects of type AeccStructure, which are created by using the Add method of the Surfaces collection of AeccPipeNetwork. This sample uses the first structure family and size filter it can find in the part list and creates a new structure based on that part type.

136 | Chapter 10 Pipe Networks

Dim Dim Dim Dim Dim Dim

oStructure as AeccStructure oSettings As AeccPipeSettingsRoot oPartLists As AeccPartLists oPartList As AeccPartList sStructureGuid As String oStructureFilter As AeccPartSizeFilter

' Go through the list of part types and select the first ' structure found. Set oSettings = oPipeDocument.Settings ' Get all the parts list in the drawing. Set oPartLists = oSettings.PartLists ' Get the first part list found. Set oPartList = oPartLists.Item(0) For Each oPartFamily In oPartList ' Look for a structure family that is not named ' "Null Structure". If (oPartFamily.Domain = aeccDomStructure) And _ (oPartFamily.Name = "Null Structure") Then sStructureGuid = oPartFamily.guid ' Get the first size filter list from the family. Set oStructureFilter = oPartFamily.SizeFilters.Item(0) Exit For End If Next Dim dPoint(0 To 2) As Double dPoint(0) = 100: dPoint(1) = 100 ' Assuming a valid AeccNetwork object "oNetwork". Set oStructure = oNetwork.Structures.Add( _ sStructureGuid, _ oStructureFilter, _ dPoint, _ 5.2333) ' 305 degrees in radians

Using Structures
To make the new structure a meaningful part of a pipe network, it must be connected to pipes in the network using the AeccStructure.ConnectToPipe method or pipes must be connected to it using the AeccPipe.ConnectToStructure method. After a structure has been connected to a network, you can determine the pipes connected to it by using the Connections property, which is a read-only collection of network parts. There are also methods and properties for setting and determining all types of physical measurements for the structure and for accessing collections of user-defined properties for custom descriptions of the structure.

Using Structures | 137

' Given a pipe and a structure, join the second endpoint ' of the pipe to the structure. oStructure.ConnectToPipe oPipeNew, aeccPipeEnd ' Determine flow directions from all pipes connected ' to a structure. Dim i As Integer For i = 0 To oStructure.ConnectedPipesCount - 1 If (oStructure.IsConnectedPipeFlowingIn(i) = True) Then Debug.Print "Pipe "; i; " flows into structure" Else Debug.Print "Pipe "; i; " does not flow into structure" End If Next i

Creating Structure Styles

A structure style controls the visual appearance of structures in a document. All structure style objects are stored in the AeccPipeDocument.StructureStyles collection. Structure styles have four methods for controlling general appearance attributes and three properties for controlling display attributes that are specific to structures. The methods DisplayStylePlan|Profile|Section|Model and HatchStylePlan|Profile|Section all take a parameter describing the feature being modified and return a reference to the AeccDisplayStyle or AeccHatchDisplayStyle object controlling common display attributes such as line styles and color. The properties PlanOption, ProfileOption, and ModelOption set the display size of the structure and whether the structure is shown as a model of the physical object or only symbolically. A structure object is given a style by assigning the AeccStructure.Style property to a AeccStructureStyle object. This sample creates a new structure style object, sets some of its properties, and assigns it to a structure object:
' Create a new structure style object. Dim oStructureStyle As AeccStructureStyle Set oStructureStyle = oPipeDocument.StructureStyles.Add("Structure Style 01") oStructureStyle.DisplayStylePlan(aeccDispCompStructure).color = 30 oStructureStyle.PlanOption.MaskConnectedObjects = True ' Set a structure to use this style. Set oStructure.Style = oStructureStyle

Creating Structure Label Styles

The collection of all structure label styles in a document is found in the AeccPipeDatabase.PipeNetworkLabelStyles.StructureLabelStyles property, which is a standard AeccLabelStyles object. For more information, see Label Styles (page 13). NOTE The label style of a particular structure cannot be set using the API.

138 | Chapter 10 Pipe Networks

Structure label styles can use the following property fields in the contents of any text component: Valid property fields for AeccLabelStyleTextComponent.Contents in structures
<[Name(CP)]> <[Description(CP)]> <[Network Name(CP)]> <[Structure Rotation Angle(Udeg|FD|P4|RN|AP|OF)]> <[Reference Alignment Name(CP)]> <[Structure Station(Uft|FS|P2|RN|AP|Sn|TP|B2|EN|W0|OF)]> <[Structure Offset(Uft|P3|RN|AP|Sn|OF)]> <[Structure Offset Side(CP)]> <[Reference Surface Name(CP)]> <[Connected Pipes(Sn)]> <[Structure Northing(Uft|P4|RN|AP|Sn|OF)]> <[Structure Easting(Uft|P4|RN|AP|Sn|OF)]> <[Automatic Surface Adjustment]> <[Insertion Rim Elevation(Uft|P3|RN|AP|Sn|OF)]> <[Sump Elevation(Uft|P3|RN|AP|Sn|OF)]> <[Surface Adjustment Value(Uft|P3|RN|AP|Sn|OF)]> <[Control Sump By:(CP)]> <[Sump Depth(P3|RN|AP|Sn|OF)]> <[Surface Elevation At Insertion Point(Uft|P3|RN|AP|Sn|OF)]> <[Structure Shape(CP)]> <[Vertical Pipe Clearance(Uin|P3|RN|AP|Sn|OF)]> <[Rim to Sump Height(Uft|P3|RN|AP|Sn|OF)]>

Creating Structure Label Styles | 139

Valid property fields for AeccLabelStyleTextComponent.Contents in structures

<[Wall Thickness(Uin|P3|RN|AP|Sn|OF)]> <[Floor Thickness(Uin|P3|RN|AP|Sn|OF)]> <[Material(CP)]> <[Frame(CP)]> <[Grate(CP)]> <[Cover(CP)]> <[Frame Height(Uin|P3|RN|AP|Sn|OF)]> <[Frame Diameter(Uin|P3|RN|AP|Sn|OF)]> <[Frame Length(Uin|P3|RN|AP|Sn|OF)]> <[Frame Width(Uin|P3|RN|AP|Sn|OF)]> <[Barrel Height(Uft|P3|RN|AP|Sn|OF)]> <[Barrel Pipe Clearance(Uin|P3|RN|AP|Sn|OF)]> <[Cone Height(Uin|P3|RN|AP|Sn|OF)]> <[Slab Thickness(Uin|P3|RN|AP|Sn|OF)]> <[Inner Structure Diameter(Uin|P3|RN|AP|Sn|OF)]> <[Inner Structure Length(Uin|P3|RN|AP|Sn|OF)]> <[Inner Structure Width(Uin|P3|RN|AP|Sn|OF)]> <[Headwall Base Width(Uin|P3|RN|AP|Sn|OF)]> <[Headwall Base Thickness(Uin|P3|RN|AP|Sn|OF)]>

Interference Checks
This section explains how to generate and examine an interference check. An interference check is used to determine when pipe network parts are either intersecting or are too close together.

140 | Chapter 10 Pipe Networks

Object Hierarchy

Pipe Network Interference Object Model

Performing an Interference Check

An interference check is used to detect intersections between the pipe parts of two different pipe networks or of pipes of a single network with themselves. The collection of all interference checks, an object of type AeccInterferenceChecks, is contained in the documents AeccPipeDocument.InterferenceChecks property. A new interference check is made using the AeccInterferenceChecks.Create method, which requires an AeccInterferenceCheckCreationData parameter. The creation data object holds all the information needed to perform the check, including the type of check to perform, the distance between parts required for an interference, and the pipe networks being checked. A new creation data object can only be made using the AeccInterferenceChecks.GetDefaultCreationData method. A valid check requires at least the Name, LayerName, SourceNetwork and TargetNetwork properties of the creation data object to be set. The following sample performs an interference check between two networks:

Object Hierarchy | 141

' Get the collection of all interference checks. Dim oInterferenceChecks As AeccInterferenceChecks Set oInterferenceChecks = oPipeDocument.InterferenceChecks ' Set up the creation data structure for making an ' interference check. Dim oCreationData As AeccInterferenceCheckCreationData Set oCreationData = oInterferenceChecks.GetDefaultCreationData ' If pipes are closer than 3.5 units apart, count it as an ' intersection. oCreationData.Criteria.ApplyProximity = True oCreationData.Criteria.CriteriaDistance = 3.5 oCreationData.Criteria.UseDistanceOrScaleFactor = aeccDistance ' List the networks being tested. We will compare a network ' with itself, so we list it twice. Set oCreationData.SourceNetwork = oPipeNetwork1 Set oCreationData.TargetNetwork = oPipeNetwork2 ' Assign the check a unique name and a layer to use. oCreationData.Name = "Test 01" oCreationData.LayerName = oPipeDocument.Layers.Item(0).Name ' Create a new check of the pipe network. Dim oInterferenceCheck As AeccInterferenceCheck Set oInterferenceCheck = _ oInterferenceChecks.Create(oCreationData)

Listing the Interferences

An interference check, the AeccInterferenceCheck object returned by the AeccInterferenceChecks.Create method, contains a collection of AeccInterference objects each representing a single interference found during the check. Each interference holds the point location of the interference center in the Location property, a three element array of doubles representing X, Y, and Z coordinates. The bounds of the entire interference area are returned by the GetExtents method. The extents are a two-item array of points, together representing the greatest and least corners of a cube containing the intersection area. The SourceNetworkPart and TargetNetworkPart properties hold the network parts that intersect.

142 | Chapter 10 Pipe Networks

Dim oInterference As AeccInterference For Each oInterference In oInterferenceCheck ' Display the 2D x,y location of the interference. Dim vLocation As Variant Dim sLocation As String Dim vExtent As Variant vLocation = oInterference.Location sLocation = vLocation(0) & ", " & vLocation(1) MsgBox "There is an interference at:" & sLocation ' Display the greatest and least corners of the 3D ' rectangle containing the interference. vExtent = oInterference.GetExtents() Debug.Print "The interference takes place between:" sLocation = vExtent(0)(0) & ", " sLocation = sLocation & vExtent(0)(1) & ", " sLocation = sLocation & vExtent(0)(2) Debug.Print " "; sLocation; " and:" sLocation = vExtent(1)(0) & ", " sLocation = sLocation & vExtent(1)(1) & ", " sLocation = sLocation & vExtent(1)(2) Debug.Print " "; sLocation Next If (oInterferenceCheck.Count = 0) Then MsgBox "There are no interferences in the network." End If

Interference Check Styles

Either a symbol or a model of the actual intersection region can be drawn at each interference location. The display of these intersections is controlled by an AeccInterferenceStyle object. The collection of all interference style objects in the document are stored in the AeccPipeDocument.InterferenceStyles collection. Set the style of an interference object by assigning an AeccInterferenceStyle object to the AeccInterference.Style property:
Set oInterference.Style = oInterferenceStyle

There are three different styles of interference displays you can chose from. First, you can display a 3D model of the intersection region. This is done by setting the ModelOptions style property to aeccTrueSolidInterference. The ModelSolidDisplayStyle2D property, an object of type AeccDisplayStyle, controls the visible appearance of the model such as color and line types. Make sure the ModelSolidDisplayStyle2D.Visible property is set to True. Another possibility is to draw a 3D sphere at the location of intersection. This is done by setting the ModelOptions style property to aeccSphereInterference. If the InterferenceSizeType property is set to aeccSolidExtents, then the sphere is automatically sized to just circumscribe the region of intersection (that is, it is the smallest sphere that still fits the model of the intersection region). You can set the size of the sphere by setting the InterferenceSizeType property to aeccUserDefined, setting the ModelSizeOptions property to use either absolute units or drawing units, and setting the corresponding AbsoluteModelSize or DrawingScaleModelSize property to the desired value. Again, the ModelSolidDisplayStyle2D property controls the visual features such as color and line type. Make sure the ModelSolidDisplayStyle2D.Visible property is set to True.

Interference Check Styles | 143

The third option is to place a symbol at the location of intersection. Set the PlanSymbolDisplayStyle2D.Visible style property to True to make symbols visible. The style property MarkerStyle, an object of type AeccMarkerStyle, controls all aspects of how the symbol is drawn. This sample creates a new interference style object that displays an X symbol with a superimposed circle at points of intersection:
' Create a new interference style object. Dim oInterferenceStyle As AeccInterferenceStyle Set oInterferenceStyle = oPipeDocument.InterferenceStyles _ .Add("Interference style 01") ' Draw a symbol of a violet X with circle with a specified ' drawing size at the points of intersection. oInterferenceStyle.PlanSymbolDisplayStyle2D.Visible = True With oInterferenceStyle.MarkerStyle .MarkerType = aeccUseCustomMarker .CustomMarkerStyle = aeccCustomMarkerX .CustomMarkerSuperimposeStyle = _ aeccCustomMarkerSuperimposeCircle .MarkerDisplayStylePlan.color = 200 ' violet .MarkerDisplayStylePlan.Visible = True .MarkerSizeType = aeccAbsoluteUnits .MarkerSize = 5.5 End With ' Hide any model display at intersection points. oInterferenceStyle.ModelSolidDisplayStyle2D.Visible = False

Sample Program
PipeSample.dvb
<installation-directory>\Sample\Civil 3D API\Vba\Pipe\PipeSample.dvb The sample code from this chapter can be found in context in the PipeSample.dvb project. This sample creates a simple pipe network, creates and applies a new style, and performs an interference check.

144 | Chapter 10 Pipe Networks

Creating Custom Subassemblies Using .NET

Overview
This chapter describes how to create a custom subassembly using Visual Basic .NET. This is the currently supported and preferred method of creating custom subassemblies, although the older VBA framework is still supported. See the Appendix Creating Custom Subassemblies with VBA (page 207) for more information. This chapter covers design considerations, the structure of subassembly programs, and an example subassembly in VB that you can use as a template for your own custom subassemblies.

Subassembly Changes
The target mapping feature in AutoCAD Civil 3D 2009 has changed, which affects how custom subassemblies are written. This feature now allows a subassembly to target object types in addition to alignments and profiles associated with the corridor that it requires to define its geometry. For more information about this feature, see Setting and Editing Targets in the AutoCAD Civil 3D Users Guide. There are four changes to the way you write a custom subassembly: 1 New parameter types in ParamLogicalNameType 2 New target collections in corridorState 3 Targets are now objects 4 The CalcAlignmentOffsetToThisAlignment utility method is changed

145

New parameter types in ParamLogicalNameType

A subassembly can now target an offset target and elevation target (instead of an alignment and a profile), which are represented by new parameter types in ParamLogicalNameType. If you want to support the new target types in your subassemblies, you need to replace:
ParamLogicalNameType.Alignment with ParamLogicalNameType.OffsetTarget offset targets that are alignments, feature lines, survey figures

and AutoCAD polylines OR

ParamLogicalNameType.OffsetTargetPipe offset targets that are pipe networks

ParamLogicalNameType.Profile with ParamLogicalNameType.ElevationTarget elevation targets that are profiles, feature lines, survey

figures and AutoCAD 3D polylines OR

ParamLogicalNameType.ElevationTargetPipe elevation targets that are pipe networks

New target collections in corridorState

To get the offset and elevation target collections from the corridorState object, use ParamsOffsetTarget and ParamsElevationTarget instead of ParamsAlignment and ParamsProfile. All the offset targets (including network pipe offset targets) are in ParamsOffsetTarget, and all elevation targets (including network pipe elevation targets) are in ParamsElevationTarget. Heres an example from the BasicLaneTransition.vb sample in the Sample VB.NET Subassembly (page 156) section below:
Dim oParamsLong As ParamLongCollection oParamsLong = corridorState.ParamsLong Dim oParamsOffsetTarget As ParamOffsetTargetCollection oParamsOffsetTarget = corridorState.ParamsOffsetTarget

Targets are now objects

Targets are now objects, instead of alignment or profile IDs. Now WidthOffsetTarget is defined for offset targets, and SlopeElevationTarget is defined for elevation targets, so you can declare targets as objects instead of IDs. Heres an example from the BasicLaneTransition.vb sample in the Sample VB.NET Subassembly (page 156) section below:
Dim offsetTarget As WidthOffsetTarget 'width or offset target offsetTarget = Nothing Dim elevationTarget As SlopeElevationTarget 'slope or elevation target elevationTarget = Nothing

Changes to CalcAlignmentOffsetToThisAlignment()
The CalcAlignmentOffsetToThisAlignment() utility method now calculate the offset from this alignment to the offset target. This method no longer returns the station value; it now returns the XY coordinate of the offset target at the point perpendicular to the alignments station. You can also now use the SlopeElevationTarget.GetElevation method to get an elevation on an elevation target directly, instead of using CalcAlignmentOffsetToThisAlignment(). Heres an example from the BasicLaneTransition.vb sample in the Sample VB.NET Subassembly (page 156) section below:

146 | Chapter 11 Creating Custom Subassemblies Using .NET

Designing Custom Subassemblies

This section describes the requirements for designing a custom subassembly.

Naming Custom Subassemblies

Do not use spaces or other special characters. Use a combination of upper and lower case letters, with uppercase letters reserved for the first character of each word. Group subassemblies by making the type of component the first word. For example, in the Civil 3D Corridor Modeling catalogs all lane subassembly names begin with Lane, all shoulders with Shoulder, and so on.

Attachment and Insertion Methodology

Most subassembly components have a single point of attachment and extend in one direction or the other from that point. However, there are some exceptions to this general rule. The list below describes the attachment and insertion methodology for three categories of subassemblies: medians, components joining two roadways, and rehabilitation and overlay.

Medians. Medians tend to be inserted in both the left and right directions simultaneously about a centerline (which is not necessarily the corridor baseline alignment). Furthermore, the attachment point may not be a point on the median surface links. For example, the attachment point for a depressed median subassembly may be above the median ditch at the elevation of the inside edges-of-traveled-way. Components Joining Two Roadways. When modeling separated roadways in a single corridor model, it is often necessary to insert intersection fill slopes, or to connect from one edge-of-roadway to another. Typically, you assemble the components for as much of the first roadway as possible, switch baselines and assemble the components for the second roadway, then use special subassemblies to connect between the two roadways. In this case, two attachment points are needed. Do this by creating a subassembly with a normal attachment point on one side, and which attaches to a previously defined marked point on the other. Rehabilitation and Overlay. Typically, subassemblies that are used to strip pavement, level, and overlay existing roads are placed based on calculations involving the shape of the existing roadway section, rather than using a design centerline alignment and profile. For example, a pavement overlay subassembly may require a minimum vertical distance from the existing pavement for a given design slope. A lane-widening subassembly may need to attach to the existing edge-of-traveled-way and match the existing lane slope.

Designing Custom Subassemblies | 147

User-defined vs. Hard-coded Parameters

Determine which of the geometric dimensions, behavior, and methodology will be hard-coded into the subassembly, and which will be controlled by user-defined input parameters. One approach is to specify that a majority of items can be controlled by user input. This can add time and complexity to using the subassembly. Another approach is to make it so that it cannot be adapted to different situations. Generally, widths, depths, and slopes should be variable, not fixed. A compromise is to include a larger number of inputs, but provide default values usable in most design situations. A good example of where to use hard-coded dimensions is with structural components, such as barriers and curb-and-gutter shapes. If there are five commonly-used variations of the same basic shape with different dimensions, it may be better to provide five separate subassemblies with hard-coded dimensions rather than making the user define the dimensions on a single subassembly. For example, users may be comfortable selecting from separate subassemblies for curb types A-E, which have predefined, hard-coded dimensions. You can always provide a generic subassembly with variable dimensions for scenarios where the common ones do not apply.

Input Parameter Types

The table below describes the various types of input parameters: Input Parameter
Widths

Offsets

% Slopes

Ratio Slopes

148 | Chapter 11 Creating Custom Subassemblies Using .NET

Input Parameter

Description
unsigned values, depending on circumstances. For example, a fill slope is always downward, so it may not be necessary to force the user to enter a value like -4.

Point, Link, and Shape Codes

In most cases, point, link, and shape codes should be hardcoded to ensure that consistent codes are assigned across the entire assembly. The primary exception is with generic link subassemblies that allow users to add links to the assembly as needed. These might be used for paved or unpaved finish grade, structural components, pavement subsurfaces, and many other unanticipated components. In these scenarios, the end-user assigns point, link, and shape codes that coordinate with the overall assembly.

Superelevation Behavior and Subassemblies

Make sure you consider differences in component behavior, such as when the roadway is in a normal crown condition or is in superelevation. Gutter and median subassemblies may also be designed to exhibit different behaviors in normal and superelevated sections. The superelevation properties of the corridor alignment define the lane and shoulder slopes at all stations on the roadway. However, the way these slopes are applied depends on a combination of how the subassemblies are manipulated in layout mode and the internal logic of the subassemblies. Different agencies have varying methodologies. The code behind the subassemblies makes it possible to adapt to just about any situation. Most importantly you need to determine where the superelevation pivot point is located, and how that point relates to the design profile grade line (PGL). Pivot point/PGL combinations that are commonly encountered include:

Pivot point and PGL are both at the crown of road. Pivot point and PGL are at the inside edge-of-traveled-way on a divided road. Pivot point and PGL are at one edge-of-traveled-way on an undivided road. Pivot point is at the edge-of-traveled-way on the inside of the curve, while the PGL is at the centerline of the road. On a divided road with crowned roadways, the PGL is at the crown points, while the pivot point is at the inside edge-of-traveled-ways. On a divided road with uncrowned roadways, the PGL and pivot point is above the median at the centerline.

Whatever the situation, the subassemblies must be designed so that they can be placed with the correct behavior. Sometimes the roadway components have special behavior in superelevated sections. Some examples of special superelevation behavior:

Broken Back Subbase. Some agencies put a break point in the subbase layer on the high side of superelevation. The subbase parallels the finish grade up to a certain point, then extends at a downward slope until it intersects the shoulder or clear zone link.

Superelevation Behavior and Subassemblies | 149

Shoulder Breakover. Usually a maximum slope difference, or breakover, must be maintained between the travel lane and the shoulder, or between the paved and unpaved shoulder links. Curbs-and-Gutters. Some agencies require that gutters on the high side of a superelevated road tip downward toward the low side, while others leave the gutters at their normal slope.

NOTE When writing your custom subassembly, avoid writing code that makes AutoCAD calls and interrupts Civil 3D subassembly operations during runtime. For example, avoid building selection sets.

Creating Subassembly Help Files

Each subassembly included in the AutoCAD Civil 3D Corridor Modeling catalog has a Help file that provides detailed construction and behavior information. You can display the Help file for the AutoCAD Civil 3D Corridor Modeling subassemblies using any of the following methods:

From a Tool Palette. Right-click a subassembly in a tool palette, then click Help. From a Tool Catalog. Right-click a subassembly in a tool catalog, then click Help. From the Subassembly Properties dialog box Parameters tab. Right-click a subassembly in the Prospector tree, then click Properties Parameters tab Subassembly Help.

When creating custom subassemblies, you should also create a custom Help file to accompany the subassembly. You can use just about any type of document file (.dwf, .doc, .pdf, .txt, .chm, .hlp) to create the subassembly Help file. For more information, see Creating Customized Help in the AutoCAD Developer Help. The Help file content and style should be similar to that in the AutoCAD Civil 3D Subassembly Reference Help. The table below describes the sections that should be included, as a minimum, in subassembly Help files. This information is required so that users understand the subassembly behavior and intended use. Section
Title

Descriptions

Subassembly Diagram

150 | Chapter 11 Creating Custom Subassemblies Using .NET

Section

Description
might attach to in a lighter line with a background color. Ideally, dimension lines and labels should also be a different color.

Attachment

Describes where the attachment point is located relative to the subassembly links. Describes each of the user-definable input parameters that can be specified when using the subassembly. These should precisely match the parameter names and order seen by the user when using the assembly layout tool, and should describe the effect of each parameter. These are best presented in a table that includes a description of each parameter, the type of input expected, and default values for metric or imperial unit projects. For input parameters for slope values, note that there are two common ways of specifying slopes: as a percent value like -2%, or as a run-to-rise ratio like 4 : 1. Any slope parameter should clearly specify which type is expected. In the subassemblies included in the AutoCAD Civil 3D Corridor Modeling catalog, the convention is to precede the word Slope with the % character in the parameter name if a percent slope is expected. Otherwise a ratio value is required. Note the practice of using positive numeric values for both cut and fill slopes. If a slope parameter is known to be used only in a fill condition, it should not be necessary for the user to have to specify a negative slope value. However, in a more generic situation, for example with the LinkWidthAndSlope subassembly, a signed value may be necessary. Describes the parameters in the subassembly that can be mapped to one or more target objects. Input parameters are defined when building an assembly in layout mode. Target parameters are substitutions that can be made for input parameters when applying the assembly to a corridor model. Typically, subassembly parameters that can use a target object to define a width or an offset can use the following types of objects to define that width or offset: alignments, AutoCAD polylines, feature lines, or survey figures. Similarly, subassembly parameters that can use a target object to define an elevation can use the following types of objects to define that elevation: profiles, AutoCAD 3D polylines, feature lines, or survey figures. Subassemblies that can use a target object to define a surface can only use a surface object to define that surface. A few subassemblies allow you to use pipe network objects as targets, such as the TrenchPipe subassemblies. A typical scenario is a travel lane where the width is a numeric input parameter, which can use an alignment as a target parameter to replace the numeric width. The given numeric width is used when displaying the lane in layout mode. If an alignment is given, the width is calculated at each station during corridor modeling to tie to the offset of the alignment. For more information, see Setting and Editing Targets in the AutoCAD Civil 3D User's Guide Help. Describes the behavior of the subassembly in detail. If necessary, this section should include diagrams showing different behaviors in different conditions. This section should provide both the subassembly programmer and the end user with all of the information needed to understand

Input Parameters

Target Parameters

Behavior

Creating Subassembly Help Files | 151

Section

Description
exactly what the subassembly does in all circumstances. Subheadings are recommended if the Behavior section covers several different topics.

Layout Mode Operation

During the process of creating an assembly from subassemblies, also known as the assembly layout mode, specific information such as alignment offsets, superelevation slopes, profile elevations, and surface data, are not known. The Layout Mode Operation section of the subassembly Help file describes how the subassembly is displayed in the assembly layout mode. Layout mode refers to an assembly that has not yet been applied to a corridor. Some subassemblies behave differently in different situations. For example, a Daylight type of subassembly may create different geometric shapes depending on whether it is in a cut or fill situation. Shoulders may behave differently for normal crown and superelevated roadways. In layout mode, the subassembly designer must specify some arbitrary choices as to how the subassembly is displayed. It should appear as much like the final result in the corridor model as possible. Lanes and shoulders, for example, should be shown at typical normal crown slopes. Where there is alternate geometry, such as for the cut and fill daylight cases, both cases should be shown. Also, links that extend to a surface should be shown with arrowheads indicating the direction of extension. A diagram illustrating layout mode behavior and visual representation is useful if layout mode behavior and/or visual representation of the subassembly differs significantly between layout mode when the assembly and its associated subassemblies are applied to a corridor. Describes the items that are hard-coded into the subassembly, including dimensions, point codes, link codes, and shape codes. Common practice is to reference the point, link, and shape codes to labels on the coding diagram. The coding diagram has a twofold purpose. First, it labels the point, link, and shape numbers referred to in the previous section. Secondly, it provides the subassembly programmer with a numbering scheme for points, links, and shapes. These should correspond to the array indices used in the script for points, links, and shapes. This is to make it easier to later modify or add to the subassembly.

Layout Mode Diagram

Point, Link, and Shape Codes

Coding Diagram

After creating the custom Help files for custom subassemblies, you must reference the Help files in the tool catalog .atc file associated with the subassemblies. For more information, see Sample Tool Catalog ATC Files (page 167).

152 | Chapter 11 Creating Custom Subassemblies Using .NET

Structure of Subassembly Programs

The Subassembly Template (SATemplate.vb)
All custom subassemblies are defined as classes that inherit from the SATemplate class. SATemplate provides four methods that you can override in your own class to provide functionality of your subassembly. They are described in the following table: Overridable Method
GetLogicalNamesImplement (input: CorridorState)

Purpose for Overriding

Define the list of target parameters that appear in the "Set All Logical Names" dialog box used when creating a corridor model. Define the list of input parameters, including their names, types, and default values. Define the list of output parameters, including their names, types, and default values. If a parameter is to be used for both input and output, that property is specified in this method. Must be overridden. Contains the code for accessing parameter values, adjusting the shape of the subassembly, and then adding the points, links, and shapes that make up your subassembly to an existing assembly.

GetInputParametersImplement (input: CorridorState) GetOutputParametersImplement (input: CorridorState)

DrawImplement (input: CorridorState)

SATemplate.vb is located in the <Civil 3D Install Directory>\Sample\Civil 3D API\C3DStockSubAssemblies directory.

The Corridor State Object

A reference to an object of type CorridorState is passed to each of the SATemplate methods you override. The CorridorState object is the primary interface between the custom subassembly and the collection of points, links, and shapes of the current assembly which the subassembly is to connect to. It provides references to the current alignment, profile, station, offset, elevation, and style, which may affect the appearance of the subassembly. It also includes several parameter buckets used for collecting parameters of types boolean, long, double, string, alignment, profile, surface, and point. Each parameter is defined by a literal name and a value. The CorridorState methods provide useful calculation functions for corridor design. These include the following:
IntersectAlignment Finds the intersection of a cross-sectional line with an offset alignment. Finds the intersection of a cross-sectional line with a link on the assembly. Finds the intersection of a cross-sectional line with a surface.

IntersectLink

IntersectSurface

Structure of Subassembly Programs | 153

IsAboveSurface SampleSection SoeToXyz XyzToSoe

Determines if a subassembly point is above or below a surface. Constructs a set of cross section links from a surface. Converts between station, offset, elevation coordinates and X,Y,Z coordinates.

Support Files (CodesSpecific.vb, Utilities.vb)

You can also use the two support files CodesSpecific.vb and Utilities.vb in your subassembly. CodesSpecific.vb provides the CodeType and AllCodes structures and the global variable Code - an instance of an AllCodes structure with all code information filled. Utilities.vb provides a series of shared helper functions for error handling, computing subassembly geometry, attaching code strings, and other tasks. For example, to report a parameter not found error to the AutoCAD Civil 3D event viewer, use the following line:
Utilities.RecordError( _ corridorState, _ CorridorError.ParameterNotFound, _ "Edge Offset", _ "BasicLaneTransition")

The following table lists all the functions within the Utility class: Utility function
RecordError RecordWarning AdjustOffset

Description
Sends an error message to the Event Viewer. Sends a warning to the Event Viewer. For a given offset from an offset baseline, this function computes the actual offset from the base baseline. Returns the version number of the subassembly as specified in the .atc file. Returns the assembly and the origin point for the subassembly. Given a surface Id, alignment Id, a station, and an offset from the station, this returns the elevation of the surface at that location. Returns an array of points along a curve where it will be tessellated, given a series of parameters describing the curve and how it is to be tessellated.

GetVersion

GetAlignmentAndOrigin

CalcElevationOnSurface

GetRoundingCurve

154 | Chapter 11 Creating Custom Subassemblies Using .NET

Utility function
CalcAlignmentOffsetToThisAlignment

Description
Calculates the offset from this alignment to an offset target, and returns the XY coordinate of the offset target at the point perpendicular to this alignment's station Adds a series of code strings to a particular link. The parameter i identifies which set of code strings to use. The parameter iLinks contains the collection of all links in an applied subassembly. The parameter linkIndex identifies which link in the link collection is given the code strings. The strArrCode parameter is a two-dimensional array of code strings. The first dimension identifies which set of codes to use, and the second dimension contains a variablelength array of code strings. Adds a series of code strings to a particular point. The parameter i identifies which set of code strings to use. The parameter iPoints contains the collection of all points in an applied subassembly. The parameter pointIndex identifies which point in the point collection is given the code strings. The strArrCode parameter is a two-dimensional array of code strings. The first dimension identifies which set of codes to use, and the second dimension contains a variable-length array of code strings. Returns True if the corridor is modeled in Imperial units, False if modeled in metric. Returns the value to go from the general units of measurement to smaller units of measurement. If the corridor is modeled in feet, this will return 12 to allow you to compute the number of inches. If the corridor is modeled in meters, this will return 1000 to allow you to compute the number of millimeters. Returns the percent slope of the alignment superelevation at the specified assembly section. The first parameter is a two-letter string indicates the part of the roadway to use. The first letter can be S for shoulder or L for lane. The second letter can be I for inside or O for outside. To determine the slope of the left side of the road, set the fourth parameter to True. To determine the slope of the right side, set the fourth parameter to False.

AddCodeToLink

AddCodeToPoint

IsProjectUnitsFeet

GetProjectUnitsDivisor

GetSlope

Support Files (CodesSpecific.vb, Utilities.vb) | 155

Utility function
AddPoints

Description
Given arrays of X and Y locations and code strings, this creates an array of Point objects (AeccRoadwayPoint objects) and a PointsCollection object (AeccRoadwayPoints object). Given the string name of a point, returns the point object.

GetMarkedPoint

The CodesSpecific.vb and Utilities.vb files are located in the <Civil Install Directory>\Sample\Civil 3D API\C3DStockSubAssemblies directory.

Sample VB.NET Subassembly

The following class module defines the BasicLaneTransition subassembly provided in the Stock Subassemblies catalog. The original source code for this and all other subassemblies that come with AutoCAD Civil 3D can be found in the <Civil 3D Install Directory>\Sample\Civil 3D API\C3DStockSubAssemblies\Subassemblies directory. Before reviewing the code you should familiarize yourself with the subassembly, how it behaves in the cut and fill conditions, the point and link codes to be assigned, and the point and link numbers specified in the subassembly coding diagram. Refer to the BasicLaneTransition subassembly Help for this information.

156 | Chapter 11 Creating Custom Subassemblies Using .NET

Option Explicit On Option Strict Off Imports Imports Imports Imports Imports Imports Imports Imports ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' ' System.Math Autodesk.AutoCAD.DatabaseServices Autodesk.Civil.Corridor Autodesk.Civil Autodesk.Civil.Alignment Autodesk.Civil.Profile Shape = Autodesk.Civil.Corridor.Shape DBTransactionManager = Autodesk.AutoCAD.DatabaseServices.TransactionManager

************************************************************************* ************************************************************************* ************************************************************************* Name: BasicLaneTransition Description: Creates a simple cross-sectional representation of a corridor lane composed of a single closed shape. Attachment origin is at top, most inside portion of lane. The lane can transition its width and cross-slope based on the position supplied by an optional horizontal and vertical alignment. Logical Names: Name Type Optional Default value Description -------------------------------------------------------------TargetHA Alg yes none Horizontal alignment to transition to TargetVA Profile yes none Vertical alignment to transition to Parameters: Name Type Optional Default Value Description -----------------------------------------------------------------Side long yes Right specifies side to place SA on Width double yes 12.0 width of lane Depth double yes 0.667 depth of coarse Slope double yes -0.02 cross-slope of lane TransitionType long yes 2 hold grade, move to offset HA *************************************************************************

Public Class BasicLaneTransition Inherits SATemplate

Private Enum TransitionTypes ' Transition types supported kHoldOffsetAndElevation = 0 kHoldElevationChangeOffset = 1 kHoldGradeChangeOffset = 2 kHoldOffsetChangeElevation = 3 kChangeOffsetAndElevation = 4 End Enum ' -------------------------------------------------------------------------' Default values for input parameters Private Const SideDefault = Utilities.Right Private Const LaneWidthDefault = 12.0# Private Const LaneDepthDefault = 0.667 Private Const LaneSlopeDefault = -0.02 '0.25 inch per foot Private Const HoldOriginalPositionDefault = TransitionTypes.kHoldOffsetAndElevation

Sample VB.NET Subassembly | 157

Protected Overrides Sub GetLogicalNamesImplement(ByVal corridorState As CorridorState) MyBase.GetLogicalNamesImplement(corridorState)

' Retrieve parameter buckets from the corridor state Dim oParamsLong As ParamLongCollection oParamsLong = corridorState.ParamsLong ' Add the logical names we use in this script Dim oParamLong As ParamLong oParamLong = oParamsLong.Add("TargetHA", ParamLogicalNameType.OffsetTarget) oParamLong.DisplayName = "690" oParamLong = oParamsLong.Add("TargetVA", ParamLogicalNameType.ElevationTarget) oParamLong.DisplayName = "691"

End Sub Protected Overrides Sub GetInputParametersImplement(ByVal corridorState As CorridorState) MyBase.GetInputParametersImplement(corridorState) ' Retrieve parameter buckets from the corridor state Dim oParamsLong As ParamLongCollection oParamsLong = corridorState.ParamsLong Dim oParamsDouble As ParamDoubleCollection oParamsDouble = corridorState.ParamsDouble ' Add the input parameters we use in this script oParamsLong.Add(Utilities.Side, SideDefault) oParamsDouble.Add("Width", LaneWidthDefault) oParamsDouble.Add("Depth", LaneDepthDefault) oParamsDouble.Add("Slope", LaneSlopeDefault) oParamsLong.Add("TransitionType", HoldOriginalPositionDefault) End Sub

Protected Overrides Sub DrawImplement(ByVal corridorState As CorridorState)

' Retrieve parameter buckets from the corridor state Dim oParamsDouble As ParamDoubleCollection oParamsDouble = corridorState.ParamsDouble Dim oParamsLong As ParamLongCollection oParamsLong = corridorState.ParamsLong Dim oParamsOffsetTarget As ParamOffsetTargetCollection oParamsOffsetTarget = corridorState.ParamsOffsetTarget Dim oParamsElevationTarget As ParamElevationTargetCollection oParamsElevationTarget = corridorState.ParamsElevationTarget

158 | Chapter 11 Creating Custom Subassemblies Using .NET

'--------------------------------------------------------' flip about Y-axis Dim vSide As Long Try vSide = oParamsLong.Value(Utilities.Side) Catch vSide = SideDefault End Try

Dim dFlip As Double dFlip = 1.0# If vSide = Utilities.Left Then dFlip = -1.0# End If '--------------------------------------------------------' Transition type Dim vTransitionType As Long Try vTransitionType = oParamsLong.Value("TransitionType") Catch vTransitionType = HoldOriginalPositionDefault End Try

'--------------------------------------------------------' BasicLaneTransition dimensions Dim vWidth As Double Try vWidth = oParamsDouble.Value("Width") Catch vWidth = LaneWidthDefault End Try

Dim vDepth As Double Try vDepth = oParamsDouble.Value("Depth") Catch vDepth = LaneDepthDefault End Try

Dim vSlope As Double Try vSlope = oParamsDouble.Value("Slope")

Sample VB.NET Subassembly | 159

Catch vSlope = LaneSlopeDefault End Try '------------------------------------------------------' Get version, and convert values if necessary Dim sVersion As String sVersion = Utilities.GetVersion(corridorState) If sVersion <> Utilities.R2005 Then 'need not change Else 'R2005 'convert %slope to tangent value vSlope = vSlope / 100 End If '--------------------------------------------------------' Check user input If vWidth <= 0 Then Utilities.RecordError(corridorState, _ CorridorError.ValueShouldNotBeLessThanOrEqualToZero, _ "Width", "BasicLaneTransition") vWidth = LaneWidthDefault End If If vDepth <= 0 Then Utilities.RecordError(corridorState, _ CorridorError.ValueShouldNotBeLessThanOrEqualToZero, _ "Depth", "BasicLaneTransition") vDepth = LaneDepthDefault End If

' Calculate the current alignment and origin according to the assembly offset Dim oCurrentAlignmentId As ObjectId Dim oOrigin As New PointInMem Utilities.GetAlignmentAndOrigin(corridorState, oCurrentAlignmentId, oOrigin) '--------------------------------------------------------' Define codes for points, links and shapes Dim sPointCodeArray(0 To 4, 0) As String Dim sLinkCodeArray(0 To 2, 0 To 1) As String Dim sShapeCodeArray(0 To 1) As String FillCodesFromTable(sPointCodeArray, sLinkCodeArray, sShapeCodeArray) '--------------------------------------------------------' Get alignment and profile we're currently working from Dim offsetTarget As WidthOffsetTarget 'width or offset target offsetTarget = Nothing Dim elevationTarget As SlopeElevationTarget 'slope or elevation target elevationTarget = Nothing Dim dOffsetToTargetHA As Double

160 | Chapter 11 Creating Custom Subassemblies Using .NET

Dim dOffsetElev As Double If corridorState.Mode = CorridorMode.Layout Then vTransitionType = TransitionTypes.kHoldOffsetAndElevation End If Dim dXOnTarget As Double Dim dYOnTarget As Double Select Case vTransitionType Case TransitionTypes.kHoldOffsetAndElevation Case TransitionTypes.kHoldElevationChangeOffset 'oHA must exist Try offsetTarget = oParamsOffsetTarget.Value("TargetHA") Catch 'Utilities.RecordError(corridorState, _ CorridorError.ParameterNotFound, "Edge Offset", "BasicLaneTransition") 'Exit Sub End Try 'get offset to targetHA If False = Utilities.CalcAlignmentOffsetToThisAlignment(_ oCurrentAlignmentId, corridorState.CurrentStation, _ offsetTarget, Utilities.GetSide(vSide), _ dOffsetToTargetHA, dXOnTarget, dYOnTarget) Then Utilities.RecordWarning(corridorState, _ CorridorError.LogicalNameNotFound, _ "TargetHA", "BasicLaneTransition") dOffsetToTargetHA = vWidth + oOrigin.Offset Else If (dOffsetToTargetHA = oOrigin.Offset) Or _ ((dOffsetToTargetHA > oOrigin.Offset) And _ (vSide = Utilities.Left)) Or _ ((dOffsetToTargetHA < oOrigin.Offset) And _ (vSide = Utilities.Right)) _ Then Utilities.RecordWarning(corridorState, _ CorridorError.ValueInABadPosition, "TargetHA", "BasicLaneTransition") dOffsetToTargetHA = vWidth + oOrigin.Offset End If End If

Case TransitionTypes.kHoldGradeChangeOffset 'oHA must exist Try offsetTarget = oParamsOffsetTarget.Value("TargetHA") Catch 'Utilities.RecordError(corridorState, _ CorridorError.ParameterNotFound, "Edge Offset", "BasicLaneTransition") 'Exit Sub End Try 'get offset to targetHA If False = Utilities.CalcAlignmentOffsetToThisAlignment(_

Sample VB.NET Subassembly | 161

oCurrentAlignmentId, corridorState.CurrentStation, offsetTarget,_ Utilities.GetSide(vSide), dOffsetToTargetHA, dXOnTarget, dYOnTarget) _ Then Utilities.RecordWarning(corridorState, _ CorridorError.LogicalNameNotFound, _ "TargetHA", "BasicLaneTransition") dOffsetToTargetHA = vWidth + oOrigin.Offset Else If (dOffsetToTargetHA = oOrigin.Offset) Or _ ((dOffsetToTargetHA > oOrigin.Offset) And _ (vSide = Utilities.Left)) Or _ ((dOffsetToTargetHA < oOrigin.Offset) And _ (vSide = Utilities.Right)) Then Utilities.RecordWarning(corridorState, _ CorridorError.ValueInABadPosition, "TargetHA", "BasicLaneTransition") dOffsetToTargetHA = vWidth + oOrigin.Offset End If End If Case TransitionTypes.kHoldOffsetChangeElevation 'oVA must exist Try elevationTarget = oParamsElevationTarget.Value("TargetVA") Catch 'Utilities.RecordError(corridorState, _ CorridorError.ParameterNotFound, _ "Edge Elevation", "BasicLaneTransition") 'Exit Sub End Try Dim db As Database = HostApplicationServices.WorkingDatabase Dim tm As DBTransactionManager = db.TransactionManager Dim oProfile As Profile = Nothing 'get elevation on elevationTarget Try dOffsetElev = elevationTarget.GetElevation(oCurrentAlignmentId, _ corridorState.CurrentStation, Utilities.GetSide(vSide)) Catch Utilities.RecordWarning(corridorState, _ CorridorError.LogicalNameNotFound, _ "TargetHA", "BasicLaneTransition") dOffsetElev = corridorState.CurrentElevation + vWidth * vSlope End Try

Case TransitionTypes.kChangeOffsetAndElevation 'both oHA and oVA must exist Try offsetTarget = oParamsOffsetTarget.Value("TargetHA") Catch 'Utilities.RecordError(corridorState, _ CorridorError.ParameterNotFound, _ "Edge Offset", "BasicLaneTransition")

162 | Chapter 11 Creating Custom Subassemblies Using .NET

'Exit Sub End Try Try elevationTarget = oParamsElevationTarget.Value("TargetVA") Catch 'Utilities.RecordError(corridorState, _ CorridorError.ParameterNotFound, _ "Edge Elevation", "BasicLaneTransition") 'Exit Sub End Try

'get elevation on elevationTarget Try dOffsetElev = elevationTarget.GetElevation(oCurrentAlignmentId, _ corridorState.CurrentStation, Utilities.GetSide(vSide)) Catch Utilities.RecordWarning(corridorState, _ CorridorError.LogicalNameNotFound, _ "TargetHA", "BasicLaneTransition") dOffsetElev = corridorState.CurrentElevation + vWidth * vSlope End Try 'get offset to targetHA If False = Utilities.CalcAlignmentOffsetToThisAlignment(_ oCurrentAlignmentId, corridorState.CurrentStation, offsetTarget, _ Utilities.GetSide(vSide), dOffsetToTargetHA, dXOnTarget, dYOnTarget) _ Then Utilities.RecordWarning(corridorState, _ CorridorError.LogicalNameNotFound, _ "TargetHA", "BasicLaneTransition") dOffsetToTargetHA = vWidth + oOrigin.Offset Else If (dOffsetToTargetHA = oOrigin.Offset) Or _ ((dOffsetToTargetHA > oOrigin.Offset) And _ (vSide = Utilities.Left)) Or _ ((dOffsetToTargetHA < oOrigin.Offset) And _ (vSide = Utilities.Right)) _ Then Utilities.RecordWarning(corridorState, _ CorridorError.ValueInABadPosition, "TargetHA", "BasicLaneTransition") dOffsetToTargetHA = vWidth + oOrigin.Offset End If End If End Select '--------------------------------------------------------' Create the subassembly points

Dim corridorPoints As PointCollection corridorPoints = corridorState.Points

Sample VB.NET Subassembly | 163

Dim dX As Double Dim dy As Double dX = 0.0# dy = 0.0# Dim oPoint1 As Point oPoint1 = corridorPoints.Add(dX, dy, "") ' compute outside position of lane Select Case vTransitionType Case TransitionTypes.kHoldOffsetAndElevation ' hold original position (always used in layout mode) dX = vWidth dy = Abs(vWidth) * vSlope Case TransitionTypes.kHoldElevationChangeOffset ' hold original elevation, move offset to that of TargetHA 'dX = Abs(dOffsetToTargetHA - corridorState.CurrentSubassemblyOffset) dX = Abs(dOffsetToTargetHA - oOrigin.Offset) dy = Abs(vWidth) * vSlope Case TransitionTypes.kHoldGradeChangeOffset ' hold original grade, move offset to that of TargetHA ' (also used if TargetVA is not defined) 'dX = Abs(dOffsetToTargetHA - corridorState.CurrentSubassemblyOffset) dX = Abs(dOffsetToTargetHA - oOrigin.Offset) dy = Abs(dX) * vSlope Case TransitionTypes.kHoldOffsetChangeElevation ' hold original offset, but change elevation to that of TargetVA dX = vWidth 'dY = dOffsetElev - corridorState.CurrentSubassemblyElevation dy = dOffsetElev - oOrigin.Elevation Case TransitionTypes.kChangeOffsetAndElevation ' move position to that of TargetHA, and elevation to that of TargetVA dX = Abs(dOffsetToTargetHA - oOrigin.Offset) dy = dOffsetElev - oOrigin.Elevation End Select '-----------------------------------------------------------------Dim dActualWidth As Double dActualWidth = dX Dim dActualSlope As Double If 0 = dActualWidth Then dActualSlope = 0.0# Else

164 | Chapter 11 Creating Custom Subassemblies Using .NET

dActualSlope = dy / Abs(dActualWidth) End If '------------------------------------------------------------------

Dim oPoint2 As Point oPoint2 = corridorPoints.Add(dX * dFlip, dy, "") dX = dX - 0.001 dy = dy - vDepth Dim oPoint3 As Point oPoint3 = corridorPoints.Add(dX * dFlip, dy, "") dX = 0.0# dy = -vDepth Dim oPoint4 As Point oPoint4 = corridorPoints.Add(dX, dy, "") Utilities.AddCodeToPoint(1, Utilities.AddCodeToPoint(2, Utilities.AddCodeToPoint(3, Utilities.AddCodeToPoint(4, corridorPoints, corridorPoints, corridorPoints, corridorPoints, oPoint1.Index, oPoint2.Index, oPoint3.Index, oPoint4.Index, sPointCodeArray) sPointCodeArray) sPointCodeArray) sPointCodeArray)

'--------------------------------------------------------' Create the subassembly links Dim oCorridorLinks As LinkCollection oCorridorLinks = corridorState.Links Dim oPoint(1) As Point Dim oLink(3) As Link oPoint(0) = oPoint1 oPoint(1) = oPoint2 oLink(0) = oCorridorLinks.Add(oPoint, "") 'L1 oPoint(0) = oPoint2 oPoint(1) = oPoint3 oLink(1) = oCorridorLinks.Add(oPoint, "") 'L2 oPoint(0) = oPoint3 oPoint(1) = oPoint4 oLink(2) = oCorridorLinks.Add(oPoint, "") 'L3 oPoint(0) = oPoint4 oPoint(1) = oPoint1 oLink(3) = oCorridorLinks.Add(oPoint, "") 'L4 Utilities.AddCodeToLink(1, oCorridorLinks, oLink(0).Index, sLinkCodeArray) Utilities.AddCodeToLink(2, oCorridorLinks, oLink(2).Index, sLinkCodeArray) '--------------------------------------------------------' Create the subassembly shapes Dim corridorShapes As ShapeCollection

Sample VB.NET Subassembly | 165

corridorShapes = corridorState.Shapes

corridorShapes.Add(oLink, sShapeCodeArray(1)) '--------------------------------------------------------'--------------------------------------------------------' Write back all the Calculated values of the input parameters into ' the RoadwayState object. ' Because they may be different from the default design values, ' we should write them back to make sure that the RoadwayState object ' contains the Actual information of the parameters. oParamsLong.Add(Utilities.Side, vSide) oParamsDouble.Add("Width", Math.Abs(dActualWidth)) oParamsDouble.Add("Depth", vDepth) oParamsDouble.Add("Slope", dActualSlope) oParamsLong.Add("TransitionType", vTransitionType) End Sub Protected Sub FillCodesFromTable(ByVal sPointCodeArray(,) As String, _ ByVal sLinkCodeArray(,) As String, ByVal sShapeCodeArray() As String) sPointCodeArray(1, 0) = Codes.Crown.Code sPointCodeArray(2, 0) = Codes.ETW.Code sPointCodeArray(3, 0) = Codes.ETWSubBase.Code 'P4 sPointCodeArray(4, 0) = Codes.CrownSubBase.Code 'P3 sLinkCodeArray(1, sLinkCodeArray(1, sLinkCodeArray(2, sLinkCodeArray(2, 0) 1) 0) 1) = = = = Codes.Top.Code Codes.Pave.Code Codes.Datum.Code Codes.SubBase.Code

sShapeCodeArray(1) = Codes.Pave1.Code End Sub End Class

The Subassembly Tool Catalog

Overview
An Autodesk tool catalog organizes groups of customized subassemblies and makes them available to AutoCAD Civil 3D users. Autodesk tool catalogs are defined using xml-formatted files with an .atc (Autodesk Tool Catalog) extension. You also need to create a catalog registry file as catalogs must be registered in the Windows registry. Some items within the .atc and registry files must contain unique identifiers known as GUIDs (Global Unique Identifiers). New GUIDs can be created using the GuidGen.exe utility that is included with many Microsoft development products and is freely available for download from the Microsoft web site. To create a tool catalog for a subassembly 1 Using Notepad or any other appropriate editor, create a plain ASCII text file named <Name>Tools Catalog.atc, where <Name> is the name of this new tool catalog. For information about the contents of the file, see Creating a Tool Catalog ATC File (page 167).

166 | Chapter 11 Creating Custom Subassemblies Using .NET

2 Save the .atc file to the location where your tool catalogs are stored. The default location is C:\Documents and Settings\All Users\Application Data\Autodesk\C3D 2009\enu\Tool Catalogs\Road Catalog. 3 Create any optional files, such as images for icons displayed in the catalog and help files for subassemblies, and place these files in appropriate locations for reference. 4 Using Notepad or any other text editor, create a registry file for the tool catalog with the extension .reg. For more information, see Creating a Tool Catalog Registry File (page 176). 5 Register the tool catalog by double-clicking on the .reg file. Once registered, the subassembly tool catalog will be displayed in the AutoCAD Civil 3D Content Browser.

Creating a Tool Catalog ATC File

Sample Tool Catalog ATC Files
The sample tool catalog .atc files define the contents and organization of an Autodesk subassembly tool catalog. These are generally split into separate files to keep files manageable: one listing all categories of tools and others listing tools within a single category.

Main Catalog File Example

The following is a portion of the file AutoCAD Civil 3D Metric Corridor Catalog.atc. It contains a list of tool categories. See the table following the sample for descriptions of the contents. This excerpt only contains the Getting Started category of tools.

Creating a Tool Catalog ATC File | 167

1) <Catalog option="0"> 2) <ItemID idValue="{0D75EF58-D86B-44DF-B39E-CE39E96077EC}"/> 3) <Properties> 4) <ItemName resource="9250" src="AeccStockSubassemblyScriptsRC.dll"/> 5) <Images option="0"> 6) <Image cx="93" cy="123" src=".\Images\AeccCorridorModel.png"/> 7) </Images> 8) <Description resource="9201" src="AeccStockSubassemblyScriptsRC.dll"/> 9) <AccessRight>1</AccessRight> 10) <Time createdUniversalDateTime="2003-01-22T00:31:56" modifiedUniversalDateTime="200609-04T13:28:12"/> 11) </Properties> 12) <Source> 13) <Publisher> 14) <PublisherName>Autodesk</PublisherName> 15) </Publisher> 16) </Source> 17) <Tools/> 18) <Palettes/> 19) <Packages/> 20) <Categories> 21) <Category option="0"> 22) <ItemID idValue="{4F5BFBF8-11E8-4479-99E0-4AA69B1DC292}"/> 23) <Url href=".\\C3D Metric Getting Started Subassembly Catalog.atc"/> 24) <Properties> 25) <ItemName resource="9212" src="AeccStockSubassemblyScriptsRC.dll"/> 26) <Images option="0"> 27) <Image cx="93" cy="123" src=".\Images\AeccGenericSubassemblies.png"/> 28) </Images> 29) <Description resource="9213" src="AeccStockSubassemblyScriptsRC.dll"/> 30) <AccessRight>1</AccessRight> 31) </Properties> 32) <Source/> 33) </Category> 34) 35)  36) 37) </Categories> 38) <StockTools/> 39) <Catalogs/> 40) </Catalog>

Line Number
1-40

Description
The <Catalog> section contains the entire contents of the catalog file. This <ItemID> defines the GUID for the catalog. The same GUID must be used in the registry file to identify this catalog. This section defines general properties of the catalog. <ItemName> defines the name that appears beneath the catalog icon in the catalog browser. In this case, we use a string resource

3-11 4

168 | Chapter 11 Creating Custom Subassemblies Using .NET

Line Number

Description
to support localization. You can also specify a constant string by using the line <ItemName>Name</ItemName>.

5-7

<Images> defines the image file for the icon that appears for the catalog in the catalog browser. Images used for catalogs and subassemblies should be a 64-by-64 pixel image. Valid image file types include .bmp, .gif, .jpg, and .png. <Description> contains the string description for the catalog. In this case, we use a string resource to support localization. You can also specify a constant string by using the line <Description>String</Description>. <Time> defines the time and date the catalog was created in the universal date/time format. This information is required, but not used. Any date or time may be given. <Source> defines the source or creator of the catalog. Empty definitions for Tools, Palettes, and Packages. The <Categories> group defines a list of categories, each of which may contain sub-categories or subassembly tools. Definition of the Getting Started category. This block has been designed to load all category information from a separate file. Category information can also be placed within this file if you only want one .atc file by using a <Category> section as described in the Tool File Example (page 170) <ItemID> defines the unique GUID for this category. It must be the same GUID as in the separate category .atc file. <Url> specifies the location of the category .atc file. The properties of a category. <ItemName> defines the name of this category of tools. In this case, we use a string resource to support localization. You can also specify a constant string by using the line <ItemName>Name</ItemName>. Sets the image used to identify the category to users. <Description> contains the string description for the category. In this case, we use a string resource to support localization. You can also specify a constant string by using the line <Description>String</Description>.

12-16 17-19 20-36

21-33

23 24-31 25

26-28 29

Creating a Tool Catalog ATC File | 169

Line Number
32 39

Description
Empty definition for Source. Empty definition for StockTools

Tool File Example

The following is a portion of the AutoCAD Metric Getting Started Subassembly Catalog.atc file. It contains all the tools in the Getting Started catalog. This excerpt only contains the BasicBarrier tool.

170 | Chapter 11 Creating Custom Subassemblies Using .NET

1) <Category> 2) <ItemID idValue="{4F5BFBF8-11E8-4479-99E0-4AA69B1DC292}"/> 3) <Properties> 4) <ItemName src="AeccStockSubassemblyScriptsRC.dll" resource="9212"/> 5) <Images> 6) <Image cx="93" cy="123" src=".\Images\AeccGenericSubassemblies.png"/> 7) </Images> 8) <Description src="AeccStockSubassemblyScriptsRC.dll" resource="9213"/> 9) <AccessRight>1</AccessRight> 10) <Time createdUniversalDateTime="2002-09-16T14:23:31" modifiedUniversalDateTime="200406-17T07:08:09"/> 11) </Properties> 12) <CustomData/> 13) <Source/> 14) <Palettes/> 15) <Packages/> 16) <Tools> 17) <Tool> 18) <ItemID idValue="{F6F066F4-ABF2-4838-B007-17DFDDE2C869}"/> 19) <Properties> 20) <ItemName resource="101" src="AeccStockSubassemblyScriptsRC.dll"/> 21) <Images> 22) <Image cx="64" cy="64" src=".\Images\AeccBasicBarrier.png"/> 23) </Images> 24) <Description resource="102" src="AeccStockSubassemblyScriptsRC.dll"/> 25) <Keywords>_barrier subassembly</Keywords> 26) <Help> 27) <HelpFile>.\Help\C3DStockSubassemblyHelp.chm</HelpFile> 28) <HelpCommand>HELP_HHWND_TOPIC</HelpCommand> 29) <HelpData>SA_BasicBarrier.htm</HelpData> 30) </Help> 31) <Time createdUniversalDateTime="2002-04-05T21:58:00" modifiedUniversalDateTime="200204-05T21:58:00"/> 32) </Properties> 33) <Source/> 34) <StockToolRef idValue="{7F55AAC0-0256-48D7-BFA5-914702663FDE}"/> 35) <Data> 36) <AeccDbSubassembly> 37) <GeometryGenerateMode>UseDotNet</GeometryGenerateMode> 38) <DotNetClass Assembly="%AECCCONTENT_DIR%\C3DStockSubassemblies.dll">Subassembly.Ba sicBarrier</DotNetClass> 39) <Resource Module="AeccStockSubassemblyScriptsRC.dll"/> 40) <Content DownloadLocation="http://www.autodesk.com/subscriptionlogin"/> 41) <Params> 42) <Version DataType="String" DisplayName="Version" Description="Ver sion">R2007</Version> 43) <TopWidth DataType="Double" TypeInfo="16" DisplayName="105" Descrip tion="106">0.15</TopWidth> 44) <MiddleWidth DataType="Double" TypeInfo="16" DisplayName="107" Descrip tion="108">0.225</MiddleWidth> 45) <CurbWidth DataType="Double" TypeInfo="16" DisplayName="109" Descrip tion="110">0.57</CurbWidth> 46) <BottomWidth DataType="Double" TypeInfo="16" DisplayName="111" Descrip tion="112">0.6</BottomWidth> 47) <TopHeight DataType="Double" TypeInfo="16" DisplayName="113" Descrip tion="114">0.9</TopHeight>

Creating a Tool Catalog ATC File | 171

48) <MiddleHeight DataType="Double" TypeInfo="16" DisplayName="115" Descrip tion="116">0.45</MiddleHeight> 49) <CurbHeight DataType="Double" TypeInfo="16" DisplayName="117" Descrip tion="118">0.075</CurbHeight> 50) </Params> 51) </AeccDbSubassembly> 52) <Units>m</Units> 53) </Data> 54) </Tool> 55) 56)  57) 58) </Tools> 59) <StockTools/> 60) </Category>

Line Number
1-59 2

Description
A <Category> is a list of subassemblies. <ItemID> defines the unique GUID for this category. It must be the same GUID as in the parent catalog .atc file. The properties of a category. <ItemName> defines the name of this category of tools. In this case, we use a string resource to support localization. You can also specify a constant string by using the line <ItemName>Name</ItemName>. Sets the image used to identify the category to users. <Description> contains the string description for the category. In this case, we use a string resource to support localization. You can also specify a constant string by using the line <Description>String</Description>. Empty definitions for Custom Data, Source, Palettes, Packages. <Tools> contains all the separate subassemblies. <Tool> represents a single subassembly. <ItemID> defines the unique GUID for this subassembly. The properties of the subassembly. <ItemName> defines the name of this subassembly. In this case, we use a string resource to support localization. You can also specify a constant string by using the line <ItemName>Name</ItemName>.

3-11 4

5-7 8

12-15 16-57 17-53 18 19-32 20

172 | Chapter 11 Creating Custom Subassemblies Using .NET

Line Number
21-23 24

Description
Sets the image used to identify the subassembly to users. <Description> defines the name of this subassembly. In this case, we use a string resource to support localization. You can also specify a constant string by using the line <Description>String</Description>. Keywords describing the subassembly. <HelpFile> defines the filename and path of the help file. <HelpCommand> defines the command used to display the help file. <HelpData> is the particular topic in the help file to display. <Time> defines the time and date the catalog was created in the universal date/time format. This information is required, but not used. Any date or time may be given. Empty Source tag. <StockToolRef> defines a GUID specifically for catalog tools. This must use the idVlaue of {7F55AAC0-0256-48D7-BFA5914702663FDE} Describes the nature of the subassembly. Identifies the tool as a subassembly. <GeometryGenerateMode> is a new tag that describes the source code of the subassembly. It can either have a value of UseDotNet or UseVBA. If this tag is not used, UseVBA is assumed. <DotNetClass> is a new tag that lists the .NET assembly and class which contain the subassembly. The VBA equivalent is the <Macro> tag. The .dll containing the resource strings and images used by the subassembly tool. <Content> is a new tag that specifies a location where you can download the subassembly if it isnt located on the local machine. If the subassembly hasnt been downloaded, the location contained in the DownloadLocation attribute is displayed in the event viewer.

25 27 28

29 31

33 34

35-52 36-50 37

Creating a Tool Catalog ATC File | 173

Line Number
41-50

Description
<Params> defines the names of the input parameters associated with the subassembly tool. This list appears in the Properties page of the subassembly, in the order they appear in the .atc file. Each parameter is defined on a single line. Each parameter is described with the following: Parameter name - The internal name of the parameter (e.g., CrownHeight). This is the name that must be used when saving or retrieving parameters to the parameter buckets. DataType Defines the type of variable used to store the parameter value, such as Long, Double, or String. For more information, see Tool Catalog Data Type Information (page 174). DisplayName Defines the name that is displayed for the parameter in the subassembly Properties page. This is what the user sees to identify each parameter. Description Provides a description of the input parameter. When a parameter name is highlighted in the subassembly Properties page, the description appears at the bottom of the page. value The default value for the parameter. This is the value that appears for the parameter in the subassembly Properties page. <Units> describes the type of units the subassembly expects. Valid values are m for meters of foot for feet.

42-49

Tool Catalog Data Type Information

The following tables describe the data types that can be used to define the variable that stores parameter values in the corridor modeling tool catalog .atc file. Boolean Data Types Data Type
Bool BoolNoYes BoolDisabledEnabled BoolOffOn BoolRightLeft

Type String
0 1 5 6 7

Description
0 = True; 1 = False. 0 = Yes; 1 = No. 0 = Enabled; 1 = Disabled. 0 = On; 1 = Off. 0 = Right; 1 = Left.

Long Data Types Data Type

Long NonZeroLong

Type String
0 1

Description
Any integer Any non-zero integer

174 | Chapter 11 Creating Custom Subassemblies Using .NET

Data Type
NonNegativeLong NonNegativeNonZeroLong NonPositiveLong NonPositiveNonZeroLong

Type String
2 3 4 5

Description
Zero or any positive integer Any non-zero positive integer Zero or any negative integer Any non-zero negative integer

Double Data Types Data Types

Double NonNegativeDouble NonNegativeNonZeroDouble

Type String
0 1 2

Description
Any double value Zero or any positive double value Any non-zero positive double value Zero or any negative double value Any non-zero negative double value Any non-zero double value Slope or grade input values Grade input values Slope input values Angular values Convergence angular value Distance values in feet or meters Dimension values in inches or millimeters Elevation values Percent values

NonPositiveDouble NonPositiveNonZeroDouble

3 4

NonZeroDouble Grade TransparentCmdGrade TransparentCmdSlope Angle ConvergenceAngle Distance Dimension

5 8 9 10 14 15 16 17

Elevation Percent

21 25

Creating a Tool Catalog ATC File | 175

Creating a Tool Catalog Cover Page

Use an .html file to create introductory content that will display when a user clicks on this new catalog in the AutoCAD Civil 3D Content Browser. You can use any html editor, and the cover page can be as simple or as comprehensive as you like. Typically, the cover page gives an overview of the tools supplied in the catalog, and a brief description of how they may be used. By convention, cover pages are named <Name> - ToolCatalogCoverPage.html where <Name> is the name of the new tool catalog. The location of the .html file is specified within the .atc file. This file is usually placed in the same directory as the .atc files themselves.

Creating a Tool Catalog Registry File

Each subassembly tool catalog needs to be registered in the Windows registry before it can be used by AutoCAD Civil 3D. One way to do this is to create a .reg file, which is a text file containing the new keys, value names, and values to be added to the registry. Double-clicking on the .reg file will modify the registry. After this process, the .reg file is no longer needed. The following is the contents of a .reg file that registers the Autodesk Civil 3D Imperial Corridor Catalog.atc catalog file. See the table following the sample for descriptions of the contents.
1) REGEDIT4 2) 3) [HKEY_CURRENT_USER\Software\Autodesk\Autodesk Content Browser\55] 4) 5) [HKEY_CURRENT_USER\Software\Autodesk\Autodesk Content Browser\55\RegisteredGroups] 6) 7) [HKEY_CURRENT_USER\Software\Autodesk\Autodesk Content Browser\55\RegisteredGroups\Roads Group] 8) "ItemID"="{5BD79109-BC69-41eb-9AC8-7E9CD469C8D3}" 9) "ItemName"="Roads Group" 10) 11) 12) [HKEY_CURRENT_USER\Software\Autodesk\Autodesk Content Browser\55\RegisteredCatalogs] 13) 14) [HKEY_CURRENT_USER\Software\Autodesk\Autodesk Content Browser\55\RegisteredCata logs\Autodesk Civil 3D Imperial Corridor Catalog] 15) "ItemID"="{410D0B43-19B3-402f-AB41-05A6E174AA3F}" 16) "Image"=".\\Images\\AeccRoadway.png" 17) "Url"="C:\\Documents and Settings\\All Users\\Application Data\\Autodesk\\C3D 2009\\enu\\Tool Catalogs\\Road Catalog\\Autodesk Civil 3D Imperial Corridor Catalog.atc" 18) "DisplayName"="Civil 3D Subassemblies (Imperial Units)" 19) "Description"="Imperial Units Subassemblies" 20) "Publisher"="Autodesk" 21) "ToolTip"="Autodesk Civil 3D Imperial Corridor Catalog" 22) "GroupType"="{5BD79109-BC69-41eb-9AC8-7E9CD469C8D3}" 23) 24) 25) [HKEY_CURRENT_USER\Software\Autodesk\AutoCAD\R17.1\ACAD-6000:409\AEC\55\General\Tools] 26) "ToolContentRoot"="C:\\Documents and Settings\\All Users\\Application Data\\Autodesk\\C3D 2009\\enu\\Tool Catalogs\\Road Catalog"

Line Number
1

Description
Identifies the file as a registry edit file.

176 | Chapter 11 Creating Custom Subassemblies Using .NET

Line Number
3-9

Description
These statements create a Group for the Autodesk Content Browser. The group id name is Roads Group. Each group must have a unique GUID for the ItemID. The Roads Group is already registered by the Civil 3D installation. If you are adding a catalog to this group, you should use the GUID shown in the example. Identifies the item being registered as an Autodesk catalog for the Autodesk Content Browser. These statements define the Catalog Entry. ItemId must be a unique GUID for this catalog. This must match the GUID for the Catalog ItemID value in the catalog .atc file. Image must be a unique GUID for this catalog. This must match the GUID for the Catalog ItemID value in the catalog .atc file. URL is a pointer to the catalog .atc file that is being registered. DisplayName is the text that displays beneath the catalog icon in the Autodesk Content Browser. Description description of the tool catalog. Publisher name of the creator / publisher of the tool catalog. ToolTip the text that displays for the tooltip when the cursor is hovered over the tool catalog in the Catalog Browser. GroupType the GUID that defines which the tool catalog belongs to in the Catalog Browser. This GUID must match the one used for the ItemID in the group definition. The directory where the .atc catalog files are located.

14-22 15

17 18

19 20 21

Installing Custom Subassemblies

Once youve created a custom subassembly, you can install it on other AutoCAD Civil 3D users machines. NOTE Its simpler to create a subassembly package file to distribute to users than to install custom subassemblies manually. See Exporting Custom Subassemblies Using a Package File (page 178). To install a custom subassembly: 1 Copy the compiled AutoCAD Civil 3D subassembly .dll library to its destination directory. By default, libraries are located in <Civil 3D Install Directory>\Sample\Civil 3D API\C3DstockSubAssemblies.

Installing Custom Subassemblies | 177

2 Copy the tool catalog .atc files to its destination directory. The tool catalog files are normally located in the C:\Documents and Settings\All Users\Application Data\Autodesk\C3D 2009\enu\Tool Catalogs\Road Catalog directory. For information about creating these, see Creating a Tool Catalog ATC File (page 167). 3 Copy optional files such as the image file representing the subassemblies or the help file to their destination directory. Images are normally located in C:\Documents and Settings\All Users\Application Data\Autodesk\C3D 2009\enu\Tool Catalogs\Images, and help files are normally located in C:\Documents and Settings\All Users\Application Data\Autodesk\C3D 2009\enu\Tool Catalogs\Help, although these can be any directory as long as the .atc file has the correct relative path information. For information about creating help files, see Creating Subassembly Help Files (page 150) 4 Copy the catalog cover page .html file to its destination. Usually this is the same location as the .atc file, although it can be any directory as long as the .atc file has the correct relative path information. For information about creating cover pages, see Creating a Tool Catalog Cover Page (page 176). 5 Register the tool catalog using a registry (.reg) file. This .reg file must have the correct paths to the .atc file and the catalog image file from steps 2) and 3). For information about creating registry files, see Creating a Tool Catalog Registry File (page 176)

Exporting Custom Subassemblies Using a Package File

You can share custom subassemblies with others by copying the required files to a package file. Custom subassemblies that have been created using .NET or VBA can be exported and imported using a package file. A package file contains all the files necessary for the custom subassemblies to work. Once the package file is created, users can import the package file into AutoCAD Civil 3D, and then copy the custom subassemblies directly into a tool palette or catalog. For more information about importing subassembly package files, see Sharing Subassemblies in the AutoCAD Civil 3D Users Guide. Like other types of Civil 3D content, subassemblies can also be shared with others through the Autodesk Civil Engineering Community site. Go to http://civilcommunity.autodesk.com/ to access the Autodesk Civil Engineering web site, then click on Content Sharing. To create a package file, you must copy all of the files that make up the custom subassembly or subassemblies into a folder. Create a .zip file of that folder, and then change the file extension from .zip to .pkt. NOTE Subassemblies created from polylines cannot be included in a package file. Package files are intended for sharing custom subassemblies that have been created using .NET or VBA.

Naming the Package File

If you are sharing a single subassembly, it is recommended that you name the package file the same name as the subassembly. For example, if you plan to export a subassembly named OpenChannel, name the package file OpenChannel.pkt. If you plan to export multiple subassemblies in a single package file, give the folder a name that easily identifies the types of subassemblies that are contained in it. For example, DitchSubassemblies.pkt.

Required Subassembly Files

The following table describes the files that must be included in a package file to successfully export and import one or more subassemblies. File
.atc file(s)

Description
A valid .atc file that defines the shape and behavior of the subassembly or subassemblies is required. You can have one or more .atc files included in the

178 | Chapter 11 Creating Custom Subassemblies Using .NET

File

Description
package file. For example, you can have one .atc file that defines one or more subassemblies, or you can have multiple .atc files, each of which defines one or more subassemblies. If the package file contains multiple .atc files, each .atc file must have a unique name. All the paths referenced in .atc file must be relative paths, if they point to files in the same .pkt file.

.dll or .dvb file(s)

A .dll file is required for subassemblies that are defined using .NET. A .dvb file is required for subassemblies that are defined using VBA. A package file can contain both .dll and .dvb files. A Help file is not required in order for a subassembly to function properly. However, the Help file is needed for others to understand how to use the subassembly. Therefore, it is recommended that you always include a Help file with each subassembly. The Help file for each subassembly is specified in the .atc file, and can be any of the following formats: .dwf, .doc, .pdf, .txt, .chm, .hlp. For more information, see Creating Subassembly Help Files (page 150). An image file for each is displayed on the tool palette and is used to provide a conceptual graphical representation of the subassembly shape.

Help file(s)

Image file(s)

To create a package file 1 Copy all of the required subassembly files into a folder. Make sure that folder contains only the files required for the subassembly or subassemblies you plan to export. 2 Create a .zip file of the contents of that folder. 3 Change the file extension from .zip to .pkt. The package (.pkt) file is created and can be shared with other users.

Exporting Custom Subassemblies Using a Package File | 179

180

Corridors

Root Objects
This section explains how to get the base objects required for using the roadway API classes.

181

Object Hierarchy

Object Model for Root Corridor Objects

Accessing Corridor-Specific Base Objects

Applications that access corridors require special versions of the base objects representing the application and document. The AeccRoadwayApplication object is identical to the AeccApplication it is inherited from except that its AeccRoadwayApplication.ActiveDocument property returns an object of type AeccRoadwayDocument instead of AeccDocument. The AeccRoadwayDocument object contains collections of road related items, such as corridors, subassemblies, and style objects in addition to all of the methods and properties of AeccDocument. When using corridor root objects, be sure to reference the Autodesk Civil Engineering Corridor 6.0 Object Library (AeccXRoadway.tlb) and Autodesk Civil Engineering UI Corridor 6.0 Object Library (AeccXUIRoadway.tlb) libraries. This sample demonstrates how to retrieve the corridor root objects:

182 | Chapter 12 Corridors

Dim oApp As AcadApplication Set oApp = ThisDrawing.Application Dim sAppName As String sAppName = "AeccXUiRoadway.AeccRoadwayApplication" Dim oRoadwayApplication As AeccRoadwayApplication Set oRoadwayApplication = oApp.GetInterfaceObject(sAppName) ' Get a reference to the currently active document. Dim oRoadwayDocument As AeccRoadwayDocument Set oRoadwayDocument = oRoadwayApplication.ActiveDocument

Ambient Settings
Ambient settings allow you to get and set the unit and default property settings of roadway objects. Ambient settings for a corridor document are held in the AeccRoadwayDocument.Settings property, an object of type AeccRoadwaySettingsRoot. AeccRoadwaySettingsRoot inheirits all the properties of the AeccSettingsRoot class from which it is derived. The roadway-specific properies of AeccRoadwaySettingsRoot let you adjust the settings for corridors, assemblies, subassemblies, and quantity takeoffs:

Corridor Ambient Settings

The corridor ambient settings object allows you to set the default name templates and default styles for corridor-related objects. The name templates allow you to set how new corridors, corridor surfaces, profiles from feature lines, or alignments from feature lines are named. Each template can use elements from the following property fields: Valid property fields for AeccSettingsCorridor.NameTemplate
<[Corridor First Assembly(CP)]> <[Corridor First Baseline(CP)]> <[Corridor First Profile(CP)]> <[Next Counter(CP)]>

... for AeccSettingsCorridor.CorridorSurfaceNameTemplate

<[Corridor Name(CP)]>

Ambient Settings | 183

... for AeccSettingsCorridor.CorridorSurfaceNameTemplate

<[Next Corridor Surface Counter(CP)]>

...for AeccSettingsCorridor.ProfileFromFeatureLineNameTemplate
<[Next Counter(CP)]>

... for AeccSettingsCorridor.AlignmentFromFeatureLineNameTemplate

<[Corridor Baseline Name(CP)]> <[Corridor Feature Code(CP)]> <[Corridor Name(CP)]> <[Next Counter(CP)]> <[Profile Type]>

This sample sets the corridor name template:

' Get the ambient settings root object. Dim oRoadwaySettings As AeccRoadwaySettingsRoot Set oRoadwaySettings = oRoadwayDocument.Settings ' Set the template so that new corridors are named "Corridor" ' followed by a unique number followed by the name of the ' corridor's first assembly in parenthesis. oRoadwaySettings.CorridorSettings.NameTemplate = _ "Corridor <[Next Counter(CP)]>(<[Corridor First Assembly(CP)]>)"

Default styles are set through the AeccSettingsCorridor.StyleSettings property. The styles for corridor alignments, alignment labels, code sets, surfaces, feature lines, profiles, profile labels, and slope pattern are accessed through a series of string properties. This sample sets the style of alignments in a corridor to the first alignment style in the documents collection of styles:

184 | Chapter 12 Corridors

' Get a reference to the corridor settings object. Dim oSettingsCorridor As AeccSettingsCorridor Set oSettingsCorridor = oRoadwayDocument.Settings.CorridorSettings ' Get the name of the first alignment style in the collection. Dim sName As String sName = oRoadwayDocument.AlignmentStyles.Item(0).Name ' Assign the name to alignment style property. oSettingsCorridor.StyleSettings.AlignmentStyle.Value = sName

Assembly Ambient Settings

The assembly ambient settings object allows you to set the default name templates and default styles for assemblies. The name templates allow you to set how new assemblies, offset assemblies, and assembly groups are named. Each template can use elements from the following property fields: Valid property fields for AeccSettingsAssembly.NameTemplate
<[Next Counter(CP)]>

... for AeccSettingsAssembly.OffsetNameTemplate

<[Corridor Name(CP)]>

...for AeccSettingsAssembly.GroupNameTemplate
<[Next Counter(CP)]>

Default styles are set through the AeccSettingsCorridor.StyleSettings property. The styles for assemblies and code sets are accessed through string properties.

Subassembly Ambient Settings

The subassembly ambient settings object allows you to set the default name templates and default styles for subassembly objects. The name templates allow you to set how subassemblies created from entities and subassemblies create from macros are named. Each template can use elements from the following property fields: ... for AeccSettingsSubassembly.CreateFromEntitiesNameTemplate
<[Macro Short Name(CP)]> <[Next Counter(CP)]> <[Subassembly Local Name(CP)]>

Ambient Settings | 185

... for AeccSettingsSubassembly.CreateFromEntitiesNameTemplate

<[Subassembly Side]>

... for AeccSettingsSubassembly.CreateFromMacroNameTemplate

<[Macro Short Name(CP)]> <[Next Counter(CP)]> <[Subassembly Local Name(CP)]> <[Subassembly Side]>

The name of the default code style set is accessed through the AeccSettingsSubassembly.CodeSetStyle string property. Each of these settings properties also contain a standard AmbientSettings property of type AeccSettingsAmbient for setting the default units of measurement.

Corridors
Corridor Concepts
A corridor represents a path, such as a road, trail, railroad, or airport runway. The geometry of a corridor is defined by a horizontal alignment and a profile. Together, these form the baseline - the centerline of the 3D path of the corridor. Along the length of the baselines are a series of assemblies which define the cross-sectional shape of the alignment. Common points in each assembly are connected to form feature lines. Together the assemblies and feature lines form the 3D shape of a corridor. A corridor also has one or more surfaces which can be compared against an existing ground surface to determine the amount of cut or fill required.

Listing Corridors
The collection of all corridors in a document are held in the AeccRoadwayDocument.Corridors property. The following sample displays the name and the largest possible triangle side of every corridor in a document:

186 | Chapter 12 Corridors

Dim oCorridors As AeccCorridors Set oCorridors = oRoadwayDocument.Corridors Dim oCorridor As AeccCorridor For Each oCorridor In oCorridors Debug.Print "Corridor: " & oCorridor.Name Debug.Print oCorridor.MaximumTriangleSideLength Next

Creating Corridors
The corridors collection includes a AeccCorridors.Add method for creating new corridors. This method creates the corridor based on an existing alignment, profile, and assembly. NOTE The station distance between assemblies cannot be set through the API, and needs to be set through the property page dialog box before the AeccCorridors.Add method is called.
' Assuming oAlignment, oProfile, and oAssembly represent ' valid AeccAlignment, AeccProfile, and AeccAssembly objects. Dim oCorridors As AeccCorridors Set oCorridors = oRoadwayDocument.Corridors Dim oCorridor As AeccCorridor Set oCorridor = oCorridors.Add( _ "Corridor01", _ oAlignment.Name, _ oProfile.Name, _ oAssembly.Name)

Baselines
A baseline represents the centerline of the path of a corridor. It is based on an alignment (the horizontal component of the path) and a profile (the vertical component of the path). A corridor can contain more than one baseline if the corridor is modeling a complicated shape, such as an intersection. A baseline is made up of one or more baseline regions. Each region has its own assembly (its own cross section), so a corridor can have different shapes at different locations along its length.

Creating Corridors | 187

Object Hierarchy

Baselines Object Model

Listing Baselines in a Corridor

The collection of all baselines in a corridor are contained in the AeccCorridor.Baselines property. The following sample display information about the underlying alignment and profile for every baseline in a corridor:
Dim oBaseline As AeccBaseline For Each oBaseline In oCorridor.Baselines Debug.Print "Baseline information -" Debug.Print "Alignment : " & oBaseline.Alignment.Name Debug.Print "Profile : " & oBaseline.Profile.Name Debug.Print "Start station: " & oBaseline.StartStation Debug.Print "End station : " & oBaseline.EndStation Debug.Print Next

Adding a Baseline to a Corridor

A baseline can be added to an existing corridor through the AeccCorridor.AddBaseline method. The baseline is defined by an existing alignment, profile, and assembly and consists of a single region. NOTE The station distance between assemblies cannot be set through the API, and needs to be set through the property page dialog box before this method is called. The following sample adds a baseline using an existing alignment, profile, and assembly:
Set oBaseline = oCorridor.AddBaseline _ (oAlignment.Name, oProfile.Name, oAssembly.Name)

Listing Baseline Regions

The collection of all the regions of a baseline are contained in the AeccBaseline.BaselineRegions property.

188 | Chapter 12 Corridors

The Civil 3D API does not include methods for creating new baseline regions or manipulating existing regions. The following sample displays the start and end station for every baseline region in a baseline:
Dim oBaselineRegion As AeccBaselineRegion For Each oBaselineRegion In oBaseline.BaselineRegions Debug.Print "Baseline information -" Debug.Print "Start station: " & oBaselineRegion.StartStation Debug.Print "End station: " & oBaselineRegion.EndStation Debug.Print Next

Accessing and Modifying Baseline Stations

Assembly cross sections are placed at regular intervals along a baseline. The list of all stations where assemblies are located along a baseline can be retrieved using the AeccBaseline.GetSortedStations method while all stations along a baseline region can be retrieved using the AeccBaselineRegion.GetSortedStations method.
Dim v As Variant v = oBaselineRegion.GetSortedStations() Dim i As Integer Debug.Print "Assembly stations:" For i = 0 To UBound(v) Debug.Print v(i) Next i

New stations can be added to baselines and baseline regions using the AddStation method. Existing stations can be deleted using the DeleteStation method. DeleteStation includes an optional tolerance parameter, letting you specify a station within a range. You can list all of the stations added to a baseline region with the AeccBaselineRegion.GetAdditionalStation method. AeccBaselineRegion.ClearAdditionalStations removes all added stations within a baseline region and leaves only the original stations created at regular intervals.
' Add an assembly to the baseline at station 12+34.5 oBaseline.AddStation 1234.5, "Station description" ' Remove the station located within 0.1 units around 5+67.5 oBaseline.DeleteStation 567.5, 0.1

Listing Offset Baselines

Within a baseline region, it is possible to have secondary baselines that are offset from the main baseline. The collection of these offset baselines are contained in the AeccBaselineRegion.OffsetBaselines property. The collection contains two kinds of baselines derived from the IAeccBaseBaseline interface. One is the hardcoded offset baseline (an instances of the AeccHardcodedOffsetBaseline class) which is a constant distance from the main baseline for the entire length of the offset baseline. The other is offset baseline (an instance of the AeccOffsetBaseline class), which is a variable distance from the main baseline. NOTE The AutoCAD Civil 3D API does not include methods for creating new offset baselines or hardcoded offset baselines. This code examines each offset baseline within a baseline region:

Accessing and Modifying Baseline Stations | 189

Dim oBaseBaseline As IAeccBaseBaseline For Each oBaseBaseline In oBaselineRegion.OffsetBaselines Dim dMainStart As Double ' station on main baseline Dim dMainEnd As Double ' station on main baseline Dim vOE As Variant Select Case oBaseline.Type Case aeccCorridorOffsetBaseline Dim oOffsetBaseline As AeccOffsetBaseline Set oOffsetBaseline = oBaseBaseline ' Report that an offset baseline exists. dMainStart = oOffsetBaseline.StartStationOnMainBaseline dMainEnd = oOffsetBaseline.EndStationOnMainBaseline Debug.Print "Offset baseline, station " & dMainStart & _ " to " & dMainEnd ' Report the offset of the baseline at its start and end. vOE = oOffsetBaseline. _ GetOffsetElevationFromMainBaselineStation(dMainStart) Debug.Print " is offset by: " & _ vOE(0) & " horizontal and: " & vOE(1) & _ " vertical at start" vOE = oOffsetBaseline. _ GetOffsetElevationFromMainBaselineStation(dMainEnd) Debug.Print " is offset by: " & vOE(0) & _ " horizontal and: " & vOE(1) & " vertical at end" Case aeccCorridorHardcodedOffsetBaseline Dim oHardcodedOffsetBaseline As AeccHardcodedOffsetBaseline Set oHardcodedOffsetBaseline = oBaseBaseline ' Report that a hardcoded offset baseline exists. dMainStart = oHardcodedOffsetBaseline.StartStation dMainEnd = oHardcodedOffsetBaseline.EndStation Debug.Print "Hardcoded offset baseline, station " _ & dMainStart & " to " & dMainEnd vOE = oHardcodedOffsetBaseline. _ OffsetElevationFromMainBaseline Debug.Print " is offset by: " & vOE(0) & _ " horizontal and: " & vOE(1) & " vertical" End Select Next

Assemblies and Subassemblies

An assembly is a pattern for the cross section of a corridor at a particular station. An assembly consists of a connected set of subassemblies, each of which are linked to a centerpoint or to other subassemblies. A subassembly consists of a series of shapes, links, and points. When an assembly is used to define the cross-section of a corridor, a series of applied assemblies (an object of type AeccAppliedAssembly) is added to the corridor. Each applied assembly consists of a collection of applied subassemblies, which in turn consist of shapes, links, and points that have been positioned relative to a specific station along the corridor baseline (AeccCalcualtedShapes, AeccCalculatedLinks, and AeccCalculatedPoints respectively). An applied assembly also has direct access to all the calculated shapes, links, and points of its constituent applied subassemblies.

190 | Chapter 12 Corridors

NOTE The AutoCAD Civil 3D API does not include methods for creating or modifying assemblies.

Object Hierarchy

Assemblies and Subassemblies Object Model

Listing Applied Assemblies in a Baseline Region

The collection of all applied assemblies used in a baseline region are contained in the AeccBaselineRegion.AppliedAssemblies property. The following sample displays information about the construction of an assembly for every assembly in a baseline region:

Object Hierarchy | 191

Dim oAppliedAssembly As AeccAppliedAssembly For Each oAppliedAssembly In oBaselineRegion.AppliedAssemblies Debug.Print "Applied Assembly" Dim lCount As Long lCount = oAppliedAssembly.GetShapes().Count Debug.Print " Num Shapes: " & lCount Debug.Print lCount = oAppliedAssembly.GetLinks().Count Debug.Print " Num Links: " & lCount lCount = oAppliedAssembly.GetPoints().Count Debug.Print " Num Points: " & lCount Next

An AeccAppliedAssembly object does not contain its baseline station position. Instead, each calculated point contains a method for determining its position with a baseline station, offset, and elevation called AeccCalculatedPoint.GetStationOffsetElevationToBaseline. Each calculated shape contains a collection of all links that form the shape, and each calculated link contains a collection of all points that define the link. Finally, each shape, link, and point contain an array of all corridor codes that apply to that element. This sample retrieves all calculated point in an applied assembly and prints their locations:
Dim oPoint As AeccCalculatedPoint For Each oPoint In oAppliedAssembly.GetPoints() Dim vPos As Variant vPos = oPoint.GetStationOffsetElevationToBaseline() Debug.Print "Position: Station = " & vPos(0) & _ " Offset = " & vPos(1) & " Elevation = " & vPos(2) Next

Getting Applied Subassembly Information

An applied subassembly consists of a series of calculated shapes, links, and points, represented by objects of type AeccCalculatedShape, AeccCalculatedLink, and AeccCalculatedPoint respectivly.
Dim S, O, E As Double With oAppliedSubassembly S = .OriginStationOffsetElevationToBaseline(0) O = .OriginStationOffsetElevationToBaseline(1) E = .OriginStationOffsetElevationToBaseline(2) End With Debug.Print "Station to baseline : " & S Debug.Print "Offset to baseline : " & O Debug.Print "Elevation to baseline : " & E

Applied subassemblies also contain a reference to the archetype subassembly (of type AeccSubassembly) in the subassembly database.
' Get information about the subassembly template. Dim oSubassembly As AeccSubassembly Set oSubassembly = oAppliedSubassembly.SubassemblyDbEntity Debug.Print "Subassembly name: " & oSubassembly.Name

192 | Chapter 12 Corridors

Feature Lines
Feature lines are formed by connecting related points in each assembly along the length of a corridor baseline. These lines represent some aspect of the roadway, such as a sidewalk edge or one side of a corridor surface. Points become related by sharing a common code, a string property usually describing the corridor feature. Each baseline has two sets of feature lines, one for lines that are positioned along the main baseline and one for lines that are positioned along any of the offset baselines. NOTE You can create feature lines from polylines using the IAeccLandFeatureLine:: AddFromPolyline() method.

Object Hierarchy

Feature Line Object Model

Listing Feature Lines Along a Baseline

The set of all feature lines along a main baseline are held in the AeccBaseline.MainBaselineFeatureLines property, an object of type AeccBaselineFeatureLines. This object contains information about all the feature lines, such as a list of all codes used. Its AeccBaselineFeatureLines.FeatureLinesCol property is a collection of collections of feature lines. Each feature line (an object of type AeccFeatureLine) contains the code string used to create the feature line and a collection of all feature line points. This sample lists all the feature line collections and feature lines along the main baseline. It also lists the code and every point location for each feature line.

Feature Lines | 193

Dim oBaselineFeatureLines As AeccBaselineFeatureLines Set oBaselineFeatureLines = oBaseline.MainBaselineFeatureLines Dim oFeatureLinesCol As AeccFeatureLinesCol Set oFeatureLinesCol = oBaselineFeatureLines.FeatureLinesCol Debug.Print "# line collections:" & oFeatureLinesCol.Count Dim oFeatureLines As AeccFeatureLines For Each oFeatureLines In oFeatureLinesCol Debug.Print "Feature Line collection" Debug.Print "# lines in collection: " & oFeatureLines.Count Dim oFeatureLine As AeccFeatureLine For Each oFeatureLine In oFeatureLines Debug.Print Debug.Print "Feature Line code: " & oFeatureLine.CodeName ' Print out all point locations of the ' feature line. Dim oFeatureLinePoint As AeccFeatureLinePoint For Each oFeatureLinePoint In oFeatureLine.FeatureLinePoints Dim X As Double Dim Y As Double Dim Z As Double X = oFeatureLinePoint.XYZ(0) Y = oFeatureLinePoint.XYZ(1) Z = oFeatureLinePoint.XYZ(2) Debug.Print "Point: " & X & ", " & Y & ", " & Z Next ' Points in a feature line Next ' Feature lines Next ' Collections of feature lines

Listing Feature Lines Along Offset Baselines

As there can be many offset baselines in a single main baseline, the list of all feature lines along all offset baselines contains an extra layer. The AeccBaseline.OffsetBaselineFeatureLinesCol property contains a collection of AeccBaselineFeatureLines objects. These AeccBaselineFeatureLines objects not only contain the feature lines just as for the main baseline, but also contain properties identifying which offset baseline each group of feature lines belong to. This sample shows how to modify the previous sample for feature lines along offset baselines:

194 | Chapter 12 Corridors

Dim oBFeatureLinesCol As AeccBaselineFeatureLinesCol Set oBFeatureLinesCol = oBaseline.OffsetBaselineFeatureLinesCol Dim oBaselineFeatureLines As AeccBaselineFeatureLines ' Loop through the groups of collections, one group for each ' offset baseline. For Each oBaselineFeatureLines In oBFeatureLinesCol Dim oFeatureLinesCol As AeccFeatureLinesCol Set oFeatureLinesCol = oBaselineFeatureLines.FeatureLinesCol Debug.Print "# line collections:" & oFeatureLinesCol.Count ' [...] ' This section is the same as the previous topic. Next ' Groups of collections of feature lines

Each offset baseline and hardcoded offset baseline also has direct access to the feature lines related to itself. The AeccBaselineFeatureLines collection is accessed through the RelatedOffsetBaselineFeatureLines property in both types of offset baselines.

Corridor Surfaces
Corridor surfaces can represent the base upon which the corridor is constructed, the top of the finished roadway, or other aspects of the corridor. Such surfaces are represented by the AeccSurface class and by the unrelated AeccCorridorSurface class. AeccCorridorSurface objects contain corridor-specific information about the surfaces, such as which feature line, point, and link codes were used to create it.

Object Hierarchy

Corridor Surfaces Object Model

Corridor Surfaces | 195

Listing Corridor Surfaces

The collection of all corridor surfaces for each corridor is held in the the AeccCorridor.CorridorSurfaces property. Each corridor surface contains the boundary of the surface and a list of all point, link, and feature line codes used in the construction of the surface. Corridor surfaces also contain read-only references to the surface style and section style used in drawing the surface. NOTE The AutoCAD Civil 3D API does not include methods for creating new corridor surfaces or modifying existing corridor surfaces. This sample lists all the corridor surfaces within a corridor and specifies which point codes were used:
Dim oCorridorSurface As AeccCorridorSurface For Each oCorridorSurface In oCorridor.CorridorSurfaces Debug.Print "Surface name: "; oCorridorSurface.Name ' Get the point codes that were used to construct ' this surface. Dim sCodes() As String Dim sCodeList As String Dim i as Integer sCodes = oCorridorSurface.PointCodes For i = 0 To UBound(sCodes) sCodeList = sCodeList & " " & sCodes(i) Next i Debug.Print "Point codes: " & sCodeList Next

Listing Surface Boundaries

Two different objects are used to define the limits of a corridor surface: boundaries and masks. A boundary is a polygon representing the outer edge of a surface or the inside edge of a hole in a surface. A mask is a polygon representing the part of the surface that can be displayed. The collection of all the boundaries of a surface are stored in the AeccCorridorSurface.Boundaries property and the collection of all masks are stored in the AeccCorridorSurface.Masks property. Boundaries (of type AeccCorridorSurfaceBoundary) and masks (of type AeccCorridorSurfaceMask) are both derived from the same base interface (IAeccCorridorSurfaceBaseMask) and both have the similar methods and properties. The array of points making up the border polygon is retrieved by calling the GetPolygonPoints method. If the border was originally defined by selecting segments of feature lines, the collection of all such feature line components are contained in the FeatureLineComponents property. NOTE The AutoCAD Civil 3D API does not include methods for creating or modifying corridor boundaries or masks. This sample loops through all the boundaries of a corridor surface and displays information about each:

196 | Chapter 12 Corridors

Dim oCSBoundary As AeccCorridorSurfaceBoundary For Each oCSBoundary In oCorridorSurface.Boundaries ' Get the type of boundary. Dim sBoundaryTitle As String If (oCSBoundary.Type = aeccCorridorSurfaceInsideBoundary) Then sBoundaryTitle = " Inner Boundary: " Else sBoundaryTitle = " Outer Boundary: " End If Debug.Print sBoundaryTitle & oCSBoundary.Name ' Get the points of the boundary polygon. Dim vPoints As Variant vPoints = oCSBoundary.GetPolygonPoints() Debug.Print " " & UBound(vPoints) & " points" ' Print the location of the first point. Usually corridors ' have a large number of boundary points, so we will not ' bother printing all of them. X = vPoints(1)(0) Y = vPoints(1)(1) Z = vPoints(1)(2) Debug.Print "Point 1: "; X; ", "; Y; ", "; Z ' Display information about each feature ' line component in this surface boundary. Debug.Print Debug.Print "Feature line components" Debug.Print " Count: "; Debug.Print oCSBoundary.FeatureLineComponents.Count Dim oFeatureLineComponent As AeccFeatureLineComponent For Each oFLineComponent In oCSBoundary.FeatureLineComponents Debug.Print "Code:" & oFLineComponent.FeatureLine.CodeName Debug.Print "Start station:" & oFLineComponent.StartStation Debug.Print "End station:" & oFLineComponent.EndStation Debug.Print: Debug.Print Next ' Feature line components Next ' Corridor surface boundaries

Computing Cut and Fill

One important use of corridor surfaces is to compare them against an existing ground surface to determine the amounts of cut and fill required to shape the terrain to match the proposed corridor. While AeccCorridorSurface objects cannot be used with AeccSurface objects directly to compute such statistics, each AeccCorridorSurface object also has a companion AeccSurface object of the same name. This sample code demonstrates the creation of a volume surface from the difference between the existing ground and the datum surface of a corridor to determine cut, fill, and volume statistics:

Computing Cut and Fill | 197

' Get the collection of all surfaces in the drawing. Dim oSurfaces As AeccSurfaces Set oSurfaces = oRoadwayDocument.Surfaces ' Assign the setup information for the volume ' surface to be created. Dim oTinVolumeCreationData As New AeccTinVolumeCreationData oTinVolumeCreationData.Name = VOLUME_SURFACE_NAME Dim sLayerName as String sLayerName = oRoadwayDocument.Layers.Item(0).Name oTinVolumeCreationData.BaseLayer = sLayerName oTinVolumeCreationData.Layer = sLayerName Set oTinVolumeCreationData.BaseSurface = oSurfaces.Item("EG") ' Get the surface with the same name as the corridor surface. Set oTinVolumeCreationData.ComparisonSurface = oSurfaces.Item(oCorridorSurface.Name) oTinVolumeCreationData.Style = oSurfaces.Item("EG").StyleName oTinVolumeCreationData.Description = "Volume surface of corridor" ' Create a volume surface that represents the ' difference between the two surfaces. Dim oTinVolumeSurface As AeccTinVolumeSurface Set oTinVolumeSurface = oSurfaces.AddTinVolumeSurface(oTinVolumeCreationData) ' Get information about the volume surface and ' display it in a messagebox. Dim dNetVol As Double Dim dCutVol As Double Dim dFillVol As Double dNetVol = oTinVolumeSurface.Statistics.NetVolume dCutVol = oTinVolumeSurface.Statistics.CutVolume dFillVol = oTinVolumeSurface.Statistics.FillVolume MsgBox "Net Volume = " & dNetVol & " cu.m" & _ vbNewLine & "Cut = " & dCutVol & " cu.m" & _ vbNewLine & "Fill = " & dFillVol & " cu.m", _ vbOKOnly, _ "Differences between """ & _ oTinVolumeCreationData.BaseSurface.Name & _ """ and """ & _ oTinVolumeCreationData.ComparisonSurface.Name & _ """"

Styles
These style objects control the visual appearance of applied assemblies.

Assembly Style
The collection of all assembly style objects are found in the AeccRoadwayDocument.AssemblyStyles property. The assembly style object contains properties for adjusting the marker types for the assembly attachment points, each of the standard AeccMarkerType property. While you can create new styles and edit existing styles, you cannot assign a style to an existing assembly using the AutoCAD Civil 3D API.

198 | Chapter 12 Corridors

' Create a new assembly style and change it so that the ' place where the assembly attaches to the main baseline ' is marked with a red X. Dim oAssemblyStyle As AeccAssemblyStyle Set oAssemblyStyle = oRoadwayDocument.AssemblyStyles.Add("Style1") With oAssemblyStyle.MarkerStyleAtMainBaseline .CustomMarkerStyle = aeccCustomMarkerX .MarkerDisplayStylePlan.Color = 10 ' red .MarkerDisplayStylePlan.Visible = True End With

Link Style
The collection of all link style objects are found in the AeccRoadwayDocument.LinkStyles property. This style object contains properties for adjusting the visual display of assembly and subassembly links. NOTE Link style objects are not used directly with link objects, but are instead used with roadway style sets.
' Create a new link style and color it green. Dim oLinkStyle As AeccRoadwayLinkStyle Set oLinkStyle = oRoadwayDocument.LinkStyles.Add("Style2") With oLinkStyle .LinkDisplayStylePlan.color = 80 .LinkDisplayStylePlan.Visible = True End With

Shape Style
The collection of all shape style objects are found in the AeccRoadwayDocument.ShapeStyles property. This style object contains properties for adjusting the visual display of assembly and subassembly shapes, including the outline and the inside area. NOTE Shape style objects are not used directly with shape objects, but are instead used with roadway style sets.
' Create a new shape style and change it so that it has ' an orange border and a yellow hatch fill. Dim oShapeStyle As AeccRoadwayShapeStyle Set oShapeStyle = oRoadwayDocument.ShapeStyles.Add("Style3") With oShapeStyle .AreaFillDisplayStylePlan.color = 50 ' yellow .AreaFillDisplayStylePlan.Visible = True .AreaFillHatchDisplayStylePlan.HatchType = aeccHatchPreDefined .AreaFillHatchDisplayStylePlan.Pattern = "LINE" .BorderDisplayStylePlan.color = 30 ' orange .BorderDisplayStylePlan.Visible = True End With

Roadway Style Sets

The visual display of applied assemblies is defined by roadway style sets, which are a set of shape styles and link styles assigned to shapes and links that use specified code strings. The collection of all style sets are found in the AeccRoadwayDocument.StyleSets property. A style set is itself a collection of

Link Style | 199

AeccRoadwayStyleSetItem objects. Each style set item has a AeccRoadwayStyleSetItem.CodeStyle property

that can reference either an existing shape style object or link shape object. New style set items are added to a style set though the AeccRoadwayStyleSet.Add method which takes parameters describing the kind of style object, the code string, and the style object itself. The particular style set in use is selected through the AeccRoadwayStyleSet.InitAsCurrent method.
' Create a new style set using our previously created styles. Dim oStyleSet As AeccRoadwayStyleSet Set oStyleSet = oRoadwayDocument.StyleSets.Add("Style Set 01") Call oStyleSet.Add( _ aeccLinkType, _ "TOP", _ g_oRoadwayDocument.LinkStyles.Item("Style2")) Call oStyleSet.Add( _ aeccShapeType, _ "BASE", _ oRoadwayDocument.ShapeStyles.Item("Style3")) ' Assign our new style set as the style set in current use. oStyleSet.InitAsCurrent

Sample Program
CorridorSample.dvb
<installation-directory>\Sample\Civil 3D API\Vba\Corridor\CorridorSample.dvb The CreateCorridorExample subroutine demonstrates the creation of a simple corridor using the AeccCorridors.Add method. Before calling this subroutine, be sure the current document contains at least one assembly. A suitable drawing is the file Corridor-2b.dwg located in the <installation-directory>\Help\Civil 3D Tutorials\Drawings directory. The GetCorridorInformationExample subroutine extracts information of all existing corridors, baselines, feature lines, surfaces, assemblies, and subassemblies within the current document and displays the data in an instance of Word. A suitable drawing is the file Corridor-4b.dwg located in the <installation-directory>\Help\Civil 3D Tutorials\Drawings directory. NOTE Microsoft Word must be running before starting this program.

200 | Chapter 12 Corridors

Object Hierarchy

AutoCAD Civil 3D
These images contain the hierarchy of all major objects. This is useful for determining which class instances are required to create an object of a particular type, or which objects can be accessed from an existing instance.

201

202 | Appendix A Object Hierarchy

AutoCAD Civil 3D | 203

204 | Appendix A Object Hierarchy

Legend
Graphic Meaning
An object with a classname of AeccObject.

AutoCAD Civil 3D | 205

Graphic

Meaning
An object with a classname of AeccCollection. This object is a list of other objects which can be enumerated. It also usually has a Count property and Add, Item, and Remove methods.

You can obtain object B from a property or method of object A.

From object X you can obtain a collection Y, which is a subset of a larger collection.

206 | Appendix A Object Hierarchy

Creating Custom Subassemblies with VBA

You can develop Visual Basic for Applications (VBA) scripts to define custom subassemblies that provide specific behavior. The actions that occur when a subassembly is used in an assembly, and when subassemblies are processed during corridor creation, are specified through VBA scripts. The AutoCAD Civil 3D COM API includes objects, methods, and properties specifically designed to provide an interface to assemblies and corridor models for subassembly VBA scripts.

Designing Custom Subassemblies

This section presents a variety of subjects to consider while designing custom subassemblies for corridor modeling.

Naming Custom Subassemblies

Devise a scheme for naming custom subassemblies that adheres to the subassembly naming conventions. Subassembly Naming Conventions

Do not use spaces or other special characters. Use a combination of upper and lower case letters, with uppercase letters reserved for the first character of each word. Group subassemblies by making the type of component the first word. For example, in the AutoCAD Civil 3D Corridor Modeling catalogs, all lane subassembly names begin with Lane..; all shoulders with Shoulder.., and so on.

Attachment and Insertion Methodology

There are some general rules to follow when considering attachment and insertion behavior for subassembly components.

207

Medians. Medians tend to be inserted in both the left and right directions simultaneously about a centerline (which is not necessarily the corridor baseline alignment). Furthermore, the attachment point may not be a point on the median surface links. For example, the attachment point for a depressed median subassembly may be above the median ditch at the elevation of the inside edges-of-traveled-way. Components Joining Two Roadways. When modeling separated roadways in a single corridor model, it is often necessary to insert intersection fill slopes, or to connect from one edge-of-roadway to another. Typically, you assemble the components for as much of the first roadway as possible, switch baselines and assemble the components for the second roadway, then use special subassemblies to connect between the two roadways. In this case, you need two attachment points. Accomplish this by having a subassembly that uses a normal attachment point on one side, and attaches to a previously defined marked point on the other. Rehabilitation and Overlay. Typically, subassemblies that are used to strip pavement, level, and overlay existing roads are placed based on calculations involving the shape of the existing roadway section, rather than using a design centerline alignment and profile. For example, a pavement overlay subassembly may require a minimum vertical distance from the existing pavement for a given design slope. A lane-widening subassembly may need to attach to the existing edge-of-traveled-way and match the existing lane slope.

User Defined vs. Hard-Coded Parameters

Behavior for custom subassemblies can be hard-coded into the subassembly design or it can be supplied by user input. Determine which of the geometric dimensions, behavior, and methodology will be hard-coded into the subassembly, and which will be controlled by user-defined input parameters. One approach is to specify that a majority of items can be controlled by user input. This can add time and complexity to using the subassembly. Another approach is to make it so that it cannot be adapted to different situations. Generally, widths, depths, and slopes should be variable, not fixed. A compromise is to include a larger number of inputs, but provide default values that cover the most common design situations. A good example of where to use hard-coded dimensions is with structural components, such as barriers and curb-and-gutter shapes. If there are five commonly-used variations of the same basic shape with different dimensions, it may be better to provide five separate subassemblies with hard-coded dimensions rather than making the user define the dimensions on a single subassembly. For example, users may be comfortable selecting from separate subassemblies for curb types A-E, which have predefined, hard-coded dimensions. You can always provide a generic subassembly with variable dimensions for scenarios where the common ones do not apply.

Input Parameter Types

Input parameters governing widths, offsets, % slopes, ratio slopes, point codes, link codes, and shape codes are commonly used in the AutoCAD Civil 3D Corridor Modeling subassemblies.

208 | Appendix B Creating Custom Subassemblies with VBA

The table below describes these various types of input parameters: Input Parameter
Widths

Description
The cross-sectional horizontal distance between two points on the roadway assembly. Widths are generally given as positive numeric values, and extend in the direction of insertion (left or right) of the subassembly. Many components that require a width are likely candidates for using an alignment as an optional runtime logical assignment. The width is then calculated at each station to tie to the alignment, if one is given. The cross-sectional horizontal distance from the corridor baseline to a point on the roadway assembly. The difference between an Offset and a Width is that Widths are measured from some point on the assembly, while Offsets are measured from the corridor baseline. Positive and negative values indicate positions right or left of the baseline. Components requiring an offset are also likely to use an alignment to allow a calculated offset. Lanes, shoulders, and other components usually have a slope defined as ratio of rise-to-run. There are two common conventions for how these are expressed. They can either be a unitless ratio (-0.05), or a percent value (-5). Both of these examples define a 5% slope downwards. The same convention should be used for all subassemblies in a catalog. In some cases, you may want the component to have a variable slope, tying to a profile. The profile name can be given as a runtime logical assignment. Cut slopes, fill slopes, ditch side slopes, median slopes, and many other roadway components are commonly expressed as a run-to-rise ratio, such as 4 : 1. These may be signed or unsigned values, depending on circumstances. For example, a fill slope is always downward, so it may not be necessary to force the user to enter a value like -4. In most cases, point, link, and shape codes should be hardcoded to ensure that consistent codes are assigned across the entire assembly. The primary exception is with generic link subassemblies that allow users to add links to the assembly as needed. These might be used for paved or unpaved finish grade, structural components, pavement subsurfaces, and many other unanticipated components. In these scenarios, the end-user assigns point, link, and shape codes that coordinate with the overall assembly.

Offsets

% Slopes

Ratio Slopes

Point, Link, and Shape Codes

Superelevation Behavior and Subassemblies

Varying road conditions, such as superelevation, have an impact on designing subassemblies.

Superelevation Behavior and Subassemblies | 209

Make sure you consider differences in component behavior, such as when the roadway is in a normal crown condition or is in superelevation. Gutter and median subassemblies may also be designed to exhibit different behaviors in normal and superelevated sections. The Superelevation Properties of the corridor alignment define the lane and shoulder slopes at all stations on the roadway. However, the way these slopes are applied depends on a combination of how the subassemblies are manipulated in layout mode and the internal logic of the subassemblies. Different agencies have varying methodologies. The VBA scripting behind the subassemblies makes it possible to adapt to just about any situation. Most importantly you need to determine where the superelevation pivot point is located, and how that point relates to the design profile grade line (PGL). Pivot point/PGL combinations that are commonly encountered include:

Broken Back Subbase. Some agencies put a break point in the subbase layer on the high side of superelevation. The subbase parallels the finish grade up to a certain point, the extends at a downward slope until it intersects the shoulder or clear zone link. Shoulder Breakover. Usually a maximum slope difference, or breakover, must be maintained between the travel lane and the shoulder, or between the paved and unpaved shoulder links. Curbs-and-Gutters. Some agencies require that gutters on the high side of a superelevated road tip downward toward the low side, while others leave the gutters at their normal slope.

Creating Subassembly Help Files

210 | Appendix B Creating Custom Subassemblies with VBA

When creating custom subassemblies, you should also create a custom Help file to accompany the subassembly. You can use just about any type of document file (.dwf, .doc, .pdf, .txt, .chm, .hlp) to create the subassembly Help file. For more information, see Creating Customized Help in the AutoCAD Developer Help. The Help file content and style should be similar to that in the AutoCAD Civil 3D Corridor Modeling subassembly Help. The table below describes the sections that should be included, as a minimum, in subassembly Help files. This information is required so that users understand the subassembly behavior and intended use. Section
Title

Description
The name of the selected subassembly should appear prominently as the top heading of the subassembly Help file. A brief description of the subassembly that includes the type of component the subassembly creates (for example, a lane, median, or shoulder), special features, and situations it is designed to cover. The subassembly diagram should be a schematic showing the geometry of the component that is created by the subassembly. Diagrams should label as many of the input parameters as feasible, especially those pertaining to dimensions and slopes. You may need to include multiple subassembly diagrams for different behavior and/or conditions in order to include all of the possible input items. The subassembly diagram should also show the subassembly reference point, which is the point on the subassembly where it is attached when building an assembly layout. It is useful to adopt diagramming conventions that help the user understand the operations. For example, the subassemblies included in the AutoCAD Civil 3D Corridor Modeling catalog use bold blue lines to represent links that are added to the assembly by the subassembly. This helps to show adjacent roadway components that the subassembly might attach to in a lighter line with a background color. Ideally, dimension lines and labels should also be a different color. Describes where the attachment point is located relative to the subassembly links. Describes each of the user-definable input parameters that can be specified when using the subassembly. These should precisely match the parameter names and order seen by the user when using the assembly layout tool, and should describe the effect of each parameter. These are best presented in a table that includes a description of each parameter, the type of input expected, and default values for metric or imperial unit projects. For input parameters for slope values, note that there are two common ways of specifying slopes: as a percent value like -2%, or as a run-to-rise ratio like 4 : 1. Any slope parameter should clearly specify which type is expected. In the subassemblies included in the AutoCAD Civil 3D Corridor Modeling catalog, the convention is to precede the word Slope with the % character in the parameter name if a percent slope is expected. Otherwise a ratio value is required. Note the practice of using positive numeric values for both cut and fill slopes. If a slope parameter is known to be used only in a fill condition, it should not be necessary for the user to have to specify a negative

Descriptions

Subassembly Diagram

Attachment

Input Parameters

Creating Subassembly Help Files | 211

Section

Description
slope value. However, in a more generic situation, for example with the LinkWidthAndSlope subassembly, a signed value may be necessary.

Runtime Logical Assignments

Input parameters are defined when building an assembly in layout mode. Runtime logical assignments are substitutions that can be made for input parameters when applying the assembly to a corridor model. Runtime logical assignments can be alignment names, profile names, or surface names. A typical scenario is a travel lane where the width is a numeric input parameter, which can use an alignment as a runtime logical assignment to replace the numeric width. The given numeric width is used when displaying the lane in layout mode. If an alignment is given, the width is calculated at each station during corridor modeling to tie to the offset of the alignment. In the subassembly Help file, a logical assignment should reference the name of the input parameter it replaces. Describes the behavior of the subassembly in detail. If necessary, this section should include diagrams showing different behaviors in different conditions. This section should provide both the subassembly programmer and the end user with all of the information needed to understand exactly what the subassembly does in all circumstances. Subheadings are recommended if the Behavior section covers several different topics. During the process of creating an assembly from subassemblies, also known as the assembly layout mode, specific information such as alignment offsets, superelevation slopes, profile elevations, and surface data, are not known. The Layout Mode Operation section of the subassembly Help file describes how the subassembly is displayed in the assembly layout mode. Layout mode refers to an assembly that has not yet been applied to a corridor. Some subassemblies behave differently in different situations. For example, a Daylight type of subassembly may create different geometric shapes depending on whether it is in a cut or fill situation. Shoulders may behave differently for normal crown and superelevated roadways. In layout mode, the subassembly designer must specify some arbitrary choices as to how the subassembly is displayed. It should appear as much like the final result in the corridor model as possible. Lanes and shoulders, for example, should be shown at typical normal crown slopes. Where there is alternate geometry, such as for the cut and fill daylight cases, both cases should be shown. Also, links that extend to a surface should be shown with arrowheads indicating the direction of extension. A diagram illustrating layout mode behavior and visual representation is useful if layout mode behavior and/or visual representation of the subassembly differs significantly between layout mode when the assembly and its associated subassemblies are applied to a corridor. Describes the items that are hard-coded into the subassembly, including dimensions, point codes, link codes, and shape codes. Common practice is to reference the point, link, and shape codes to labels on the coding diagram.

Behavior

Layout Mode Operation

Layout Mode Diagram

Point, Link, and Shape Codes

212 | Appendix B Creating Custom Subassemblies with VBA

Section
Coding Diagram

Description
The coding diagram has a twofold purpose. First, it labels the point, link, and shape numbers referred to in the previous section. Secondly, it provides the subassembly programmer with a numbering scheme for points, links, and shapes. These should correspond to the array indices used in the VBA script for points, links, and shapes. This is to make it easier to later modify or add to the subassembly.

COM Objects for Subassemblies

The AeccRoadwayState object is the primary interface into the Create Assembly and Create Corridor processes. The object is declared and initialized with the statements:
Dim oRwyState As AeccRoadwayState Set oRwyState = GetRoadwayState()

It provides numerous properties and methods. The properties include the current station, current alignment and profile, current offset and elevation, layer, color, line style, and line weight. Some of these, like the CurrentAlignment property, provide a substantial set of their own methods and properties. They also include several parameter buckets used for collecting parameters of types boolean, long, double, string, alignment, profile, surface, and point. Each parameter is defined by a literal name and a value. The AeccRoadwayState methods provide useful calculation functions for corridor design. These include the following:
IntersectAlignment Finds the intersection of a cross-sectional line with an offset alignment. Finds the intersection of a cross-sectional line with a link on the assembly. Finds the intersection of a cross-sectional line with a surface. Determines if a subassembly point is above or below a surface. Constructs a set of cross section links from a surface. Converts between station, offset, elevation coordinates and X,Y,Z coordinates.

IntersectLink

IntersectSurface

IsAboveSurface

SampleSection SoeToXyz XyzToSoe

VBA Structure for Subassemblies

This topic describes the structure of the VBA script for subassemblies.

COM Objects for Subassemblies | 213

Each subassembly should have a separate module in the VBA library where the module name matches the subassembly name. For example, the subassembly DaylightStandard is executed by the subroutines in a module that is also called DaylightStandard. There are several standard subroutines that must be implemented for each subassembly within its module. These subroutines are described below for a hypothetical subassembly called Lane1. Subroutine
Lane1_GetLogicalNames()

Description
Defines the list of runtime logical assignments that can be made in modeling mode. This subroutine is called by the system to build the logical assignments list in the user interface for corridor modeling. Defines the list of input parameters that must be defined for the subassembly. This subroutine is called by the system to build the input parameters list in the user interface for selecting an assembly, changing subassembly properties, and in the user interface for corridor modeling. Defines the list of output parameters that are produced by the subassembly. This subroutine is called by the system to build the output parameters list in the user interface for corridor modeling. Executes the subassembly in both layout and modeling mode, based on the input parameters and runtime logical assignments provided by the user. This is the subroutine where the user defined input parameters and logical assignments are read, and the geometry of the roadway component is calculated and displayed.

Lane1_GetInputParameters()

Lane1_getOutputParameters()

Lane1

Additional utility subroutines needed for subassembly execution can be added as needed. These four subroutines must be present for each subassembly, even if there are no logical names, input parameters, or output parameters.

Defining Point, Link, and Shape Codes

The subassembly scripts provided with AutoCAD Civil 3D define point, link, and shape codes from an external file. Because the same subassemblies are used in many different countries, having an external file provides an easy way to adapt the codes to different languages without having to modify the VBA script. This method does result in some additional processing overhead since the codes are read from the external file (C3DStockSubassemblyScripts.codes) multiple times in the course of building a corridor model.

214 | Appendix B Creating Custom Subassemblies with VBA

NOTE If you are creating a set of custom subassemblies designed for use by a single organization, or in a single language, an external file for point, link, and shape codes is not necessary. However, it may still be considered a good practice to have your codes defined in a single place. This makes it easier to monitor and change codes as subassemblies evolve. For single-language usage, the recommended method is to define the standard point, link, and shape codes as global constants in a separate module, as in the examples below:
Public Const g_spcETW = "ETW" Public Const g_slcPave1 = "Pave1" Public Const g_sscSubbase = "Subbase"

Then the individual subassembly modules can use assignments like the ones below:
oPointArray(5).RoadwayCodes.Add (g_spcETW) oLinkArray(2).RoadwayCodes.Add(g_slcPave1) oShapeArray(1).RoadwayCodes.Add(g_slcSubbase)

Sample Subassembly VBA Script

This sample VBA script defines the BasicLaneTransition subassembly provided in the AutoCAD Civil 3D Corridor Modeling Getting Started Subassemblies Catalog. Refer to the table following the code sample for descriptions of the various lines of code. Before reviewing the VBA code you should familiarize yourself with the subassembly, how it behaves in the cut and fill conditions, the point and link codes to be assigned, and the point and link numbers specified in the subassembly coding diagram. Refer to the BasicLaneTransition subassembly Help file for this information.

Sample Subassembly VBA Script | 215

1. Option Explicit 2. 3. ' ************************************************************************* 4. ' Name: BasicLaneTransition 5. ' 6. Private Enum TransitionTypes 7. kHoldOffsetAndElevation = 0 8. kHoldElevationChangeOffset = 1 9. kHoldGradeChangeOffset = 2 10. kHoldOffsetChangeElevation = 3 11. kChangeOffsetAndElevation = 4 12. End Enum 13. 14. ' ---------------------------------------------------------------------15. ' Default values for input parameters 16. Private Const c_iSideDefault = g_iRight 17. Private Const c_dLaneWidthDefault = 12# 18. Private Const c_dLaneDepthDefault = 0.667 19. Private Const c_dLaneSlopeDefault = -2# '0.25 inch per foot 20. Private Const c_iHoldOriginalPositionDefault = TransitionTypes.kHoldOffsetAndElevation 21. 22. ' ---------------------------------------------------------------------23. ' Returns logical names used by this script 24. Public Sub BasicLaneTransition_GetLogicalNames() 25. 26. On Error GoTo ErrorHandler 27. 28. ' Get the roadway stateobject 29. Dim oRwyState As AeccRoadwayState 30. Set oRwyState = GetRoadwayState() 31. 32. ' Retrieve parameter buckets from the roadway state 33. Dim oParamsLong As AeccParamsLong 34. Set oParamsLong = oRwyState.ParamsLong 35. 36. ' Add the logical names we use in this script 37. oParamsLong.Add "TargetHA", aeccParamLogicalNameTypeAlignment 38. oParamsLong.Add "TargetVA", aeccParamLogicalNameTypeProfile 39. 40. Exit Sub 41. 42. ErrorHandler: 43. RecordError Err.Number, Err.Description, Err.Source 44. End Sub 45. 46. 47. ' ----------------------------------------------------------------------48. ' Returns input parameters required by this script 49. Public Sub BasicLaneTransition_GetInputParameters() 50. 51. On Error GoTo ErrorHandler 52. 53. ' Get the roadway stateobject 54. Dim oRwyState As AeccRoadwayState 55. Set oRwyState = GetRoadwayState() 56.

216 | Appendix B Creating Custom Subassemblies with VBA

57. ' Retrieve parameter buckets from the roadway state 58. Dim oParamsLong As AeccParamsLong 59. Set oParamsLong = oRwyState.ParamsLong 60. 61. Dim oParamsDouble As AeccParamsDouble 62. Set oParamsDouble = oRwyState.ParamsDouble 63. 64. ' Add the input parameters we use in this script 65. oParamsLong.Add g_sSide, c_iSideDefault 66. oParamsDouble.Add "Width", c_dLaneWidthDefault 67. oParamsDouble.Add "Depth", c_dLaneDepthDefault 68. oParamsDouble.Add "Slope", c_dLaneSlopeDefault 69. oParamsLong.Add "TransitionType", c_iHoldOriginalPositionDefault 70. 71. 72. Exit Sub 73. 74. ErrorHandler: 75. RecordError Err.Number, Err.Description, Err.Source 76. End Sub 77. 78. 79. ' ---------------------------------------------------------------------80. ' Returns output parameters returned by this script 81. ' ---------------------------------------------------------------------82. 83. Public Sub BasicLaneTransition_GetOutputParameters() 84. 85. On Error GoTo ErrorHandler 86. 87. ' This macro does not provide any output parameters 88. 89. Exit Sub 90. 91. ErrorHandler: 92. RecordError Err.Number, Err.Description, Err.Source 93. End Sub 94. 95. 96. 97. ' ---------------------------------------------------------------------98. ' Computes the BasicLaneTransition 99. ' ---------------------------------------------------------------------100. 101. Public Sub BasicLaneTransition() 102. 103. On Error GoTo ErrorHandler 104. 105. '--------------------------------------------------------107. 108. Dim oRwyState As AeccRoadwayState 109. Set oRwyState = GetRoadwayState() 110. 111. ' Retrieve parameter buckets from the roadway state 112. Dim oParamsDouble As AeccParamsDouble 113. Set oParamsDouble = oRwyState.ParamsDouble

Sample Subassembly VBA Script | 217

114. 115. 116. 117. 118. 119. 120. 121. 122. 123. 124. 125. 126. 127. 128. 129. 130. 131. 132. 133. 134. 135. 136. 137. 138. 139. 140. 141. 142. 143. 144. 145. 146. 147. 148. 149. 150. 151. 152. 153. 154. 155. 156. 157. 158. 159. 160. 161. 162. 163. 164. 165. 166. 167. 168. 169.

Dim oParamsLong As AeccParamsLong Set oParamsLong = oRwyState.ParamsLong Dim oParamsAlignment As AeccParamsAlignment Set oParamsAlignment = oRwyState.ParamsAlignment Dim oParamsProfile As AeccParamsProfile Set oParamsProfile = oRwyState.ParamsProfile Dim oParamsPoint As AeccParamsPoint Set oParamsPoint = oRwyState.ParamsPoint

'--------------------------------------------------------' now fetch a few parameters we're interested in On Error Resume Next

'--------------------------------------------------------' flip about Y-axis Dim vSide As Variant vSide = oParamsLong.Value(g_sSide) If IsEmpty(vSide) Then vSide = c_iSideDefault Dim dFlip As Double dFlip = 1# If vSide = g_iLeft Then dFlip = -1# End If '--------------------------------------------------------' Transition type Dim vTransitionType As Variant vTransitionType = oParamsLong.Value("TransitionType") If IsEmpty(vTransitionType) Then vTransitionType = _ c_iHoldOriginalPositionDefault '--------------------------------------------------------' BasicLaneTransition dimensions Dim vWidth As Variant vWidth = oParamsDouble.Value("Width") If IsEmpty(vWidth) Then vWidth = c_dLaneWidthDefault Dim vDepth As Variant vDepth = oParamsDouble.Value("Depth") If IsEmpty(vDepth) Then vDepth = c_dLaneDepthDefault Dim vSlope As Variant vSlope = oParamsDouble.Value("Slope") If IsEmpty(vSlope) Then vSlope = c_dLaneSlopeDefault '--------------------------------------------------------' Check user input

218 | Appendix B Creating Custom Subassemblies with VBA

170. If vWidth <= 0 Then 171. RecordError aeccRoadwayErrorValueShouldNotBeLessThanOrEqualToZero, _ "Width", "BasicLaneTransition" 172. vWidth = c_dLaneWidthDefault 173. End If 174. 175. If vDepth <= 0 Then 176. RecordError aeccRoadwayErrorValueShouldNotBeLessThanOrEqualToZero, _ "Depth", "BasicLaneTransition" 177. vDepth = c_dLaneDepthDefault 178. End If 179. 180. '--------------------------------------------------------181. ' Define codes for points, links and shapes 182. Dim sPointCodeArray(1 To 4, 0) As String 183. Dim sLinkCodeArray(1 To 2, 0 To 1) As String 184. Dim sShapeCodeArray(1 To 1) As String 185. 186. BasicLaneTransition_FillCodesFromTable sPointCodeArray, sLinkCodeArray, _ sShapeCodeArray 187. 188. '--------------------------------------------------------189. ' Get alignment and profile we're currently working from 190. 191. Dim oHA As AeccAlignment 192. Dim oVA As AeccProfile 193. 194. Dim dOffsetToTargetHA As Double 195. Dim dOffsetElev As Double 196. 197. If oRwyState.Mode = aeccRoadwayModeLayout Then 198. vTransitionType = TransitionTypes.kHoldOffsetAndElevation 199. End If 200. 201. Dim dTempStation As Double 202. Dim dTempOffset As Double 203. Dim oProfileAlignment As AeccAlignment 204. 205. Select Case vTransitionType 206. Case TransitionTypes.kHoldOffsetAndElevation 207. 208. Case TransitionTypes.kHoldElevationChangeOffset 209. 'oHA must exist 210. Set oHA = oParamsAlignment.Value("TargetHA") 211. If oHA Is Nothing Then RecordError 1, "Edge Offset", _ "BasicLaneTransition" 212. 'get offset to targetHA 213. CalcAlignmentOffsetToThisAlignment oRwyState.CurrentBaseline, _ oRwyState.Cur rentStation, oHA, dOffsetToTargetHA, dTempStation 214. 215. Case TransitionTypes.kHoldGradeChangeOffset 216. 'oHA must exist 217. Set oHA = oParamsAlignment.Value("TargetHA") 218. If oHA Is Nothing Then RecordError 1, "Edge Offset", _ "BasicLaneTransition" 219. 'get offset to targetHA 220. CalcAlignmentOffsetToThisAlignment oRwyState.CurrentBaseline, _ oRwyS tate.CurrentStation, oHA, dOffsetToTargetHA, dTempStation

Sample Subassembly VBA Script | 219

221. 222. Case TransitionTypes.kHoldOffsetChangeElevation 223. 'oVA must exist 224. Set oVA = oParamsProfile.Value("TargetVA") 225. If oVA Is Nothing Then RecordError 1, "Edge Elevation", _ "BasicLaneTrans ition" 226. 227. 'get elevation on profile 228. Set oProfileAlignment = oVA.Alignment 229. CalcAlignmentOffsetToThisAlignment oRwyState.CurrentBaseline, _ oRwyState.Cur rentStation, oProfileAlignment, dTempOffset, _ dTempStation 230. dOffsetElev = oVA.ElevationAt(dTempStation) 231. 232. Case TransitionTypes.kChangeOffsetAndElevation 233. Set oHA = oParamsAlignment.Value("TargetHA") 234. Set oVA = oParamsProfile.Value("TargetVA") 235. 236. 'both oHA and oVA must exist 237. If oHA Is Nothing Then RecordError 1, "Edge Offset", _ "BasicLaneTransition" 238. If oVA Is Nothing Then RecordError 1, "Edge Elevation", _ "BasicLaneTrans ition" 239. 240. 'get elevation on profile 241. 242. Set oProfileAlignment = oVA.Alignment 243. CalcAlignmentOffsetToThisAlignment oRwyState.CurrentBaseline, _ oRwyState.Cur rentStation, oProfileAlignment, dTempOffset, _ dTempStation 244. dOffsetElev = oVA.ElevationAt(dTempStation) 245. 246. 'get offset to targetHA 247. CalcAlignmentOffsetToThisAlignment oRwyState.CurrentBaseline, _ oRwyState.Cur rentStation, oHA, dOffsetToTargetHA, dTempStation 248. End Select 249. 250. '--------------------------------------------------------251. ' Create the subassembly points 252. 253. On Error GoTo ErrorHandler 254. 255. Dim oRoadwayPoints As AeccRoadwayPoints 256. Set oRoadwayPoints = oRwyState.Points 257. 258. Dim dX As Double 259. Dim dY As Double 260. 261. dX = 0# 262. dY = 0# 263. Dim oPoint1 As AeccRoadwayPoint 264. Set oPoint1 = oRoadwayPoints.Add(dX, dY, "") 265. 266. ' compute outside position of lane 267. Select Case vTransitionType 268. 269. Case TransitionTypes.kHoldOffsetAndElevation 270. 271. ' hold original position (always used in layout mode)

220 | Appendix B Creating Custom Subassemblies with VBA

272. 273. 274. 275. 276. 277. 278. 279. 280. 281. 282. 283. 284. 285. 286. 287. 288. 289. 290. 291. 292. 293. 294. 295. 296. 297. 298. 299. 300. 301. 302. 303. 304. 305. 306. 307. 308. 309. 310. 311. 312. 313. 314. 315. 316. 317. 318. 319. 320. 321. 322. 323. 324. 325. 326. 327.

dX = vWidth dY = Abs(vWidth) * vSlope / 100# Case TransitionTypes.kHoldElevationChangeOffset ' hold original elevation, move offset to that of TargetHA 'dX = Abs(dOffsetToTargetHA - oRwyState.CurrentSubassemblyOffset) dX = Abs(dOffsetToTargetHA - oRwyState.CurrentOffset) dY = Abs(vWidth) * vSlope / 100# Case TransitionTypes.kHoldGradeChangeOffset ' hold original grade, move offset to that of TargetHA ' (also used if TargetVA is not defined) 'dX = Abs(dOffsetToTargetHA - oRwyState.CurrentSubassemblyOffset) dX = Abs(dOffsetToTargetHA - oRwyState.CurrentOffset) dY = Abs(dX) * vSlope / 100# Case TransitionTypes.kHoldOffsetChangeElevation ' hold original offset, but change elevation to that of TargetVA dX = vWidth 'dY = dOffsetElev - oRwyState.CurrentSubassemblyElevation dY = dOffsetElev - oRwyState.CurrentElevation Case TransitionTypes.kChangeOffsetAndElevation ' move position to that of TargetHA, and elevation to TargetVA dX = Abs(dOffsetToTargetHA - oRwyState.CurrentSubassemblyOffset) dY = dOffsetElev - oRwyState.CurrentElevation End Select Dim oPoint2 As AeccRoadwayPoint Set oPoint2 = oRoadwayPoints.Add(dX * dFlip, dY, "") dY = dY vDepth Dim oPoint3 As AeccRoadwayPoint Set oPoint3 = oRoadwayPoints.Add(dX * dFlip, dY, "") dX = 0# dY = -vDepth Dim oPoint4 As AeccRoadwayPoint Set oPoint4 = oRoadwayPoints.Add(dX, dY, "") AddCodeToPoint AddCodeToPoint AddCodeToPoint AddCodeToPoint 1, 2, 3, 4, oRoadwayPoints, oRoadwayPoints, oRoadwayPoints, oRoadwayPoints, oPoint1.Index, oPoint2.Index, oPoint3.Index, oPoint4.Index, sPointCodeArray sPointCodeArray sPointCodeArray sPointCodeArray

'--------------------------------------------------------' save the outside edge of pavement as a marked point Dim rwyPoint As AeccRoadwayPoint Set rwyPoint = oPoint2 If Not rwyPoint Is Nothing Then

Sample Subassembly VBA Script | 221

328. Dim dElevation As Double 329. dElevation = rwyPoint.Elevation + oRwyState.CurrentElevation 330. Dim oParamPoint As AeccParamPoint 331. Set oParamPoint = oParamsPoint.Add("EdgeOfPavement") 332. oParamPoint.SetPoint oRwyState.CurrentStation, rwyPoint.Offset, _ dElevation 333. End If 334. 335. 336. '--------------------------------------------------------337. ' Create the subassembly links 338. 339. Dim oRoadwayLinks As AeccRoadwayLinks 340. Set oRoadwayLinks = oRwyState.Links 341. 342. Dim oPoint(1) As AeccRoadwayPoint 343. Dim oLink(3) As AeccRoadwayLink 344. 345. Set oPoint(0) = oPoint1 346. Set oPoint(1) = oPoint2 347. Set oLink(0) = oRoadwayLinks.Add(oPoint, "") 'L1 348. 349. Set oPoint(0) = oPoint2 350. Set oPoint(1) = oPoint3 351. Set oLink(1) = oRoadwayLinks.Add(oPoint, "") 'L2 352. 353. Set oPoint(0) = oPoint3 354. Set oPoint(1) = oPoint4 355. Set oLink(2) = oRoadwayLinks.Add(oPoint, "") 'L3 356. 357. Set oPoint(0) = oPoint4 358. Set oPoint(1) = oPoint1 359. Set oLink(3) = oRoadwayLinks.Add(oPoint, "") 'L4 360. 361. AddCodeToLink 1, oRoadwayLinks, oLink(0).Index, sLinkCodeArray 362. AddCodeToLink 2, oRoadwayLinks, oLink(2).Index, sLinkCodeArray 363. 364. '--------------------------------------------------------365. ' Create the subassembly shapes 366. 367. Dim oRoadwayShapes As AeccRoadwayShapes 368. Set oRoadwayShapes = oRwyState.Shapes 369. 370. Dim oShape1 As AeccRoadwayShape 371. Set oShape1 = oRoadwayShapes.Add(oLink, sShapeCodeArray(1)) 372. 373. Exit Sub 374. 375. ErrorHandler: 376. RecordError Err.Number, Err.Description, Err.Source 377. End Sub 378. 379. Private Sub BasicLaneTransition_FillCodesFromTable(sPointCodeArray() As String, sLinkCodeArray() As String, Optional sShapeCodeArray As Variant) 380. 381. 'check if the CodesStruct is filled in (will not be filled in two conditions: 382. '1. the moment the VBA application is loaded for the very first time

222 | Appendix B Creating Custom Subassemblies with VBA

383. 384. 385. 386. 387. 388. 389. 390. 391. 392. 393. 394. 395. 396. 397. 398. 399. 400. 401. 402. 403.

'2. the GC kicked-in and cleaned the global memory 'this ensure us that the CodesFile is not being read all the time the If Not g_AllCodes.g_bCodesStructureFilled Then FillCodeStructure End If sPointCodeArray(1, sPointCodeArray(2, sPointCodeArray(3, sPointCodeArray(4, sLinkCodeArray(1, sLinkCodeArray(1, sLinkCodeArray(2, sLinkCodeArray(2, 0) 0) 0) 0) = = = = g_AllCodes.g_sCrown.sCode g_AllCodes.g_sETW.sCode g_AllCodes.g_sETW_Subbase.sCode 'P4 g_AllCodes.g_sCrown_Subbase.sCode 'P3

0) 1) 0) 1)

= = = =

g_AllCodes.g_sTop.sCode g_AllCodes.g_sPave.sCode g_AllCodes.g_sDatum.sCode g_AllCodes.g_sSubbase.sCode

sShapeCodeArray(1) = g_AllCodes.g_sPave1.sCode Exit Sub End Sub

In the table below, the Lines column references line numbers for sections of the BasicLaneTransition subassembly VBA code shown above. The Description column describes the functionality provided by those lines of code. Sample Subassembly VBA Script Definitions Lines
1

Description
Always begin a module with the Option Explicit statement. This requires that all variable names and objects be explicitly declared. This subassembly uses a selection list for one of the parameters. The Enum definition defines default values for the menu choices in this list. Default values for each of the subassembly input parameters are defined as defaults in the VBA script. If for any reason a subassembly is used with undefined parameters, these defaults are used. The subassemblyname_GetLogicalNames subroutine must be present in the module for each subassembly. It defines the list of runtime logical assignments that appear in the Set All Logical Names dialog box used when creating a corridor model. Forces any runtime error to branch to the ErrorHandler: section of code. Declares and instantiates oRwyState, an object of type AeccRoadwayState. This type of object is the primary COM interface to the corridor model. Declares and instantiates oParamsLong, an object of type AeccParamsLong. This object is a bucket of parameters of type Long.

6-12

16-20

26 29-30

33-34

Sample Subassembly VBA Script | 223

Lines
37

Description
Adds a runtime logical assignment parameter for an alignment. The display name of the parameter is TargetHA. Adds a runtime logical assignment parameter for a profile. The display name of the parameter is TargetVA. Branch point for runtime errors. The RecordError writes the error number, description, and source to the Event Viewer window. The subassemblyname_GetInputParameters subroutine must be present in the module for each subassembly. It defines the list of input parameters. Declares and instantiates oRwyState, an object of type AeccRoadwayState. This type of object is the primary COM interface to the corridor model. Declares and instantiates input parameter buckets for parameters of type Long and Double. Adds each parameter to the appropriate parameter bucket, and initializes them to the default constants defined in lines 16 20. The parameter names appearing in quotes (Width, Depth) must match the Display Names defined for that subassembly in the catalog .atc files. The subassemblyname_GetOutputParameters subroutine must be present in the module for each subassembly. It defines the list of output parameters produced by the subassembly. This particular subassembly does not produce any output parameters. The subassemblyname subroutine must be present in the module for each subassembly. It is run when placing a subassembly into an assembly in Layout mode, and when such an assembly is used to create a corridor model. Declares and instantiates oRwyState, an object of type AeccRoadwayState. This type of object is the primary COM interface to the corridor model. Declares and instantiates parameter buckets for parameters of type Double, Long, Alignment, Profile, and Point. Most subassemblies can be inserted separately to the left or to the right of their attachment points in an assembly, and this is usually controlled by an input parameter with a selection list containing Left and Right. These enum values map to a Long value of either 0 or 1. g_sSide is a global variable which is defined in the Utilities module as follows: Public Const g_sSide As String = "Side"

42-43

54-55

58-62

65-69

83-93

101

108-109

112-125

137-139

224 | Appendix B Creating Custom Subassemblies with VBA

Lines

Description
Public Const g_iLeft As Integer = 1 Public Const g_iRight As Integer = 0 Line 138 retrieves the value of the Side parameter. This parameter has not been defined, it is set to the constant default.

141-145

The primary difference between left and right insertions is the direction used when calculating the offsets of subassembly points. This block sets a variable called dFlip that is either +1 or -1. This is used as a factor on all calculations involving point offsets. Each of the remaining input parameters is retrieved from the appropriate bucket type (Long, Double, etc.). The parameter values are read into local variables like vWidth and vDepth. In each case the default constant value is used if the parameter value cannot be retrieved from its bucket. These blocks check for invalid input parameter values, such as a negative width or subbase depth. The sPointCodeArray is used to set the codes to be assigned to each point stored by the subassembly. The first array dimension is the number of points, and the second (zero-based) is the greatest number of codes to be assigned to any one point. In this case, there are four points with one code each. Declares the arrays used to assign codes to the links and shapes stored by the subassembly. The call to the assemblyname_FillCodesFromTable subroutine assigns the codes to the arrays declared in lines 182 184. Dimensions objects providing COM access to alignment and profile objects. In layout mode (i.e., creating an assembly from subassemblies), dataspecific information such as actual alignments, profiles, and surfaces is not known. This subassembly is designed to tie the edge-of-lane to an offset alignment and profile. Since this information is not known in Layout mode, the If block sets the transition type variable to hold to a fixed offset and elevation. The BasicLaneTransition subassembly has fixed width and slope values provided as input parameters, and optional edge-of-lane alignment and profile names provided as runtime logical assignments. One of the parameters is a selection list providing different combinations of using the width vs. alignment, and slope vs. profile. The Case statement is used to perform necessary calculations based on the Transition Type chosen from this list. In Layout mode, the transition type is automatically set to ignore the alignment and profile (see 197 199).

148-166

170-178

182

183-184

186

191-192

197-199

205

Sample Subassembly VBA Script | 225

Lines
206

Description
For transition type Hold Offset and Elevation, no action is taken; the current width and slope values are correct. For transition type Hold Elevation and Change Offset, an offset alignment is used to calculate the lane width, but the elevation is to be calculated from the slope parameter. An object is defined for the TargetHA offset alignment, and the CalcAlignmentOffsetToTHisAlignment utility function is called to calculate the offset to that alignment in the local variable dOffsetToTargetHA. This option also uses the TargetHA alignment to calculate the lane width. This option holds the Width parameter but sets the edge-of-lane elevation from the TargetVA profile. It uses the CalcAlignmentOffsetToThisAlignment function to find the station on the offset profiles parent alignment, then uses profile objects .ElevationAt method to obtain the profile elevation at that station. Note that the corridor models baseline station is not directly used on the offset profile. This option uses both the TargetHA alignment and TargetVA profile. It assumes that the profiles parent alignment may be different than the TargetHA alignment, so it has to use the technique described in 222 230 to get the profile elevation, then gets the offset to the TargetHA alignment. Declares and instantiates oRoadwayPoints as an AeccRoadwayPoints object, which is a bucket containing all of the subassembly points. Variables dX and dY are used to store the delta-offset and delta-elevation of each point from the attachment point. Declares and instantiates oPoint1 as an AeccRoadwayPoint object, which is a single subassembly point, then stores the coordinates of the first point as 0,0. The Case statement calculates the dX, dY of the outside edge of lane, depending on the Transition Type selected by the user. Calculates the outside edge-of-lane dX, dY using the Width and Slope input parameters. Since the slope is provided as a percent value, it must be divided by 100 for the dY calculation. Calculates the edge-of-lane offset as the TargetHA alignment offset minus the .CurrentOffset property of the oRwyState object. Calculates the edge-of-lane elevation as the TargetVA profile elevation minus the .CurrentElevation property of the oRwyState object.

208-213

215-220

222-230

232-247

255-256

261-262

263-264

267-303

272-273

287

295

226 | Appendix B Creating Custom Subassemblies with VBA

Lines
306

Description
Stores the edge-of-lane point as oPoint2. Note that the dX value is multiplied by the vFlip variable so that it goes to the correct side. Calculates the dY on the subbase layer at the edge-of-lane, and stores as oPoint3. Sets oPoint4 to be the inside edge-of-lane on the subbase layer. Uses the AddCodeToPoint utility function to add the codes defined in the sPointCodeArray to each of the four subassembly points. Defines each of the four links stored by this subassembly. The oRoadwayLinks.Add method requires that the link endpoints be passed in a two element AeccRoadwayPoint array (oPoint). Adds codes to the finish grade and subbase links from sLinkCodeArray array. Uses the oLink array to define and store a shape. The subassemblyname_FillCodesFromTable is a special function used by Autodesk to set point, link, and shape codes from an external file instead of defining them in the VBA script.

308-310

312-315 317-320

339-359

361-362

367-371 379

Creating a Subassembly Tool Catalog

You can create an Autodesk tool catalog to organize groups of customized subassemblies and make them available to AutoCAD Civil 3D users. Autodesk tool catalogs are defined using xml-formatted files with an .atc (Autodesk Tool Catalog) extension. You also need to create a catalog registry file since catalogs must be registered in the Windows registry. Some items within the .atc and registry files must contain unique identifiers known as GUIDs (Global Unique Identifiers). To create a tool catalog for a subassembly 1 Using Notepad, or any other appropriate editor, create a plain ASCII text file named <Name>Tools Catalog.atc, where <Name> is the name of this new tool catalog. For information on the contents of the file, see Sample Tool Catalog ATC File (page 229). 2 Save the .atc file to the location where your tool catalogs are stored. The default location is C:\Documents and Settings\All Users\Application Data\Autodesk\C3D 2008\enu\Tool Catalogs. 3 Create any optional files, such as images for icons displayed in the catalog, and Help files for subassemblies, and place these files in appropriate locations for reference. 4 Using Notead, or any other text editor, create a registry file for the tool catalog with the extension .reg. For more information, see Sample Tool Catalog Registry File (page 228). 5 Register the tool catalog by double-clicking on the .reg file. Once registered, the subassembly tool catalog displays in the AutoCAD Civil 3D Content Browser.

Creating a Subassembly Tool Catalog | 227

Sample Tool Catalog Registry File

This sample tool catalog registry file is used to register an Autodesk subassembly tool catalog in the Windows registry. Refer to the table following the sample for descriptions of the various lines of the registry modification file.
1. REGEDIT4 2. 3. [HKEY_CURRENT_USER\Software\Autodesk\Autodesk Content Browser\45] 4. 5. [HKEY_CURRENT_USER\Software\Autodesk\Autodesk Content Browser\45\RegisteredGroups] 6. 7. [HKEY_CURRENT_USER\Software\Autodesk\Autodesk Content Browser\45\RegisteredGroups\Roads Group] 8. "ItemID"="{5BD79109-BC69-41eb-9AC8-7E9CD469C8D3}" 9. "ItemName"="Roads Group" 10. 11. 12. [HKEY_CURRENT_USER\Software\Autodesk\Autodesk Content Browser\45\RegisteredCatalogs] 13. 14. [HKEY_CURRENT_USER\Software\Autodesk\Autodesk Content Browser\45\RegisteredCata logs\Autodesk Civil 3D Imperial Corridor Catalog] 15. "ItemID"="{410D0B43-19B3-402f-AB41-05A6E174AA3F}" 16. "Image"=".\\Images\\AeccRoadway.png" 17. "Url"="C:\\Dozer\\Road Catalog\\Autodesk Civil 3D Imperial Corridor Catalog.atc" 18. "DisplayName"="Civil 3D Subassemblies (Imperial Units)" 19. "Description"="Imperial Units Subassemblies" 20. "Publisher"="Autodesk" 21. "ToolTip"="Autodesk Civil 3D Imperial Corridor Catalog" 22. "GroupType"="{5BD79109-BC69-41eb-9AC8-7E9CD469C8D3}" 23. 24. 25. [HKEY_CURRENT_USER\Software\Autodesk\AutoCAD \R16.1\ACAD-301:409\AEC\4.5\General\Tools] 26. "ToolContentRoot"="C:\\Dozer\\Scripts\\"

In the table below, the Lines column references line numbers for sections of the tool catalog registry file shown above. The Description column describes the functionality provided by those lines of code. Tool Catalog Registry File Code Descriptions Line
1 3-9

Description
Identifies the file as a registry edit file. These statements create a Group for the Autodesk Content Browser. The group id name is Roads Group. Each group must have a unique GUID for the ItemID. The Roads Group is already registered by the Civil 3D installation. If you are adding a catalog to this group, you should use the GUID shown in the example. Identifies the item being registered as an Autodesk catalog for the Autodesk Content Browser. These statements define the Catalog Entry.

14-22

228 | Appendix B Creating Custom Subassemblies with VBA

Line
15

Description
ItemId must be a unique GUID for this catalog. This must match the GUID for the Catalog ItemID value in the catalog .atc file. Image defines the name and location of the image file for the catalog icon. URL is a pointer to the catalog .atc file that is being registered. DisplayName is the text that displays beneath the catalog icon in the Autodesk Content Browser. Description description of the tool catalog. Publisher name of the creator / publisher of the tool catalog. ToolTip the text that displays for the tooltip when the cursor is hovered over the tool catalog in the Catalog Browser. GroupType the GUID that defines which the tool catalog belongs to in the Catalog Browser. This GUID must match the one used for the ItemID in the group definition.

17 18

19 20 21

Sample Tool Catalog ATC File

This sample tool catalog .atc file defines the contents of an Autodesk subassembly tool catalog. Refer to the table following the code sample for descriptions of the various lines of code. Each subassembly is defined as a <Tool> entry in the .atc file, and tools can be organized into categories and subcategories. This sample defines a catalog containing categories called Lanes and Shoulders. The Lanes category contains two subassembly tools: LaneOutsideSuper and LaneTowardCrown. The Shoulders category also contains two subassembly tools: ShoulderExtendSubbase and ShoulderVerticalSubbase.

Sample Tool Catalog ATC File | 229

1. <Catalog> 2. <ItemID idValue="{410D0B43-19B3-402F-AB41-05A6E174AA3F}"/> 3. <Properties> 4. <ItemName>Corridor Modeling Catalogs (Imperial)</ItemName> 5. <Images> 6. <Image cx="93" cy="123" src=".\Images\AeccCorridorModel.png"/> 7. </Images> 8. <AccessRight>0</AccessRight> 9. <Description>This catalog contains Subassembly tools for corridor modeling with Imper ial units.</Description> 10. <Time createdUniversalDateTime="2003-01-22T00:31:56" modifiedUniversalDateTime="200407-12T19:09:30"/> 11. </Properties> 12. <Source> 13. <Publisher> 14. <PublisherName>Autodesk</PublisherName> 15. </Publisher> 16. </Source> 17. <Tools/> 18. <Palettes/> 19. <Packages/> 20. <Categories> 21. <Category> 22. <ItemID idValue="{CB0E456C-AB63-4C77-B9E9-34759D242B54}"/> 23. <Properties> 24. <ItemName>Lanes</ItemName> 25. <Images/> 26. <Time createdUniversalDateTime="2002-09-16T14:23:57" modifiedUniversalDateTime="200209-16T14:23:57"/> 27. </Properties> 28. <CustomData/> 29. <Source/> 30. <Tools> 31. <Tool> 32. <ItemID idValue="{B4B7540E-E9BE-411D-82CA-AC191ED95AD6}"/> 33. <Properties> 34. <ItemName>LaneParabolic</ItemName> 35. <Images> 36. <Image cx="64" cy="64" src=".\Images\AeccLaneParabolic.png"/> 37. </Images> 38. <Description>Travel lanes with a parabolic cross section.</Description> 39. <Keywords>_LaneParabolic subassembly</Keywords> 40. <AccessRight>1</AccessRight> 41. <Help> 42. <HelpFile>.\Help\C3DStockSubassemblyHelp.chm</HelpFile> 43. <HelpCommand>HELP_HHWND_TOPIC</HelpCommand> 44. <HelpData>SA_LaneParabolic.html</HelpData> 45. </Help> 46. <Time createdUniversalDateTime="2002-04-05T21:58:00" modifiedUniversalDate Time="2002-04-05T21:58:00"/> 47. </Properties> 48. <Source/> 49. <StockToolRef idValue="{7F55AAC0-0256-48D7-BFA5-914702663FDE}"/> 50. <Data> 51. <AeccDbSubassembly>

230 | Appendix B Creating Custom Subassemblies with VBA

52. <Macro Module="%AECCCONTENT_DIR%\C3DStockSubassemblyScripts.dvb"> C3DStockSub assemblyScripts.LaneParabolic.LaneParabolic</Macro> 53. <Params> 54. <CrownHeight DataType="Double" DisplayName="Crown Height" Description="Height from the center of the string line to the crown of road">0.3333</CrownHeight> 55. <Width DataType="Double" DisplayName="Width" Description="Entire width of the parabolic roadway between edges-of-traveled-ways">24</Width> 56. <Pave1Depth DataType="Double" DisplayName="Pave1 Depth" Description="Thickness of the Pave1 layer">0.083</Pave1Depth> 57. <Pave2Depth DataType="Double" DisplayName="Pave2 Depth" Description="Thickness of the Pave2 layer">0.083</Pave2Depth> 58. <BaseDepth DataType="Double" DisplayName="Base Depth" Description="Thickness of the Base layer">0.333</BaseDepth> 59. <SubBaseDepth DataType="Double" DisplayName="Sub-base Depth" Description="Thick ness of the Subbase layer">1</SubBaseDepth> 60. <PerSlope DataType="Double" DisplayName="%Slope" Description="% slope of the string line from the left to right edges-of-traveled-ways">0</PerSlope> 61. <NoIncrements DataType="Long" DisplayName="No. Increments" Description="Number of straight line segments used to approximate the parabolic shape">8</NoIncrements> 62. </Params> 63. </AeccDbSubassembly> 64. <Units>foot</Units> 65. </Data> 66. </Tool> 67. <Tool> 68. <ItemID idValue="{1CC87FA0-76B8-4A94-8F68-04B5B0FD9502}"/> 69. <Properties> 70. <ItemName>LaneOutsideSuper</ItemName> 71. <Images> 72. <Image cx="64" cy="64" src=".\Images\AeccLaneOutsideSuper.png"/> 73. </Images> 74. <Description>Travel lanes using Outside Lane superelevation slope.</Description> 75. <Keywords>_LaneOutsideSuper subassembly</Keywords> 76. <AccessRight>1</AccessRight> 77. <Help> 78. <HelpFile>.\Help\C3DStockSubassemblyHelp.chm</HelpFile> 79. <HelpCommand>HELP_HHWND_TOPIC</HelpCommand> 80. <HelpData>SA_LaneOutsideSuper.html</HelpData> 81. </Help> 82. <Time createdUniversalDateTime="2002-04-05T21:58:00" modifiedUniversalDate Time="2002-04-05T21:58:00"/> 83. </Properties> 84. <Source/> 85. <StockToolRef idValue="{7F55AAC0-0256-48D7-BFA5-914702663FDE}"/> 86. <Data> 87. <AeccDbSubassembly> 88. <Macro Module="%AECCCONTENT_DIR%\C3DStockSubassemblyScripts.dvb"> C3DStockSub assemblyScripts.LaneOutsideSuper.LaneOutsideSuper</Macro> 89. <Params> 90. <Side DataType="Long" DisplayName="Side" Description="Specifies which side to place the subassembly">0 91. <Enum> 92. <Right DisplayName="Right">0</Right> 93. <Left DisplayName="Left">1</Left> 94. </Enum> 95. </Side>

Sample Tool Catalog ATC File | 231

96. <Width DataType="Double" DisplayName="Width" Description="Width of the travel lanes">12</Width> 97. <DefaultSlope DataType="Double" DisplayName="Default %Slope" Description="Default % slope of the lanes for regions where superelevation is not defined">-2.0</DefaultSlope> 98. <Pave1Depth DataType="Double" DisplayName="Pave1 Depth" Description="Thickness of the Pave1 layer">0.083</Pave1Depth> 99. <Pave2Depth DataType="Double" DisplayName="Pave2 Depth" Description="Thickness of the Pave2 layer">0.083</Pave2Depth> 100. <BaseDepth DataType="Double" DisplayName="Base Depth" Description="Thickness of the Base layer">0.333</BaseDepth> 101. <SubBaseDepth DataType="Double" DisplayName="Sub-base Depth" Description="Thick ness of the Subbase layer">1</SubBaseDepth> 102. </Params> 103. </AeccDbSubassembly> 104. <Units>foot</Units> 105. </Data> 106. </Tool> 107. </Tools> 108. <Palettes/> 109. <Packages/> 110. <Categories/> 111. <StockTools/> 112. </Category> 113. <Category> 114. <ItemID idValue="{3230B1FF-2C77-47BC-B53D-0557CB5E2B40}"/> 115. <Properties> 116. <ItemName>Shoulders</ItemName> 117. <Images/> 118. <Time createdUniversalDateTime="2002-09-16T14:23:57" modifiedUniversalDateTime="200209-16T14:23:57"/> 119. </Properties> 120. <CustomData/> 121. <Source/> 122. <Tools> 123. <Tool> 124. <ItemID idValue="{3ED4FBA8-4793-48FC-889C-E1E506D48D8E}"/> 125. <Properties> 126. <ItemName>ShoulderExtendSubbase</ItemName> 127. <Images> 128. <Image cx="64" cy="64" src=".\Images\AeccShoulderExtendSubbase.png"/> 129. </Images> 130. <Description>Paved shoulder with extended subbase.</Description> 131. <Keywords>_ShoulderExtendSubbase subassembly</Keywords> 132. <AccessRight>1</AccessRight> 133. <Help> 134. <HelpFile>.\Help\C3DStockSubassemblyHelp.chm</HelpFile> 135. <HelpCommand>HELP_HHWND_TOPIC</HelpCommand> 136. <HelpData>SA_ShoulderExtendSubbase.html</HelpData> 137. </Help> 138. <Time createdUniversalDateTime="2002-04-05T21:58:00" modifiedUniversalDate Time="2002-04-05T21:58:00"/> 139. </Properties> 140. <Source/> 141. <StockToolRef idValue="{7F55AAC0-0256-48D7-BFA5-914702663FDE}"/> 142. <Data> 143. <AeccDbSubassembly>

232 | Appendix B Creating Custom Subassemblies with VBA

144. <Macro Module="%AECCCONTENT_DIR%\C3DStockSubassemblyScripts.dvb"> C3DStockSub assemblyScripts.ShoulderExtendSubbase.ShoulderExtendSubbase</Macro> 145. <Params> 146. <Side DataType="Long" DisplayName="Side" Description="Specifies which side to place the subassembly">0 147. <Enum> 148. <Right DisplayName="Right">0</Right> 149. <Left DisplayName="Left">1</Left> 150. </Enum> 151. </Side> 152. <ShoulderWidth DataType="Double" DisplayName="Shoulder Width" Description="Width of the shoulder finish grade">8</ShoulderWidth> 153. <ShoulderSlope DataType="String" DisplayName="Shoulder %Slope" Description="% slope of the shoulder finish grade">-6</ShoulderSlope> 154. <HoldDaylightSlope DataType="Long" DisplayName="Subbase Daylight Type" Descrip tion="Select whether to hold the daylight link to a fixed slope with variable width, or hold it to a fixed width with variable slope">1 155. <Enum> 156. <True DisplayName="Hold slope, adjust width">1</True> 157. <False DisplayName="Hold width, adjust slope">0</False> 158. </Enum> 159. </HoldDaylightSlope> 160. <DaylightSlopeWidth DataType="Double" DisplayName="Daylight Slope/Width" De scription="x:1 slope or the width of the link to the subbase daylight point">4</Day lightSlopeWidth> 161. <SubbaseSlope DataType="String" DisplayName="Sub-base %Slope" Description="% slope of the subbase">-6</SubbaseSlope> 162. <Pave1Extension DataType="Double" DisplayName="Pave1 Extension" Description="Dis tance that Pave1 extends past the edge of shoulder">0</Pave1Extension> 163. <Pave2Extension DataType="Double" DisplayName="Pave2 Extension" Description="Dis tance that Pave2 extends past the edge of shoulder">0</Pave2Extension> 164. <BaseExtension DataType="Double" DisplayName="Base Extension" Description="Dis tance that Base extends past the edge of shoulder">0</BaseExtension> 165. <Pave1Depth DataType="Double" DisplayName="Pave1 Depth" Description="Thickness of the Pave1 layer">0.083</Pave1Depth> 166. <Pave2Depth DataType="Double" DisplayName="Pave2 Depth" Description="Thickness of the Pave2 layer">0.083</Pave2Depth> 167. <BaseDepth DataType="Double" DisplayName="Base Depth" Description="Thickness of the Base layer">0.333</BaseDepth> 168. <SubbaseDepth DataType="Double" DisplayName="Sub-base Depth" Description="Thick ness of the Subbase layer">1</SubbaseDepth> 169. </Params> 170. </AeccDbSubassembly> 171. <Units>foot</Units> 172. </Data> 173. </Tool> 174. <Tool> 175. <ItemID idValue="{76AC9AF2-B469-43D7-967F-BDF00FCEAB30}"/> 176. <Properties> 177. <ItemName>ShoulderVerticalSubbase</ItemName> 178. <Images> 179. <Image cx="64" cy="64" src=".\Images\AeccShoulderVerticalSubbase.png"/> 180. </Images> 181. <Description>Paved shoulder with truncated subbase.</Description> 182. <Keywords>_ShoulderVerticalSubbase subassembly</Keywords> 183. <AccessRight>1</AccessRight>

Sample Tool Catalog ATC File | 233

184. <Help> 185. <HelpFile>.\Help\C3DStockSubassemblyHelp.chm</HelpFile> 186. <HelpCommand>HELP_HHWND_TOPIC</HelpCommand> 187. <HelpData>SA_ShoulderVerticalSubbase.html</HelpData> 188. </Help> 189. <Time createdUniversalDateTime="2002-04-05T21:58:00" modifiedUniversalDate Time="2002-04-05T21:58:00"/> 190. </Properties> 191. <Source/> 192. <StockToolRef idValue="{7F55AAC0-0256-48D7-BFA5-914702663FDE}"/> 193. <Data> 194. <AeccDbSubassembly> 195. <Macro Module="%AECCCONTENT_DIR%\C3DStockSubassemblyScripts.dvb"> C3DStockSub assemblyScripts.ShoulderVerticalSubbase.ShoulderVerticalSubbase</Macro> 196. <Params> 197. <Side DataType="Long" DisplayName="Side" Description="Specifies which side to place the subassembly">0 198. <Enum> 199. <Right DisplayName="Right">0</Right> 200. <Left DisplayName="Left">1</Left> 201. </Enum> 202. </Side> 203. <PavedWidth DataType="Double" DisplayName="Paved Width" Description="Width of the paved portion of the shoulder">4</PavedWidth> 204. <PavedSlope DataType="String" DisplayName="Paved %Slope" Description="%slope of the paved portion of the shoulder">-6</PavedSlope> 205. <UnpavedLinkTreatment DataType="Double" DisplayName="Unpaved Link Treatment" Description="1 - alway add unpaved link; 2 - Add only if shoulder is in cut; 3 - add if shoulder is in cut or on high side of superelevation">1</UnpavedLinkTreatment> 206. <UnpavedWidth DataType="Double" DisplayName="Unpaved Width" Description="Width of the unpaved shoulder link">6</UnpavedWidth> 207. <UnpavedSlope DataType="Double" DisplayName="Unpaved %Slope" Description="%slope of the unpaved shoulder link">-6</UnpavedSlope> 208. <UnpavedMaxBreakover DataType="Double" DisplayName="Unpaved Max Breakover" Description="Maximum breakover between the paved and unpaved shoulder links">8</Unpaved MaxBreakover> 209. <Pave1Depth DataType="Double" DisplayName="Pave1 Depth" Description="Thickness of the Pave1 layer">0.083</Pave1Depth> 210. <Pave2Depth DataType="Double" DisplayName="Pave2 Depth" Description="Thickness of the Pave2 layer">0.083</Pave2Depth> 211. <BaseDepth DataType="Double" DisplayName="Base Depth" Description="Thickness of the Base layer">0.333</BaseDepth> 212. <SubbaseDepth DataType="Double" DisplayName="Sub-base Depth" Description="Thick ness of the Subbase layer">1</SubbaseDepth> 213. </Params> 214. </AeccDbSubassembly> 215. <Units>foot</Units> 216. </Data> 217. </Tool> 218. </Tools> 219. <Palettes/> 220. <Packages/> 221. <Categories/> 222. <StockTools/> 223. </Category> 224. </Categories>

234 | Appendix B Creating Custom Subassemblies with VBA

225.

</Catalog>

In the table below, the Lines column references line numbers for sections of the tool catalog .atc file code shown above. The Description column describes the functionality provided by those lines of code. Tool Catalog ATC File Code Descriptions Lines
1-225 2

Description
The <Catalog> section contains the entire contents of the catalog file. The <ItemID> defines a GUID for this catalog. The same GUID must be used in the registry file to identify this catalog. Defines general properties of the catalog. <ItemName> defines the name that appears beneath the catalog icon in the catalog browser. <Images> defines the image file for the icon that appears for the catalog in the catalog browser. Images used for catalogs and subassemblies should be a 64-by-64 pixel image. Valid image file types include .bmp, .gif, .jpg, and .png. <Description> defines the description of the catalog. <Time> defines the time and date the catalog was created in the universal date/time format. This information is required, but not used. Any date or time may be given. <Source> defines the source or creator of the catalog. Empty definitions for Tools, Palettes, and Packages. The <Categories> group defines a list of categories, each of which may contain sub-categories or subassembly tools. Category group defining the Lanes category. <ItemID> defines a unique GUID for this category. Defines the <Properties> of this category. <ItemName> defines Lanes as the title for the category. This name appears in the catalog browser. <Images> defines an icon that appears in the catalog browser for this category. No icon is given in this case, so only the name appears. Images used for catalogs and subassemblies should be a 64-by-64 pixel image. Valid image file types include .bmp, .gif, .jpg, and .png. Empty definitions for <CustomData> and <Source>.

3-11 4

5-7

9 10

12-16 17-19 20, 224

21, 112 22 23-27 24

28-29

Sample Tool Catalog ATC File | 235

Lines
30-107 31-66 32 33-47 34 35-37

Description
The <Tools> section list the individual tools found in this category. The <Tool> section defines a single subassembly within the category. <ItemID> defines a unique GUID for the subassembly. The <Properties> section defines the properties of the subassembly tool. <ItemName> defines the name of the subassembly. <Images> defines the image file for the icon associated with the subassembly. This icon appears in the catalog browser, and is also shown on the tool palette when the subassembly is copied there from the catalog. Images used for catalogs and subassemblies should be a 64by-64 pixel image. Valid image file types include .bmp, .gif, .jpg, and .png. <Description> defines the description of the subassembly tool. This description appears on the catalog browser beneath the subassembly name. <Keywords> The <Help> section defines the help file associated with the subassembly, and the method by which the help file is displayed. <HelpFile> defines the name of the help file. <HelpCommand> defines the command used to display the help file. <StockToolRef> defines a GUID specifically for catalog tools. This must use the idVlaue of {7F55AAC0-0256-48D7-BFA5-914702663FDE} Defines the data items associated with the subassembly tool. Defines the tool as an AeccDbSubassembly. Defines the VBA script used to execute the subassembly. This includes the location and name of the VBA library file, the name of the library itself, the name of the module, and the name of the subroutine. <Params> defines the names of the input parameters associated with the subassembly tool. This list appears in the Properties page of the subassembly, in the order they appear in the ATC file. Each parameter is defined on a single line in the ATC file with the following elements: Parameter name - The internal name of the parameter (e.g., CrownHeight). This is the name that must be used when saving or retrieving parameters to the parameter buckets.

39 41-45

42 43 49

50-65 51, 63 52

53-62

236 | Appendix B Creating Custom Subassemblies with VBA

Lines

Description
DataType=type Defines the type of variable used to store the parameter value, such as Long, Double, or String. For more information, see Data Type Information (page 237). DisplayName Defines the name that is displayed for the parameter in the subassembly Properties page. This is what the user sees to identify each parameter. Description Provides a description of the input parameter. When a parameter name is highlighted in the subassembly Properties page, the description appears at the bottom of the page. value The default value for the parameter. This is the value that appears for the parameter in the subassembly Properties page.

Data Type Information

The following tables describe the data types that can be used to define the variable that stores parameter values in the corridor modeling tool catalog .atc file. The tables are categorized into boolean, long, and double data types. The following table describes the boolean data types that can be used in the corridor modeling tool catalog .atc file for defining parameter values. Boolean Data Types Data Type
Bool BoolNoYes BoolDisabledEnabled BoolOffOn BoolRightLeft

Type String
0 1 5 6 7

Description
0 = True; 1 = False. 0 = Yes; 1 = No. 0 = Enabled; 1 = Disabled. 0 = On; 1 = Off. 0 = Right; 1 = Left.

The following table describes the long data types that can be used in the corridor modeling tool catalog .atc file for defining parameter values. Long Data Types Data Type
Long NonZeroLong NonNegativeLong NonNegativeNonZeroLong

Type String
0 1 2 3

Description
Any integer Any non-zero integer Zero or any positive integer Any non-zero positive integer

Data Type Information | 237

Data Type
NonPositiveLong NonPositiveNonZeroLong

Type String
4 5

Description
Zero or any negative integer Any non-zero negative integer

The following table describes the double data types that can be used in the corridor modeling tool catalog .atc file for defining parameter values. Double Data Types Data Type
Double NonNegativeDouble NonNegativeNonZeroDouble

Type String
0 1 2

NonPositiveDiuble NonPositiveNonZeroDouble

3 4

NonZeroDouble Grade TransparentCmdGrade TransparentCmdSlope Angle ConvergenceAngle Distance Dimension

5 8 9 10 14 15 16 17

Elevation Percent

21 25

238 | Appendix B Creating Custom Subassemblies with VBA

Creating a Tool Catalog Cover Page

Use an .html file to create introductory content that will display when a user clicks on this new catalog in the AutoCAD Civil 3D Content Browser. You can use any html editor to create the tool catalog cover page. It can be as simple or comprehensive as you like. Typically, the cover page gives an overview of the tools supplied in the catalog, and a brief description of how they may be used. To create a tool catalog cover page 1 Using any html editor, create an html file named <Name>ToolCatalogCoverPage.html where <Name> is the name of the new tool catalog. 2 Add the desired information to the cover page and save the file. 3 Place the file in the appropriate folder, usually the same folder as the .atc files.

Installing Custom Subassemblies

After you develop VBA scripts for custom subassemblies, you can make them available to AutoCAD Civil 3D users. To install custom subassemblies 1 Before installing custom subassemblies, make sure the VBA script defining the subassemblies has been created and tested. For more information about using VBA to customize AutoCAD-based applications, see the AutoCAD Developer Help. See Sample Subassembly VBA Script (page 215) for more information on developing the VBA script. 2 The AutoCAD Civil 3D corridor modeling (subassembly) scripts are located by default in C:\Program Files\Autodesk Civil 3D 2008\Data\Models. This default location can be changed at product installation. Copy custom subassembly VBA scripts to this location. 3 Create a tool catalog .atc file. For more information, see Sample Tool Catalog ATC File (page 229). 4 Create a catalog cover page. For more information, see Creating a Tool Catalog Cover Page (page 239). 5 Create a tool catalog .reg (registry file) and register the tool catalog. For more information, see Sample Tool Catalog Registry File (page 228).

Creating a Tool Catalog Cover Page | 239

240

Creating Client Applications

Overview
You can create stand-alone applications that use AutoCAD Civil 3D libraries to perform tasks. Sample programs written in C++, C#, and Visual Basic.NET are included in the Samples directory.

Samples
All of the following are located in the <installation-directory>\Sample\Civil 3D API directory.

C++ Using COM

.\VC++\COM C++\ProjectStats.vcproj Directly launches AutoCAD Civil 3D and creates a dialog box that displays some information about the current drawing or adds sample lines into the alignments of any selected sites.

Managed C++
.\VC++\Managed C++\C3DManagedExample.vcproj Using COM interops, launches AutoCAD Civil 3D and creates a dialog box that displays some information about the current drawing or adds sample lines into the alignments of any selected sites.

C++ Using CustomDraw

.\VC++\CustomDraw\Sample\C3DCustomDraw.vcproj Demonstrates accessing the CustomDraw API. This project overrides how triangles in TIN surfaces are drawn so that theyre numbered. It requires the Autodesk ObjectARX libraries.

C++ Client Sample

.\VC++\VcClient\VcClientSamp.vcproj

241

Creates a dialog box that lets you launch AutoCAD Civil 3D and determine simple information about the current drawing.

C#
.\CSharp\CSharpClient\CSharpClientSample.csproj Creates a dialog box that lets you launch AutoCAD Civil 3D and determine simple information about the current drawing.

Visual Basic .NET

.\VB_NET\VbDotNetClient\VBDotNetClientSample.vbproj Creates a dialog box that lets you launch AutoCAD Civil 3D and determine simple information about the current drawing.

242 | Appendix C Creating Client Applications

Index
A
AeccAlignment 72 AeccApplication 9 AeccCorridor 186 AeccDatabase 11 AeccDocument 10, 126, 182 AeccParcelSegment 6466 AeccPipeApplication 126 AeccPipeDocument 126 AeccPoint 33 AeccProfile 83 AeccProfileView 86 AeccRoadwayApplication 182 AeccRoadwayDocument 182 AeccSampleLine 92 AeccSection 99 AeccSectionView 100 AeccSite 64, 72 AeccSurface 44 AeccSurveyApplication 18 AeccSurveyDocument 18 AeccSurveyNetworkEntity 27 alignments 7278, 83, 92 creating 72 creating from polyline 73 design speeds 76 entities 74 offset alignments 73 profiles 83 sample lines 92 siteless 72 station equations 75 station sets 76 stations 75 styles 78 superelevation 77 ambient settings 12, 183 corridors 183 application object 9 assemblies 190192, 198 applied assemblies 191192 styles 198 creating 188 feature lines 193194 offset baselines 194 listing 188 offset baselines 189 breaklines 5152 non-destructive 52 proximity 52 standard 51 wall 52

C
collections 10 contours 5354 extracting 54 control points 23 corridor surfaces 197 cut and fill 197 corridors 182183, 186189, 192, 195199 adding stations 189 ambient settings 183 assemblies 198 styles 198 base objects 182 baselines 187188 concepts 186 corridor surfaces 195197 boundaries 196 masks 196 creating 187 links 192, 199 styles 199 listing 186 points 192 roadway style sets 199 shapes 192, 199 styles 199 custom subassemblies 178 package file 178

D
data bands 108, 110, 112, 114, 116, 119, 121123 concepts 108 profile views 110, 112, 114, 116, 119, 121122 adding to a view 122 creating 121 horizontal geometry styles 112

B
baselines 187189, 191, 193194 applied assemblies 191 baseline regions 188 baseline stations 189

243 | Index

profile styles 110 styles 119 superelevation styles 116 vertical geometry styles 114 section views 121, 123 adding to a view 123 creating 121 database object 11 directions 23 document object 10

E
entities 74, 8384 alignment 74 profiles 83 PVIs 84 Event Viewer 11 events 11 adding 11 exportTo 16 method 16 extended properties

F
feature lines 193194 offset baselines 194

I
interference check styles 143 141143

L
label styles 1315 creating 14 defining 14 property fields 15

styles 67 pipe documents 126, 141143 ambient settings 126 interference check 141143 styles 143 pipe network 130 creating 130 PipeNetworkCommandsSettings 126 pipes 127128, 130132 creating 130 dynamic part properties 127 parts list 128 styles 132 using 131 point groups 3941 creating 39 QueryBuilder 40 TIN surfaces 41 using 41 points 3334, 36, 3839 description keys 38 export to file 34 import from file 34 point groups 39 points collection 33 style 36 profile views 8687, 110 creating 86 data bands 110 styles 8687 axis style 86 axis tick marks 87 graph style 87 graph title 87 profiles 8385 creating from surface 83 creating using entities 83 PVIs 84 styles 85 PVI (points of vertical intersection) 84

S N
non-control points 25 sample lines 9293, 9597, 99 adding sample lines 93, 9596 at a station 95 by range 96 from a polyline 95 setup 93 creating 92 creating sections 99 sample line groups 9293, 99 styles 97 section views 100103 creating 100 styles 101103 axis style 102 axis tick marks 102 graph style 103

P
package file 178 custom subassemblies 178 package files 179 creating 179 parcel segments 6467 parcel loops 66 styles 67 parcels 6467 creating 64 parcel loops 66 parcel segments 6465

244 | Index

graph title 103 sections 99100 creating 99 section views 100 using 99 setups 24 sharing custom subassemblies 178 sites 64 creating 64 station equations 75 stations 7576 station sets 76 structures 127128, 136138 creating 136 dynamic part properties 127 parts list 128 styles 138 using 137 styles 16 exporting 16 subassemblies 147150, 153154, 156, 166167, 174, 176177, 190 attachment 147 CorridorState 153 example 156 Help files 150 installing 177 naming 147 parameters 148 superelevation 149 support files 154 template program 153 tool catalog 166167, 174, 176 cover page 176 creating 167 data types 174 example 167 registry file 176 superelevation 77, 116, 149 data bands 116 surface analysis 5657 elevation analysis 56 watershed analysis 57 surfaces 4447, 4951, 5357, 195197 boundaries 47, 196 collection 44 corridor surfaces 195196 creating 4446, 49 from .tin file 45 from DEM file 45, 49

from LandXML file 44 using AddGridSurface 46 using AddTinSurface 45 volume surfaces 46 cut and fill 197 elevation analysis 56 extracting contours 54 masks 196 snapshots 49 styles 55 TIN surfaces 5051, 53 breaklines 51 contours 53 point files 50 point groups 50 watershed analysis 57 survey 1830 ambient settings 19 equipment database 20 figures 2730 adding arcs 28 adding lines 27 adding to drawing 28 creating 27 effect on sites and parcels 28 effect on surfaces 29 prefix database 30 styles 29 network 2326 adding to drawing 26 control points 23 creating 23 directions 23 non-control points 25 setups 24 traverses 26 project 2122 creating 21 settings 22 root objects 18 user settings 19

T
ThisObject 10

V
VBA commands 3

Index | 245

246

SABITA Manual-13 - 1997
No ratings yet
SABITA Manual-13 - 1997
62 pages
Notes 1 - Design of Footings On Reactive Soils
No ratings yet
Notes 1 - Design of Footings On Reactive Soils
25 pages
Geogrids: Product Data
100% (1)
Geogrids: Product Data
11 pages
12d Range Files
No ratings yet
12d Range Files
7 pages
Sabita Man14 Granular Emulsion Mixes
No ratings yet
Sabita Man14 Granular Emulsion Mixes
23 pages
Revision of Bs 8002, 8004, AND 8081
100% (1)
Revision of Bs 8002, 8004, AND 8081
34 pages
New Mixer at LFL-Specifications Issue 1
No ratings yet
New Mixer at LFL-Specifications Issue 1
47 pages
Design Report
No ratings yet
Design Report
9 pages
Pavement Design
No ratings yet
Pavement Design
77 pages
BBA Cert For ReCo High Adherence Strip and Panel Lug System For Ret Walls & Bridge Abuts (2003)
No ratings yet
BBA Cert For ReCo High Adherence Strip and Panel Lug System For Ret Walls & Bridge Abuts (2003)
8 pages
Design and construction of deep basements including cut-and-cover structures（拖移項目） 2
100% (1)
Design and construction of deep basements including cut-and-cover structures（拖移項目） 2
2 pages
Chapter 1 (Sandy Lean Clay)
No ratings yet
Chapter 1 (Sandy Lean Clay)
17 pages
Effectiveness of Geomembrane Liners in Minimizing Seepage in Tailings Storage Facilities
No ratings yet
Effectiveness of Geomembrane Liners in Minimizing Seepage in Tailings Storage Facilities
14 pages
Sans 5863
No ratings yet
Sans 5863
9 pages
VIMP - Design and Construction of Road Tunnels Part 2 Methodology and Excavation Support
No ratings yet
VIMP - Design and Construction of Road Tunnels Part 2 Methodology and Excavation Support
215 pages
Appraisal On Chin Method
No ratings yet
Appraisal On Chin Method
5 pages
2024 Cost Per Unit - Second Half of The Year
No ratings yet
2024 Cost Per Unit - Second Half of The Year
166 pages
ARRB SR41 Pavement Materials
No ratings yet
ARRB SR41 Pavement Materials
4 pages
Tunnel Engineering-1 25042016 084008AM
No ratings yet
Tunnel Engineering-1 25042016 084008AM
82 pages
TMH11 Standard Survey Methods V3.0 1
No ratings yet
TMH11 Standard Survey Methods V3.0 1
333 pages
ALiCC PWRI 2006
No ratings yet
ALiCC PWRI 2006
47 pages
Topic 7 - AASHTO Flexible Pavement Design
No ratings yet
Topic 7 - AASHTO Flexible Pavement Design
16 pages
SATS SAR Rectangular Portals: (Rail Application Stormwater Culvert) - Class 1 Loading
No ratings yet
SATS SAR Rectangular Portals: (Rail Application Stormwater Culvert) - Class 1 Loading
1 page
Prokon Bending Schedule
No ratings yet
Prokon Bending Schedule
1 page
AKENYA Standard Specs
No ratings yet
AKENYA Standard Specs
346 pages
Reinforcement Bond Capacity: Jewell, R. A. (1990) - Gcotechnique 40, No. 3,51Q8
No ratings yet
Reinforcement Bond Capacity: Jewell, R. A. (1990) - Gcotechnique 40, No. 3,51Q8
6 pages
Asphalt Surfacing To Bridge Decks
No ratings yet
Asphalt Surfacing To Bridge Decks
44 pages
DMRB hd3816 Concrete Surfacing and Materials
100% (1)
DMRB hd3816 Concrete Surfacing and Materials
27 pages
Design Subgrade CBR For Flexible Pavements: Comparison of Predictive Methods
67% (3)
Design Subgrade CBR For Flexible Pavements: Comparison of Predictive Methods
16 pages
Some Difficulties Associated With The Limit Equilibrium Methods
No ratings yet
Some Difficulties Associated With The Limit Equilibrium Methods
12 pages
DM Reinforced Earth Wall
No ratings yet
DM Reinforced Earth Wall
76 pages
Armorflex 8pp
No ratings yet
Armorflex 8pp
8 pages
Retaining: Structures
No ratings yet
Retaining: Structures
6 pages
Seal Design and Construction (Additional Notes)
No ratings yet
Seal Design and Construction (Additional Notes)
43 pages
Drainage: Definition of Terms
No ratings yet
Drainage: Definition of Terms
14 pages
Geological Society, London, Engineering Geology Special Publications, 16, 257-289, 1 January 1999
No ratings yet
Geological Society, London, Engineering Geology Special Publications, 16, 257-289, 1 January 1999
33 pages
VIMP - Design and Construction of Road Tunnels Part 4 Obstacles and Mitigations
No ratings yet
VIMP - Design and Construction of Road Tunnels Part 4 Obstacles and Mitigations
163 pages
Lesson 6 SOIL CLASSIFICATION SCHEMES
No ratings yet
Lesson 6 SOIL CLASSIFICATION SCHEMES
24 pages
1-s2.0-S2352012424013067-main
No ratings yet
1-s2.0-S2352012424013067-main
10 pages
XDisp20.2 Manual 1
No ratings yet
XDisp20.2 Manual 1
205 pages
Design Review
No ratings yet
Design Review
40 pages
ArchesCulvertBrochure Humes
0% (1)
ArchesCulvertBrochure Humes
24 pages
How Eurocode 7 Has Affected Geotechnical Design
No ratings yet
How Eurocode 7 Has Affected Geotechnical Design
6 pages
Ground Improvement Techniques Unit-4
No ratings yet
Ground Improvement Techniques Unit-4
13 pages
JPCP Design Construction Guide
100% (1)
JPCP Design Construction Guide
37 pages
Anchorage Systems
No ratings yet
Anchorage Systems
5 pages
Shear Strength of Cohesionless Soils at Low Stress
No ratings yet
Shear Strength of Cohesionless Soils at Low Stress
12 pages
E-4-2 Traffic Appraisal Manual, Chapter 13
100% (1)
E-4-2 Traffic Appraisal Manual, Chapter 13
26 pages
COTO Standard Specifications For Road and Bridge Works For South African Road Authorities Book 1 of 3
100% (1)
COTO Standard Specifications For Road and Bridge Works For South African Road Authorities Book 1 of 3
466 pages
7 John Burland Paradox of The Gaussian Subsidence Trough
No ratings yet
7 John Burland Paradox of The Gaussian Subsidence Trough
40 pages
Grouting of Rock Masses - Giovanni Lombardi
No ratings yet
Grouting of Rock Masses - Giovanni Lombardi
34 pages
SANS1200MM
100% (1)
SANS1200MM
15 pages
A Catalogue of Details on Pre-Contract Schedules: Surgical Eye Centre of Excellence - Kath
From Everand
A Catalogue of Details on Pre-Contract Schedules: Surgical Eye Centre of Excellence - Kath
Edward Ayebeng Botchway
No ratings yet
Civil3d Developersguide
No ratings yet
Civil3d Developersguide
294 pages
AutoCAD Civil 3D 2011 Developers Guide
100% (1)
AutoCAD Civil 3D 2011 Developers Guide
292 pages
AutoCAD Civil 3D 2011 Developer S Guide
No ratings yet
AutoCAD Civil 3D 2011 Developer S Guide
292 pages
Manualcivil3dingles 090618111635 Phpapp01
No ratings yet
Manualcivil3dingles 090618111635 Phpapp01
182 pages
ObjectARX .NET Developer's Guide
No ratings yet
ObjectARX .NET Developer's Guide
86 pages
Acad Elec 2009 Userguide
No ratings yet
Acad Elec 2009 Userguide
1,622 pages
Civil Ug
No ratings yet
Civil Ug
2,320 pages
心理学畅销书 (少有人走的路) 英文原版
100% (1)
心理学畅销书 (少有人走的路) 英文原版
303 pages
MG RenderReady Tutorial AutoCAD PDF
No ratings yet
MG RenderReady Tutorial AutoCAD PDF
12 pages
Building Your Business PDF
No ratings yet
Building Your Business PDF
27 pages
Field Formulas: Highway Engineering
No ratings yet
Field Formulas: Highway Engineering
39 pages