Package com.luciad.view.lightspeed.util

Class TLspViewNavigationUtil

java.lang.Object
com.luciad.view.lightspeed.util.TLspViewNavigationUtil
public final class TLspViewNavigationUtil extends Object
This class allows you to programmatically navigate in a Lightspeed view.

This class supports:

These methods immediately snap the view to the requested state, without transition.

This class also supports animated navigation in a view. This allows a smooth transition from the current state to the desired state.

These methods return an ILcdAnimation. Depending on the auto-start property, you still need to run these animation using the ALcdAnimationManager. Typically, you would use the view's camera as key, e.g.: ALcdAnimationManager.getInstance().putAnimation(view.getViewXYZWorldTransformation(), animation);

Since:
2012.0

  • Constructor Details

    • TLspViewNavigationUtil

      public TLspViewNavigationUtil(ILspView aView)
      Constructor for new TLspViewNavigationUtil.
      Parameters:
      aView - the view to navigate on.

  • Method Details

    • getAnimationSpeedUp

      public double getAnimationSpeedUp()
      Returns the animation speedup used by all (non-continuous animations offered by this class).
      Returns:
      the animation speedup.

    • setAnimationSpeedUp

      public void setAnimationSpeedUp(double aAnimationSpeedUp)
      Sets the animation speed used by all (non-continuous animations offered by this class). The default value is 1.0. A value of 2.0 means animation will run twice as fast, a value of 0.5 means they take twice as long.
      Parameters:
      aAnimationSpeedUp - the animation speed up to use.

    • isAutoStartAnimations

      public boolean isAutoStartAnimations()
      Returns true if (non-continuous) animations should be started as soon as they are created.
      Returns:
      true if animations are started automatically, false otherwise.

    • setAutoStartAnimations

      public void setAutoStartAnimations(boolean aAutoStartAnimations)
      Enables or disables automatically starting (non-continuous) animations. By default this is set to true.
      Parameters:
      aAutoStartAnimations - true if animations should be started automatically, false otherwise.
      See Also:

    • pan

      public void pan(ILcdPoint aViewPointStart, ILcdPoint aViewPointDestination)
      Pans the view so that the world point visible under aViewPointStart is visible under aViewPointDestination instead.
      Parameters:
      aViewPointStart - the start of the pan action, in view coordinates.
      aViewPointDestination - the destination of the pan action, in view coordinates.

    • rotate

      public void rotate(ILcdPoint aRotateCenter, double aDeltaYaw, double aDeltaPitch)
      Rotates the view around aRotateCenter. The passed values are added to the current yaw and pitch angle.
      Parameters:
      aRotateCenter - the point in world coordinates to rotate around.
      aDeltaYaw - the change in yaw, in degrees.
      aDeltaPitch - the change in pitch, in degrees (typically only used in 3D).

    • rotateTo

      public void rotateTo(ILcdPoint aRotateCenter, double aYaw, double aPitch)
      Rotates the view around aRotateCenter. The yaw and pitch are set to the passed values.
      Parameters:
      aRotateCenter - the point in world coordinates to rotate around.
      aYaw - the change in yaw, in degrees.
      aPitch - the change in pitch, in degrees (typically only used in 3D).

    • zoom

      public void zoom(double aFactor)
      Zoom in or out on the center of the view with the specified factor.
      Parameters:
      aFactor - the zoom factor with which to multiply the view scale. Values larger than 1 zoom in, smaller values zoom out.

    • zoom

      public void zoom(ILcdPoint aViewPointCenter, double aFactor)
      Zooms in or out on aViewPointCenter with the specified factor.
      Parameters:
      aViewPointCenter - the point to zoom in or out on, in view coordinates.
      aFactor - the zoom factor with which to multiply the view scale. Values larger than 1 zoom in, smaller values zoom out.

    • zoom

      public void zoom(TLcdMapScale aMapScale, TLcdMapScale.ScaleLocation aScaleLocation)
      Zooms to the given map scale.

      Bear in mind that on 3D maps, this method might be somewhat inaccurate. This is the case because the map scale depends heavily on the terrain data that is currently loaded on the map, while the terrain in turn also depends on the scale. Specifically, more detailed terrain gets loaded as you're zooming in, so when zooming in from far away, the terrain's low level of detail can significantly affect your zoom operation. To counter this effect, it is recommended to use the animated zoom instead when that is possible. This method lasts a couple of frames and thereby allows the zoom to adapt to any terrain changes that appear in the process. 2D maps are not affected by this issue.

      Parameters:
      aMapScale - the target map scale to zoom in or out to
      aScaleLocation - where the map scale should be measured
      Since:
      2021.0

    • animatedPan

      public ALcdAnimation animatedPan(ILcdPoint aViewPointStart, ILcdPoint aViewPointDestination)
      Returns an animation with the specified aDuration that pans the view from aViewPointStart to aViewPointDestination.

      If the auto start property is true, the animation will be started before the method returns, and already running navigation animations are cancelled.

      Parameters:
      aViewPointStart - the start of the pan action, in view coordinates.
      aViewPointDestination - the destination of the pan action, in view coordinates.
      Returns:
      a pan animation

    • animatedContinuousPan

      public ILcdAnimation animatedContinuousPan(double aSpeedX, double aSpeedY)
      Returns an animation that pans the view until stopped with a direction and speed specified by aSpeedX and aSpeedY.

      This method will not start this animation. The user should call putAnimation with the view's ALspViewXYZWorldTransformation as key. Note that this animation will run indefinitely until manually removed for the animation manager.

      Parameters:
      aSpeedX - the x pan speed, in pixels per second.
      aSpeedY - the y pan speed, in pixels per second.
      Returns:
      an animation panning the view when started until it is stopped.

    • animatedRotate

      public ALcdAnimation animatedRotate(ILcdPoint aRotateCenter, double aDeltaYaw, double aDeltaPitch)
      Returns an animation with the specified aDuration that rotates the view around aRotateCenter.

      If the auto start property is true, the animation is started before the method returns, and already running navigation animations are cancelled.

      Parameters:
      aRotateCenter - the center of the rotation, in world coordinates.
      aDeltaYaw - the change in yaw, in degrees.
      aDeltaPitch - the change in pitch, in degrees. Only used in 3D.
      Returns:
      a rotate animation

    • animatedContinuousRotate

      public ILcdAnimation animatedContinuousRotate(ILcdPoint aRotateCenter, double aYawSpeed, double aPitchSpeed)
      Returns an animation that rotates the view around aRotateCenter until stopped. The speed is defined by aYawSpeed and aPitchSpeed.

      This method will not start this animation. The user should call putAnimation with the view's ALspViewXYZWorldTransformation as key.

      Parameters:
      aRotateCenter - the center of the rotation, in world coordinates.
      aYawSpeed - the yaw speed, in degrees per second.
      aPitchSpeed - the pitch speed, in degrees per second.
      Returns:
      an animation rotating the view when started until it is stopped.

    • animatedZoom

      public ALcdAnimation animatedZoom(double aFactor)
      Starts an ILcdAnimation that zooms the view by the specified factor. A factor 1 means no change; larger values zoom in, smaller values zoom out. The zoom is performed on the center of the view.

      If the auto start property is true, the animation is started before the method returns, and already running navigation animations are cancelled.

      Parameters:
      aFactor - the zoom factor with which to multiply the view scale
      Returns:
      a zoom animation

    • animatedZoom

      public ALcdAnimation animatedZoom(TLcdMapScale aMapScale, TLcdMapScale.ScaleLocation aScaleLocation)
      Creates an animation that zooms from the view's current map scale to the given map scale.

      If the auto start property is true, the animation is started before the method returns, and already running navigation animations are cancelled.

      Parameters:
      aMapScale - the target map scale to zoom in or out to
      aScaleLocation - where the map scale should be measured
      Returns:
      a zoom animation
      Since:
      2022.0

    • animatedContinuousZoom

      public ILcdAnimation animatedContinuousZoom(ILcdPoint aViewPointCenter, double aZoomSpeed)
      Returns an animation that zooms the view in or out on aViewPointCenter until stopped. The speed is defined by aZoomSpeed.

      This method will not start this animation. The user should call putAnimation with the view's ALspViewXYZWorldTransformation as key.

      Parameters:
      aViewPointCenter - the point to zoom in on.
      aZoomSpeed - the zoom speed, every second the view is zoomed with this factor by multiplying it with the view scale
      Returns:
      an animation zooming on the view when started until it is stopped.

    • animatedZoom

      public ALcdAnimation animatedZoom(double aFactor, ILcdPoint aViewPointCenter)
      Starts an ILcdAnimation that zooms the view by the specified factor. A factor 1 means no change; larger values zoom in, smaller values zoom out. The zoom is performed around the specified point in the view. To also pan the view so that the target point will end up in the middle of the view, use animatedZoomTo(com.luciad.shape.ILcdPoint, double).

      If the auto start property is true, the animation is started before the method returns, and already running navigation animations are cancelled.

      Parameters:
      aFactor - the zoom factor with which to multiply the view scale
      aViewPointCenter - the point to zoom in on or zoom out from, in view coordinates
      Returns:
      a zoom animation

    • animatedZoomTo

      public ALcdAnimation animatedZoomTo(ILcdPoint aViewPointDestination, double aFactor)
      Starts an ILcdAnimation that centers the view on the specified point and zooms it by the specified factor. A factor 1 means no change; smaller values zoom in, larger values zoom out.

      If the auto start property is true, the animation is started before the method returns, and already running navigation animations are cancelled.

      Parameters:
      aViewPointDestination - the location to center on, in view coordinates
      aFactor - the zoom factor with which to multiply the view scale
      Returns:
      a zoom animation

    • getFitMargin

      public double getFitMargin()
      Returns the margin that is added to the bounds passed to fit(com.luciad.view.lightspeed.layer.ILspLayer...) or animatedFit(com.luciad.shape.ILcdBounds, com.luciad.reference.ILcdGeoReference).
      Returns:
      the margin of the bounds.
      See Also:

    • setFitMargin

      public void setFitMargin(double aMargin)

      Sets a margin on the bounds passed to fit(com.luciad.view.lightspeed.layer.ILspLayer...) or animatedFit(com.luciad.shape.ILcdBounds, com.luciad.reference.ILcdGeoReference). This margin is used to enlarge the bounds on which to fit. The given margin is a value larger than or equal to 0. The margin is added to all sides of the bounds. E.g. if the margin is 0.1, both the width and height of the bounds are enlarged by 20%.

      By default, this value is 0.05.

      Parameters:
      aMargin - the margin used to enlarge the bounds on which to fit.

    • animatedFit

      public ILcdAnimation animatedFit(ILcdBounds aBounds, ILcdGeoReference aBoundsReference) throws TLcdOutOfBoundsException
      Starts an animation that fits the view on the specified bounds.

      This fit animation updates the ALspViewXYZWorldTransformation so that the specified bounds fit entirely in the given view. This method will both move the view and change the scale, but will keep the current rotation or pitch (in 3D).

      If the auto start property is true, the animation is started before the method returns, and already running navigation animations are cancelled.

      Parameters:
      aBounds - the bounds to which to fit on.
      aBoundsReference - the reference of the given bounds, null if it's the view's world reference.
      Returns:
      a fit animation
      Throws:
      TLcdOutOfBoundsException - when fitting on the given bounds isn't possible, for instance when the bounds aren't visible in the current projection.

    • animatedFitOnModelBounds

      public ILcdAnimation animatedFitOnModelBounds(ILcdBounds aBounds, ILcdModelReference aBoundsReference) throws TLcdOutOfBoundsException
      Returns an animation that fits the view on the specified bounds.

      This fit animation updates the ALspViewXYZWorldTransformation so that the specified bounds fit entirely in the given view. This method will both move the view and change the scale, but will keep the current rotation or pitch (in 3D).

      If the auto start property is true, the animation is started before the method returns, and already running navigation animations are cancelled.

      Parameters:
      aBounds - the bounds to which to fit on.
      aBoundsReference - the reference of the given bounds, null if it's the view's world reference.
      Returns:
      a fit animation
      Throws:
      TLcdOutOfBoundsException - when fitting on the given bounds isn't possible, for instance when the bounds aren't visible in the current projection.

    • animatedFit

      public ILcdAnimation animatedFit(Collection<ILspLayer> aLayers) throws TLcdNoBoundsException, TLcdOutOfBoundsException
      Returns an animation that fits the view on the specified layers.

      This fit animation updates the ALspViewXYZWorldTransformation so that the specified layers fit entirely in the given view. This method will both move the view and change the scale, but will keep the current rotation or pitch (in 3D).

      If the auto start property is true, the animation is started before the method returns, and already running navigation animations are cancelled.

      Parameters:
      aLayers - the layers to fit on.
      Returns:
      a fit animation
      Throws:
      TLcdNoBoundsException - when no bounds could be calculated based on the passed layers, for instance if all layers are empty.
      TLcdOutOfBoundsException - when fitting on the layer bounds isn't possible, for instance when the bounds aren't visible in the current projection.

    • fit

      public void fit(ILspLayer... aLayers) throws TLcdNoBoundsException, TLcdOutOfBoundsException
      Fits the view on the specified layers.

      This fit action updates the ALspViewXYZWorldTransformation so that the specified layers fit entirely in the given view. This method will both move the view and change the scale, but will keep the current rotation or pitch (in 3D).

      This method cancels already running view navigation animations.

      Parameters:
      aLayers - the layers on which to fit
      Throws:
      TLcdNoBoundsException - when no bounds could be calculated based on the passed layers, for instance if all layers are empty.
      TLcdOutOfBoundsException - when fitting on the layer bounds isn't possible, for instance when the bounds aren't visible in the current projection.

    • fit

      public void fit(Collection<ILspLayer> aLayers) throws TLcdNoBoundsException, TLcdOutOfBoundsException
      Fits the view on the specified layers.

      This fit action updates the ALspViewXYZWorldTransformation so that the specified layers fit entirely in the given view. It will both move the view and change the scale, but will keep the current rotation or pitch (in 3D).

      This method cancels already running view navigation animations.

      Parameters:
      aLayers - the layers on which to fit
      Throws:
      TLcdNoBoundsException - when no bounds could be calculated based on the passed layers, for instance if all layers are empty.
      TLcdOutOfBoundsException - when fitting on the layer bounds isn't possible, for instance when the bounds aren't visible in the current projection.

    • fit

      public void fit(ILcdBounds aBounds, ILcdGeoReference aGeoReference) throws TLcdOutOfBoundsException
      Fits the view on the specified bounds.

      This fit action updates the ALspViewXYZWorldTransformation so that the specified bounds fits entirely in the given view. It will both move the view and change the scale, but will keep the current rotation or pitch (in 3D).

      This method cancels already running view navigation animations.

      Parameters:
      aBounds - the bounds to which the view will be fit
      aGeoReference - the reference of the bounds to which the view will be fit, null to specify the world reference.
      Throws:
      TLcdOutOfBoundsException - when fitting on the given bounds isn't possible, for instance when the bounds aren't visible in the current projection.

    • fitOnModelBounds

      public void fitOnModelBounds(ILcdBounds aBounds, ILcdModelReference aReference) throws TLcdOutOfBoundsException
      Fits the view on the specified bounds.

      This fit action updates the ALspViewXYZWorldTransformation so that the specified bounds fits entirely in the given view. This method will both move the view and change the scale, but will keep the current rotation or pitch (in 3D).

      This method cancels already running view navigation animations.

      Parameters:
      aBounds - the bounds to which the view will be fit
      aReference - the reference of the bounds to which the view will be fit, null to specify the world reference.
      Throws:
      TLcdOutOfBoundsException - when fitting on the given bounds isn't possible, for instance when the bounds aren't visible in the current projection.

    • center

      public void center(ILspLayer... aLayers) throws TLcdOutOfBoundsException, TLcdNoBoundsException
      Moves the view to the middle of data of the specified layers. This method does not zoom the view, so the scale will not be changed,

      This method cancels already running view navigation animations.

      Parameters:
      aLayers - the layers to center on
      Throws:
      TLcdNoBoundsException - when no bounds could be calculated based on the passed layers, for instance if all layers are empty.
      TLcdOutOfBoundsException - when centering on the layer bounds isn't possible, for instance when the bounds aren't visible in the current projection.

    • center

      public void center(ILcdBounds aBounds, ILcdGeoReference aGeoReference) throws TLcdOutOfBoundsException
      Moves the view to the middle of the specified bounds. This method does not zoom the view, so the scale will not be changed.

      This method cancels already running view navigation animations.

      Parameters:
      aBounds - the bounds to center on
      aGeoReference - the reference of the given bounds, or null if the bounds are in the view's world coordinates.
      Throws:
      TLcdOutOfBoundsException - when centering on the given bounds isn't possible, for instance when the bounds aren't visible in the current projection.

    • centerOnModelBounds

      public void centerOnModelBounds(ILcdBounds aBounds, ILcdModelReference aReference) throws TLcdOutOfBoundsException
      Moves the view to the middle of the specified bounds. This method does not zoom the view, so the scale will not be changed.

      This method cancels already running view navigation animations.

      Parameters:
      aBounds - the bounds to center on
      aReference - the reference of the given bounds, or null if the bounds are in the view's world coordinates.
      Throws:
      TLcdOutOfBoundsException - when centering on the given bounds isn't possible, for instance when the bounds aren't visible in the current projection.

    • animatedCenter

      public ILcdAnimation animatedCenter(ILspLayer... aLayers) throws TLcdOutOfBoundsException, TLcdNoBoundsException
      Starts an animation that moves the view to the middle of data of the specified layers. The animation may zoom out and in if needed, but the target scale is similar to the initial scale.

      If the auto start property is true, the animation is started before the method returns, and already running navigation animations are cancelled.

      Parameters:
      aLayers - the layers to center on
      Returns:
      a center animation
      Throws:
      TLcdNoBoundsException - when no bounds could be calculated based on the passed layers, for instance if all layers are empty.
      TLcdOutOfBoundsException - when centering on the layer bounds isn't possible, for instance when the bounds aren't visible in the current projection.

    • animatedCenter

      public ILcdAnimation animatedCenter(ILcdBounds aBounds, ILcdGeoReference aGeoReference) throws TLcdOutOfBoundsException
      Starts an animation that moves the view to the middle of the specified bounds. The animation may zoom out and in if needed, but the target scale is similar to the initial scale.

      If the auto start property is true, the animation is started before the method returns, and already running navigation animations are cancelled.

      Parameters:
      aBounds - the bounds to center on
      aGeoReference - the reference of the given bounds, or null if the bounds are in the view's world coordinates.
      Returns:
      a center animation
      Throws:
      TLcdOutOfBoundsException - when centering on the given bounds isn't possible, for instance when the bounds aren't visible in the current projection.

    • animatedCenterOnModelBounds

      public ILcdAnimation animatedCenterOnModelBounds(ILcdBounds aBounds, ILcdModelReference aReference) throws TLcdOutOfBoundsException
      Starts an animation that moves the view to the middle of the specified bounds. The animation may zoom out and in if needed, but the target scale is similar to the initial scale.

      If the auto start property is true, the animation is started before the method returns, and already running navigation animations are cancelled.

      Parameters:
      aBounds - the bounds to center on
      aReference - the reference of the given bounds, or null if the bounds are in the view's world coordinates.
      Returns:
      a center animation
      Throws:
      TLcdOutOfBoundsException - when centering on the given bounds isn't possible, for instance when the bounds aren't visible in the current projection.