DTM API
Overview
A lot of functionality of Carlson triangulation and TIN file
manipulation is now available from LISP for the advanced users to use
in their routines. This part of the Carlson interface is called DTM API.
API supports the older FLT file format, which stores only edge
information, and the new TIN format, which is a binary format containing all
the structure of triangulation and therefore is faster to load
and takes less space. The file extension controls which file type
is being created.
The functionality of DTM API is implemented in TRI4.ARX. It would be
the responsibility of the caller to make sure that this file gets loaded by
adding this line at the beginning:
(scload (strcat lspdir$ "tri4"))
The ARX should never by unloaded by the caller.
The following is a list of currently supported functions (it can be obtained at any time by calling (cf:dtm_api):
create_tin - create a TIN
from selection set
draw_tin - draws a TIN as
3d faces;
tri_volume - produce
volume report from 1 or 2 TINs
tri_change - modify tin
using inc/exc and operators
tri_contour - contour tin
using inc/exc and ini file with settings
tri_diff - produce a
difference TIN from two TINs
tin_combine - produce a
combined TIN performing a specified operation to elevation
tri_store_regions -
create and store TIN difference
tri_apply_region - apply
a specific region revision
tri_forget_region -
forget all region revisions
surface_util - routines
for tin surface manager
create_tin
Creates TIN from a given selection set, optionally using inside/outside
logic.
Usage: (cf:dtm_api
"create_tin" entities_ss inclusion_ss exclusion_ss regions_ss file_name
options)
entities_ss - Selection
set of all entities to be used for triangulation. Currently supported
are point, line, arc, polyline, insert, circle, 3dface, solids, text,
and mtext.
inclusion_ss - Selection set
containing inclusion polylines if needed. Pass nil if inclusion
polylines are not being used.
exclusion_ss - Selection set
containing exclusion polylines if needed. Pass nil if exclusion polylines are not being used.
regions_ss - Selection set
containing region polylines if needed.
Pass nil if regions are not being used. Regions logic is on/off -
crossing region line reverses the inside/outside state. Note: Only one
of inside/outside methods can be used for one call (either
inclusion/exclusion or regions).
file_name - Full path of file
to be created. Extension controls a type of TIN file created.
options - Optional. String
containing one or more of the following keywords, space separated:
ignore_zero
- Ignore zero elevation data points.
view_error_log - In case of
warnings during triangulation, bring up the report at the end.
densify - Perform ridge/valley
detection and improve triangulation as needed.
draw_tin
Draws TIN file at a given layer as 3DFACEs.
Usage: (cf:dtm_api
"draw_tin" file_name layer_name is_road)
file_name - Full path of file
to be loaded.
layer_name - Layer name to use.
If does not yet exist, new layer will be created. Color of entities is
set to BYLAYER.
is_road - Optional. If set to
1 and route follows completion of Process Road Design feature it will
turn on road coloring.
tri_volume
Calculates volume of the TIN within a given polyline, optionally with
report generated.
Usage: (cf:dtm_api
"tri_volume" inclusion_ss exclusion_ss regions_ss filename
filename2|elevation is_report is_silent)
Return values: If successful, the function returns a list with 4 real
values: cut, fill, cut area, and fill area. The volume is in cubic ft or
meters and area is in square ft or meters, depending on the configuration.
inclusion_ss - Selection set
containing inclusion polylines if needed. Pass nil if inclusion
polylines are not being used.
exclusion_ss - Selection set
containing exclusion polylines if needed. Pass nil if exclusion polylines are not being used.
regions_ss - Selection set
containing region polylines if
needed.
Pass nil if regions are not being used. Regions logic is on/off -
crossing region line reverses the inside/outside state. Note: Only one
of inside/outside methods can be used for one call (either
inclusion/exclusion or regions).
filename - Full path of main
TIN file to be used.
filename2 - Full path of
secondary TIN file to be used. If used, two surface volumes will be
calculated between the first and second TINs.
elevation - Reference elevation
passed as real value. If this option is used, one surface volume
will be calculated between the first TIN and this reference elevation.
is_report - 0/1. Specifies
whether to bring up the report with calculation results.
is_silent - 0/1. If 0 value is
supplied the routine will provide no output at the command line and no
progress indicators.
tri_change
Change TIN file using specified optional inclusion polylines and using
one of the possible math operations. For all operations but "embed" the
inclusion/exclusion polylines are offset a 0.1 so that a reasonably sharp
wall could be produced by modifications.
Usage: (cf:dtm_api
"tri_change" inclusion_ss exclusion_ss regions_ss filename operation
value)
inclusion_ss - Selection set
containing inclusion polylines if needed. Pass nil if inclusion
polylines are not being used.
exclusion_ss - Selection set
containing exclusion polylines if needed. Pass nil if exclusion polylines are not being used.
regions_ss - Selection set containing region polylines if
needed.
Pass nil if regions are not being used. Regions logic is on/off -
crossing region line reverses the inside/outside state. Note: Only one of inside/outside methods can be used for one call
(either inclusion/exclusion or regions).
filename - Full path of main
TIN file to be modified.
operation - keywords describing
what operation is to be performed on the TIN:
add -
Add a value to elevation of inside nodes.
scale - Scale elevation of
inside nodes by the value.
set - Set elevation of inside
nodes to the value specified.
perp - Sets elevation of nodes
as if TIN is offset by value along normal at the point. The node is not
moved horizontally, just elevation is adjusted.
nil - Removes inside nodes. No
value is needed.
embed - No change of
elevations, but the inclusion polyline is still added to TIN.
tri_contour
Contours TIN file as defined by INI file and inclusion polylines
Usage: (cf:dtm_api
"tri_contour" inclusion_ss exclusion_ss regions_ss tin_filename
ini_filename)
inclusion_ss - Selection
set
containing inclusion polylines if needed. Pass nil if inclusion
polylines are not being used.
exclusion_ss - Selection set
containing exclusion polylines if needed. Pass nil if exclusion polylines are not being used.
regions_ss - Selection set containing region polylines if
needed.
Pass nil if regions are not being used. Regions logic is on/off -
crossing region line reverses the inside/outside state. Note: Only one of inside/outside methods can be used for one call
(either inclusion/exclusion or regions).
tin_filename - Full path of
main
TIN file to be used.
ini_filename - Full path of INI
file defining how contouring is performed. For list of values, check
tri4.ini in USER folder which stores values used in Triangulate and Contour function.
tri_diff
Calculates difference between two TIN files and creates combined TIN
with elevation being the difference of elevations. TINs do not have to
match perfectly - face intersections will be performed. Inclusion logic
will be applied if needed.
Usage: (cf:dtm_api
"tri_diff" inclusion_ss exclusion_ss regions_ss filename1 filename2
diff_filename)
inclusion_ss - Selection set
containing inclusion polylines if needed. Pass nil if inclusion
polylines are not being used.
exclusion_ss - Selection set
containing exclusion polylines if needed. Pass nil if exclusion polylines are not being used.
regions_ss - Selection set containing region polylines if
needed.
Pass nil if regions are not being used. Regions logic is on/off -
crossing region line reverses the inside/outside state. Note: Only one of inside/outside methods can be used for one call
(either inclusion/exclusion or regions).
filename1, filename2 - Full
path to
TIN files to be used. Second TIN is subtracted from first one.
diff_filename - Full path of
differential TIN file to be created.
tin_combine
Combines two TINs into one while applying one of the specified operations.
First two TINs are combined into one intersecting all faces which need
to be intersected and then elevations are assigned as specified.
Usage: (cf:dtm_api
"tin_combine" inclusion_ss exclusion_ss regions_ss filename1 filename2
merged_filename operation)
inclusion_ss - Selection set
containing inclusion polylines if needed. Pass nil if inclusion
polylines are not being used.
exclusion_ss - Selection set
containing exclusion polylines if needed. Pass nil if exclusion polylines are not being used.
regions_ss - Selection set containing region polylines if
needed.
Pass nil if regions are not being used. Regions logic is on/off -
crossing region line reverses the inside/outside state. Note: Only one of inside/outside methods can be used for one call
(either inclusion/exclusion or regions).
filename1, filename2 - Full
path to
TIN files to be used.
merged_filename - Full path to
the file where results are stored.
operation - Keywords describing
the operation to perform. The following operations are supported:
keep
- The elevations of first TIN are used.
copy - Elevations of second TIN
are used.
min - Lesser of two elevations
is used.
max - Greater of two elevations
is used.
join - Points inside are given
elevations of first TIN, outside - second one.
tri_store_regions
Evaluates "before" and "after" TIN and stores "affected" area as a
region with two revisions "0" and "1". The regions then can be
applied as needed using other commands. This functionality only works
with binary .TIN files.
Usage: (cf:dtm_api
"tri_store_regions" filename1 filename2 mark_name filename3)
filename1, filename2 - Full
path to
TIN files to be used.
mark_name
- String label for region to be used.
filename3 - Full path to
TIN files to be Save As. If omitted, the file specified by
filename1 will be replaced with resulting file.
tri_apply_region
Applies a specific pre-stored region revision, so that when TIN file is
used it has that revision of the region in use.
Usage: (cf:dtm_api
"tri_apply_region" filename mark_name revision)
filename1 - Full path to TIN
file to be modified.
mark_name
- String label for region to be used.
revision - Integer. Optional
ID of revision to apply. If omitted, the latest revision of the region
is used.
tri_forget_region
Removes any knowledge of a specific pre-stored region revision from
TIN file. Optionally remove triangles found in the region from the TIN.
Usage: (cf:dtm_api
"tri_forget_region" filename mark_name remove_first)
filename - Full path to TIN
file to be modified.
mark_name
- String label for region to be used.
remove_first- 0/1. Optional
flag indicating whether region triangles should be removed, leaving a
hole in the TIN.
surface_util
Utilities for dealing with surfaces stored in the drawing.
Usage: (cf:dtm_api
"surface_util" filename operation)
filename - Full path to TIN
file to be modified.
operation - Keywords
describing the operation to perform. The following operations are
supported:
check
- Check if TIN is used
in one of the surfaces. Returns 0 or 1 depending on outcome.
process - Apply current
surface parameters to TIN file. This function should be used to update
surface in the drawing after TIN has been modified.