ilog.views.graphlayout.labellayout.annealing

Interface IlvObstacleOffsetInterface

public interface IlvObstacleOffsetInterface

An interface used to select specific minimal offsets between certain label/obstacle pairs. It can be used to modify the effect of the global obstacle offset parameter: The global obstacle offset (see IlvAnnealingLabelLayout.setObstacleOffset(double)) specifies the minimal offset between labels and unrelated obstacles. In some situations, it may be desired to disable the effect of the global obstacle offset, because the label is allowed to move closer to certain obstacles than specified by the global obstacle value. In this case, the obstacle offset interface can be used. It allows you to make the effective obstacle offset for specific label/obstacle pairs smaller than the global obstacle offset.

As an example, assume the labels must be in general at least 10 units apart from unrelated obstacles, except for a specific label "X" that can move as close as 3 units to specific obstacles "A" and "B". You specify this by setting the global obstacle offset to 10, and by installing an IlvObstacleOffsetInterface that returns 3 for the call getOffset(model, X, A) and for the call getOffset(model, X, B), while it returns Double.MAX_VALUE for all other combinations of labels and obstacles.

The effective minimal obstacle offset is the minimum of the global obstacle offset and the value returned by this interface for the label/obstacle pair. The algorithm tries to place the label so that it is at least the effective minimal offset apart from an unrelated obstacle.

The obstacle offset interface cannot be used to make a minimal obstacle offset larger than the global obstacle offset. The global obstacle offset is always the upper limit, that is, if the obstacle offset interface returns larger values than the global obstacle offset, then the global offset is used. The global obstacle offset as the upper limit is necessary for technical reasons; hence it is not recommended to set the global obstacle offset to an unreasonably high value such as Double.MAX_VALUE, because this causes computational problems inside quadtree operations (see IlvAnnealingLabelLayout.setUseQuadtree(boolean)).

An implementation of the obstacle offset interface must be consistent; that means the method getOffset(IlvLabelingModel, Object, Object) should always return the same value for the same input parameter triple. In particular, it must be consistent during layout. An implementation that allows you to dynamically adjust the returned offset values works only if the dynamic adjustment is done while layout is not running, and if the dynamic adjustment notifies the layout via IlvLabelLayout.setParametersUpToDate(boolean) that the policy inside the obstacle interface has changed. For instance, an implementation could have a method setOffset, and the method getOffset(IlvLabelingModel, Object, Object) always returns the value that was previously passed to setOffset. In this case, setOffset should never be called while layout is running, and setOffset should call layout.setParametersUpToDate(false) on the layout that uses this implementation of the interface whenever it would cause getOffset(IlvLabelingModel, Object, Object) to return a different value for a certain parameter triple.

Since:

JViews 5.5

Method Summary

Modifier and Type	Method and Description
double	getOffset(IlvLabelingModel labelingModel, Object label, Object obstacle) Returns the desired minimal offset between the input label and the input obstacle.

Method Detail

getOffset

double getOffset(IlvLabelingModel labelingModel,
                 Object label,
                 Object obstacle)

Returns the desired minimal offset between the input label and the input obstacle. The effective minimal obstacle offset is the minimum of the global obstacle offset and the value returned by this method. For instance, return Double.MAX_VALUE if the label should be pushed away from the obstacle by at least the global obstacle offset, or return 0 if the label should not be pushed away from the obstacle despite any global obstacle offset settings.

Parameters:

labelingModel - The labeling model to which the label belongs.

label - The label.

obstacle - The obstacle.

Returns:

The desired minimal obstacle offset between the label and the obstacle.

See Also:

IlvAnnealingLabelLayout.setObstacleOffset(double)