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_profile - creates a
profile of the TIN along a centerline
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
load_tin - loads TIN into
memory for tin_z function
unload_tin - unloads the
current TIN from memory
tin_z - returns the z at
the specified x,y for the current TIN set by load_tin
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_profile
Creates a profile of the TIN along a centerline
Usage: (cf:dtm_api
"tri_profile" tin_filename cl_filename pro_filename)
Return
values: If successful, the function returns 1, otherwise
nil.
tin_filename - Full
path of main TIN file to be used.
cl_filename - Full path of
centerline (.cl) file to be used.
pro_filename - Full path of
the profile file to be created.
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.
load_tin
Loads a TIN into memory for use with the tin_z function.
Usage: (cf:dtm_api "load_tin"
file_name)
file_name - Full path of
file to be loaded.
unload_tin
Unloads the current TIN from memory.
Usage: (cf:dtm_api
"unload_tin")
tin_z
Calculates the elevation of the TIN at the specified x,y location.
The TIN to process must be already loaded by the load_tin command.
The calculated elevation is returned to LSP on success. A nil is
returned to LSP if the command arguments are invalid, a TIN is not
loaded or the point is off the surface.
Usage: (setq elev (cf:dtm_api
"tin_z" point))
point - List of doubles in
x,y format
Examples:
Calculate TIN Elevation at Point
(scload (strcat lspdir$ "tri4"))
(setq file_name (scad_getfiled "Select TIN to Process" "" "tin"
0))
(cf:dtm_api "load_tin" file_name)
(setq pnt (getpoint "\nPick point:"))
(setq elev (cf:dtm_api "tin_z" pnt))
(cf:dtm_api "unload_tin")