IEuclideanShortestPath_KC Interface
Euclidean Shortest Path (ESP) algorithm calculates shortest length curve (path)
between two points in 3D space, which does not intersect any objects involved in
the calculation. See overview at
Euclidean Shortest Path.
To perform the calculation:
- Call IDIObjGenerator.Create
method with eType parameter set to eObjTypeESPAlgorithm
value from EObjectType
enumeration.
- Query IEuclideanShortestPath_KC from the returned object
- Select objects to be involved in the calculation using AddObject
or AddAllObjects
- Define input (initial guess) path using either SetInputPointCount and
Set(Add)InputPoint or
IArray3D obtained with GetInputPointArray
- Call Calculate() method to execute the main calculation
- Call GetOutputPath() to obtain the optimal path as a generic
curve. In this release the path is always a
Free Form curve
- Query ICurveFreeForm from the
ICurve interface obtained on the previous step
- Use ICurveFreeForm.GetData to access sampling points of
the curve
Input points must not be inside inside of any obejcts selected for the
calculation. Often segments of the initial path intersect some of the objects
even if input points are outside. The MakeInputValid
method inserts additional points if needed to move the path out of the object(s). MakeInputValid
is automatically called on start of Calculate(true)
call.
See also: Euclidean Shortest Path sample
- AddObject
- AddAllObjects
- SetInputPointCount
- GetInputPointCount
- SetInputPoint
- GetInputPoint
- AddInputPoint
- GetInputPointArray
- GetInputPath
- MakeInputValid
- Calculate
- GetOutputPath
- Reset
- GetPrecision
- SetPrecision
- GetOutputPath2
- Calculate2
- CalculatePerSegment
- GetObjects
- CloneNoPaths
HRESULT AddObject(ISection* obj)
Parameters
obj -[in] An object to be added for the calculation
HRESULT AddAllObjects(IModel* objects)
- Remarks
Adds all objects of the model for the calculation
HRESULT SetInputPointCount(int points)
Parameters
points -[in] New size of the input path array.
HRESULT GetInputPointCount(int* points)
- Remarks:
Returns size of the input point array (input path)
HRESULT SetInputPoint(int i, double x, double y, double z)
Parameters
i -[in] 0-based index of an input point
x, y,z -[in] Coordinates of the input point
- Remarks:
Modifies the i-th point of the input path. i must be in range 0 to size of the input
array as returned by the GetInputPointCount above
HRESULT GetInputPoint(int i, double* x, double* y, double* z)
Parameters
i -[in] 0-based index of an input point
x, y,z -[out] Coordinates of the input point
- Remarks:
Returns the i-th point of the input path. i must be in range 0 to size of the input
array as returned by the GetInputPointCount above
HRESULT AddInputPoint(double x, double y, double z)
Parameters
x, y -[in] Coordinates of the point to be appended to the
array
- Remarks:
Adds the point at the end of the input array. Size is incremented by one
HRESULT GetInputPointArray(IArray3D** iArray)
Parameters
iArray -[out,retval] - The returned input array
- Remarks:
Gives direct acces to the input array. This method is useful when a point has to
be inserted or deleted from the array
HRESULT GetInputPath(ICurve** path)
Parameters
path -[out,retval] ICurve interface of the input path
- Remarks:
Constructs a free form curve on the array of input points and returns its
interface. The returned interface can be used to add visual representation of
the path to the current scene using
IModel2.Display(iCurve)
Query ICurve > ICurveFreeForm
> ICurveFreeForm.GetData >
IArray3D produces the same array as returned by GetInputPointArray
HRESULT MakeInputValid()
Parameters
- Input points must be completely outside of any obejcts selected for the
calculation. Often segments of the initial path intersect some of the objects
even if input points are outside. The MakeInputValid
method inserts additional points if needed to move the path out of the object(s)
HRESULT Calculate(VARIANT_BOOL checkValidInput)
Parameters
checkValidInput -[in] See remarks
- Remarks:
Performs the main calculation. Call GetOutputPath to
obtain the results. As the computation is complicated it is recommended to
handle exceptions from this method
If checkValidInput is true MakeInputValid
method is called on start of the execution. This parameter should be false only
for performance reasons when it is certain when the intitial path is on surface
or outside of the objects
HRESULT GetOutputPath(ICurve** path)
Parameters
path -[out,retval] ICurve interface of the
output path
- Remarks:
Returns the calculated optimal path. The Calculate
method must be called prior a call to this method. In this release the curve is
a segmented free form curve defined by an array of points. Use ICurve > ICurveFreeForm
> ICurveFreeForm.GetData >
IArray3D query to obtain the array.
The returned interface can be used to add visual representation of the path to
the current scene using
IModel2.Display(iCurve)
HRESULT Reset(VARIANT_BOOL pathOnly)
Parameters
pathOnly -[in] See remarks
- Remarks:
Removes all results and the input array from the calculation engine. If pathOnly
is false the call also removes all objects added with AddObject
or AddAllObjects
HRESULT GetPrecision(double* precision)
Parameters
precision -[out,retval] See remarks
- Remarks:
Returns the current precision. See remarks for SetPrecision() below
HRESULT SetPrecision(double precision)
Parameters
pathOnly -[in] See remarks
- Remarks:
Sets precision used in termination condition of the algorithm. The higher this
value is the earlier the algorithm terminates. Lower values of precision produce
more exact optimal path but longer execution time. The default value may change
between versions and updates. Precision must be considered a relative value as
calculations multiply this value by several factors calculated dynamically
depending on geometry of objects and the initial path.
It is recommended to tune in this parameter for speficic types of applications.
To tune the precision in:
- Obtain the default value using the GetPrecision() method above.
- Multiply the precision by a tune-in factor. We suggest initial value of factor
of 5.0 to accelerate the algorithm or 0.5 to increase precision
- Run the algorithm a number times with a typical input. Increase the tune-in
factor to 10, 50, 100, ... (Reduce to 0.1, 0.05, 0.01, ...) to achieve the
optimal preformance vs precision trade off
HRESULT GetOutputPath2(ISurfacePointArrayKC** path)
Parameters
path -[out,retval]
- Remarks:
Returns the result after a Calculate() call as a surface point array. The surface points, apart from coordinates contain information
about the entity where the point belongs. Only end points may lie outside of any surface (ISurfacePointKC.GetItem() returns null).
HRESULT Calculate2(DIPoint* from, DIPoint* to, ISurfacePointArrayKC** path)
Parameters
path -[out,retval] See remarks
- Remarks:
A simplified way to calculate the shortest path for the case of two input points.
HRESULT CalculatePerSegment(ISurfacePointArrayKC** path)
Parameters
pathOnly -[in] See remarks
- Remarks:
Creates path, which is the shortest between each pair of consequitive input points. Useful for defining shortest segment
polygons on a surface. Can also be used for visualisation of the input path, which otherwise can be hidden
by convex parts of the surface. Notice also the ISurfacePointArrayKC.Offset(),
useful for avoiding aliasing during rendering.
HRESULT GetObjects(IArray** objects)
Returns entities added either by the AddObject() or AddAllObjects() above.
HRESULT CloneNoPaths(IEuclideanShortestPath_KC** esp)
Returns a new object implementing this interface, which contains only changes made with AddObject(), AddAllObjects() or GetPrecision() calls.
|