DG Kernel Documentation

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

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.