WhirlyGlobeViewController

Objective-C

@interface WhirlyGlobeViewController : MaplyBaseViewController

Swift

class WhirlyGlobeViewController : MaplyBaseViewController

This view controller implements a 3D interactive globe.

This is the main entry point for displaying a globe. Create one of these, fill it with data and let your users mess around with it.

You can display a variety of features on the globe, including tiled base maps (MaplyQuadImageTilesLayer), vectors (MaplyVectorObject), shapes (MaplyShape), and others. Check out the add calls in the MaplyBaseViewController for details.

To get selection and tap callbacks, fill out the WhirlyGlobeViewControllerDelegate and assign the delegate.

Most of the functionality is shared with MaplyBaseViewController. Be sure to look in there first.

  • If set, keep north facing upward on the screen as the user moves around.

    Off by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool keepNorthUp;

    Swift

    var keepNorthUp: Bool { get set }

  • Turn the pan gesture recognizer on and off

    On by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool panGesture;

    Swift

    var panGesture: Bool { get set }

  • Turn the pinch (zoom) gesture recognizer on and off

    On by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool pinchGesture;

    Swift

    var pinchGesture: Bool { get set }

  • Turn the rotate globe functionality for pinch gesture gesture recognizer on and off

    On by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool zoomAroundPinch;

    Swift

    var zoomAroundPinch: Bool { get set }

  • Turn the rotate gesture recognizer on and off

    On by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool rotateGesture;

    Swift

    var rotateGesture: Bool { get set }

  • Turn the tilt gesture recognizer on and off

    Off by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool tiltGesture;

    Swift

    var tiltGesture: Bool { get set }

  • Turn the double tap to zoom gesture recognizer on and off

    On by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool doubleTapZoomGesture;

    Swift

    var doubleTapZoomGesture: Bool { get set }

  • Turn the 2 finger tap to zoom out gesture recognizer on and off

    On by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool twoFingerTapGesture;

    Swift

    var twoFingerTapGesture: Bool { get set }

  • Turn on the double tap and drag gesture to zoom in and out.

    On by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool doubleTapDragGesture;

    Swift

    var doubleTapDragGesture: Bool { get set }

  • If set, we use a modified pan gesture recognizer to play nice with the scroll view. For the UIScrollView object, set clipsToBounds, pagingEnabled, and delaysContentTouches to YES, and set scrollEnabled and canCancelContentTouches to NO. Add swipe gesture recognizers to the scroll view to control paging, and call requirePanGestureRecognizerToFailForGesture: for each.

    Off by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool inScrollView;

    Swift

    var inScrollView: Bool { get set }

  • If set, we’ll automatically move to wherever the user tapped.

    When on we’ll move the current location to wherever the user tapped if they tapped the globe. That’s true for selection as well. On by default.

    Declaration

    Objective-C

    @property (nonatomic) _Bool autoMoveToTap;

    Swift

    var autoMoveToTap: Bool { get set }

  • Delegate for the selection and tap events.

    Fill in the WhirlyGlobeViewControllerDelegate protocol, assign the object here and you’ll get selection and tap events.

    Declaration

    Objective-C

    @property (nonatomic, weak, nullable) NSObject<WhirlyGlobeViewControllerDelegate> *delegate;

    Swift

    weak var delegate: WhirlyGlobeViewControllerDelegate? { get set }

  • Current viewer height above terrain.

    This is the height from with the viewer is viewing the globe. Values range from minHeight to maxHeight. Smaller is closer. See getZoomLimitsMin:max: for values. The display units are based on a globe with a radius of 1.0.

    Declaration

    Objective-C

    @property (nonatomic) float height;

    Swift

    var height: Float { get set }

  • Tilt in radians. 0 is looking straight down (the default). PI/2 is looking toward the horizon.

    Declaration

    Objective-C

    @property (nonatomic) float tilt;

    Swift

    var tilt: Float { get set }

  • If set, the globe will be centered to this point on the screen.

    Declaration

    Objective-C

    @property (nonatomic) CGPoint globeCenter;

    Swift

    var globeCenter: CGPoint { get set }

  • The current rotation away from north.

    If keepNorthUp is set this is always 0.

    Declaration

    Objective-C

    @property (nonatomic) float heading;

    Swift

    var heading: Float { get set }

  • The current roll around the axis pointed out of the user’s nose.

    Declaration

    Objective-C

    @property (nonatomic) double roll;

    Swift

    var roll: Double { get set }

  • Returns the closest a viewer is allowed to get to the map surface.

    Declaration

    Objective-C

    - (float)getZoomLimitsMin;

    Swift

    func getZoomLimitsMin() -> Float

    Return Value

    FLT_MIN if there’s no pinchDelegate set

  • Returns the farthest away a viewer is allowed to get from the map surface

    Declaration

    Objective-C

    - (float)getZoomLimitsMax;

    Swift

    func getZoomLimitsMax() -> Float

    Return Value

    FLT_MIN if there’s no pinchDelegate set

  • Return the zoom limits for the globe.

    Declaration

    Objective-C

    - (void)getZoomLimitsMin:(float *_Nonnull)minHeight
                     max:(float *_Nonnull)maxHeight;

    Swift

    func getZoomLimitsMin(_ minHeight: UnsafeMutablePointer<Float>, max maxHeight: UnsafeMutablePointer<Float>)

    Parameters

    minHeight

    The closest a viewer is allowed to get to the globe surface.
    maxHeight

    The farthest away a viewer is allowed to get from the globe surface.

  • Set the zoom limits for the globe.

    Declaration

    Objective-C

    - (void)setZoomLimitsMin:(float)minHeight max:(float)maxHeight;

    Swift

    func setZoomLimitsMin(_ minHeight: Float, max maxHeight: Float)

    Parameters

    minHeight

    The closest a viewer is allowed to get to the globe surface.
    maxHeight

    The farthest away a viewer is allowed to get from the globe surface.

  • How much we zoom in or out by when the user double taps or two finger taps.

    This sets the factor we’ll use to zoom in by (e.g. *2.0) when the user double taps. It also sets how much we zoom out by when the user two finger taps. This will only have an effect if those gestures are active.

    Declaration

    Objective-C

    @property (nonatomic) float zoomTapFactor;

    Swift

    var zoomTapFactor: Float { get set }

  • How long we take to zoom in or out when the user double taps or two finger taps.

    This controls the duration of the zoom animation. You can set it to zero to avoid the animation entirely.

    Declaration

    Objective-C

    @property (nonatomic) float zoomTapAnimationDuration;

    Swift

    var zoomTapAnimationDuration: Float { get set }

  • Reset the far clipping plane.

    This is advanced functionality. Make sure you actually need to do this before you do it.

    The far clipping plane is usually set to something like 4.0.

    Declaration

    Objective-C

    - (void)setFarClipPlane:(double)farClipPlane;

    Swift

    func setFarClipPlane(_ farClipPlane: Double)

  • Set the simplified tilt mode. We’ll tilt toward the horizon as the user gets closer to the ground.

    This implements a simplified mode for tilting. As the user gets closer to the ground we tilt more toward the horizon.

    Declaration

    Objective-C

    - (void)setTiltMinHeight:(float)minHeight
               maxHeight:(float)maxHeight
                 minTilt:(float)minTilt
                 maxTilt:(float)maxTilt;

    Swift

    func setTiltMinHeight(_ minHeight: Float, maxHeight: Float, minTilt: Float, maxTilt: Float)

    Parameters

    minHeight

    The minimum height corresponding to minTilt.
    maxHeight

    The height at which to start interoplating tilt.
    minTilt

    The most tilt toward the horizon. Invoked when the user is at minHeight or below.
    maxTilt

    The tilt at the maximum height and over. The tilt will never be less than this, so typically 0.

  • Turn off the varying tilt set up by setTiltMinHeight:maxHeight:minTilt:maxTilt:

    Declaration

    Objective-C

    - (void)clearTiltHeight;

    Swift

    func clearTiltHeight()

  • Turn on autorotate to rotate by the given amount every second.

    This turns on an auto-rotate mode. The globe will start rotating after a delay by the given number of degrees per second. Very pleasant.

    Declaration

    Objective-C

    - (void)setAutoRotateInterval:(float)autoRotateInterval
                      degrees:(float)autoRotateDegrees;

    Swift

    func setAutoRotateInterval(_ autoRotateInterval: Float, degrees autoRotateDegrees: Float)

    Parameters

    autoRotateInterval

    Wait this number of seconds after user interaction to auto rotate.
    autoRotateDegrees

    Rotate this number of degrees (not radians) per second.

  • Animate to the given position over time.

    Declaration

    Objective-C

    - (void)animateToPosition:(MaplyCoordinate)newPos time:(NSTimeInterval)howLong;

    Swift

    func animate(toPosition newPos: MaplyCoordinate, time howLong: TimeInterval)

    Parameters

    newPos

    A coordinate in geographic (lon/lat radians)
    howLong

    A time interval in seconds.

  • Animate the given position to the screen position over time.

    This is similar to animateToPosition:time: except that it will attempt to match up the screen position and the geographic position. This is how you offset the location you’re looking at.

    If it’s impossible to move newPos to loc, then nothing happens.

    Declaration

    Objective-C

    - (_Bool)animateToPosition:(MaplyCoordinate)newPos
                  onScreen:(CGPoint)loc
                      time:(NSTimeInterval)howLong;

    Swift

    func animate(toPosition newPos: MaplyCoordinate, onScreen loc: CGPoint, time howLong: TimeInterval) -> Bool

    Parameters

    newPos

    The geographic position (lon/lat in radians) to move to.
    loc

    The location on the screen where we’d like it to go.
    howLong

    How long in seconds to take getting there.

  • Animate to the given position, heading and height over time.

    Declaration

    Objective-C

    - (_Bool)animateToPosition:(MaplyCoordinate)newPos
                    height:(float)newHeight
                   heading:(float)newHeading
                      time:(NSTimeInterval)howLong;

    Swift

    func animate(toPosition newPos: MaplyCoordinate, height newHeight: Float, heading newHeading: Float, time howLong: TimeInterval) -> Bool

    Parameters

    newPos

    A coordinate in geographic (lon/lat radians)
    newHeight

    New height to animate to.
    newHeading

    New heading to finish on.
    howLong

    A time interval in seconds.

  • Animate to the given position, heading and height over time.

    Declaration

    Objective-C

    - (_Bool)animateToPositionD:(MaplyCoordinateD)newPos
                     height:(double)newHeight
                    heading:(double)newHeading
                       time:(NSTimeInterval)howLong;

    Swift

    func animate(toPositionD newPos: MaplyCoordinateD, height newHeight: Double, heading newHeading: Double, time howLong: TimeInterval) -> Bool

    Parameters

    newPos

    A coordinate in geographic (lon/lat radians) (double precision)
    newHeight

    New height to animate to. (double)
    newHeading

    New heading to finish on. (double)
    howLong

    A time interval in seconds.

  • Animate to the given position, screen position, heading and height over time.

    If it’s impossible to move newPos to loc, then nothing happens.

    Declaration

    Objective-C

    - (_Bool)animateToPosition:(MaplyCoordinate)newPos
                  onScreen:(CGPoint)loc
                    height:(float)newHeight
                   heading:(float)newHeading
                      time:(NSTimeInterval)howLong;

    Swift

    func animate(toPosition newPos: MaplyCoordinate, onScreen loc: CGPoint, height newHeight: Float, heading newHeading: Float, time howLong: TimeInterval) -> Bool

    Parameters

    newPos

    A coordinate in geographic (lon/lat radians)
    loc

    The location on the screen where we’d like it to go.
    newHeight

    New height to animate to.
    newHeading

    New heading to finish on.
    howLong

    A time interval in seconds.

  • Animate with a delegate over time.

    Fill in the WhirlyGlobeViewControllerAnimationDelegate and you can control the visual view on a frame by frame basis. You’ll get called back at the appropriate time on the main thread over the time period.

    You’ll also be called one at the end of the animation to establish the final position.

    Declaration

    Objective-C

    - (void)animateWithDelegate:
            (NSObject<WhirlyGlobeViewControllerAnimationDelegate> *_Nonnull)
                animationDelegate
                       time:(NSTimeInterval)howLong;

    Swift

    func animate(with animationDelegate: WhirlyGlobeViewControllerAnimationDelegate, time howLong: TimeInterval)

    Parameters

    animationDelegate

    The objects that implements the WhirlyGlobeViewControllerAnimationDelegate protocol.
    howLong

    How long the animation will run from the present time.

  • Set the center of the screen to the given position immediately.

    Declaration

    Objective-C

    - (void)setPosition:(MaplyCoordinate)newPos;

    Swift

    func setPosition(_ newPos: MaplyCoordinate)

    Parameters

    newPos

    The geographic position (lon/lat in radians) to move to.

  • Set the center of the screen and the height offset immediately.

    Declaration

    Objective-C

    - (void)setPosition:(MaplyCoordinate)newPos height:(float)height;

    Swift

    func setPosition(_ newPos: MaplyCoordinate, height: Float)

    Parameters

    newPos

    The geographic position (lon/lat in radians) to move to.
    height

    Height the view point above the globe.

  • Returns the center of the screen in geographic (lon/lat in radians).

    Declaration

    Objective-C

    - (MaplyCoordinate)getPosition;

    Swift

    func getPosition() -> MaplyCoordinate

  • Returns the center of the screen in geographic (lon/lat in radians as doubles).

    Declaration

    Objective-C

    - (MaplyCoordinateD)getPositionD;

    Swift

    func getPositionD() -> MaplyCoordinateD

  • Returns the current view point’s height above the globe.

    Declaration

    Objective-C

    - (double)getHeight;

    Swift

    func getHeight() -> Double

  • Set the center of the screen and the height offset immediately.

    Set the center and height using double.s

    Declaration

    Objective-C

    - (void)setPositionD:(MaplyCoordinateD)newPos height:(double)height;

    Swift

    func setPositionD(_ newPos: MaplyCoordinateD, height: Double)

    Parameters

    newPos

    The geographic position (lon/lat in radians) to move to.
    height

    Height the view point above the globe.

  • Return the current center position and height.

    Declaration

    Objective-C

    - (void)getPosition:(MaplyCoordinate *_Nonnull)pos
             height:(float *_Nonnull)height;

    Swift

    func getPosition(_ pos: UnsafeMutablePointer<MaplyCoordinate>, height: UnsafeMutablePointer<Float>)

    Parameters

    pos

    The center of the screen in geographic (lon/lat in radians).
    height

    The current view point’s height above the globe.

  • Return the current center position and height in doubles.

    Declaration

    Objective-C

    - (void)getPositionD:(MaplyCoordinateD *_Nonnull)pos
              height:(double *_Nonnull)height;

    Swift

    func getPositionD(_ pos: UnsafeMutablePointer<MaplyCoordinateD>, height: UnsafeMutablePointer<Double>)

    Parameters

    pos

    The center of the screen in geographic (lon/lat in radians).
    height

    The current view point’s height above the globe.

  • Set the viewing state all at once

    This sets the position, tilt, height, screen position and heading all at once.

    Declaration

    Objective-C

    - (void)setViewState:
    (WhirlyGlobeViewControllerAnimationState *_Nonnull)viewState;

    Swift

    func setViewState(_ viewState: WhirlyGlobeViewControllerAnimationState)

  • Make a WhirlyGlobeViewControllerAnimationState object from the current view state.

    This returns the current view parameters in a single WhirlyGlobeViewControllerAnimationState.

    Declaration

    Objective-C

    - (nullable WhirlyGlobeViewControllerAnimationState *)getViewState;

    Swift

    func getViewState() -> WhirlyGlobeViewControllerAnimationState?

  • Return a view state looking at the given location.

    Creates a view state that looks at the given location, taking tilt and heading into account.

    Declaration

    Objective-C

    - (nullable WhirlyGlobeViewControllerAnimationState *)
    viewStateForLookAt:(MaplyCoordinate)coord
                  tilt:(float)tilt
               heading:(float)heading
              altitude:(float)alt
                 range:(float)range;

    Swift

    func viewStateForLook(at coord: MaplyCoordinate, tilt: Float, heading: Float, altitude alt: Float, range: Float) -> WhirlyGlobeViewControllerAnimationState?

    Parameters

    coord

    The location the user will be looking at.
    tilt

    Tilt off of vertical.
    heading

    Heading calculated from due north.
    alt

    Altitude of the point the user will be looking at (0, is a good value).
    range

    How far the user will be from the location they’re looking at.

    Return Value

    The view state encapsulating the user location. Will be nil if the parameters weren’t valid.

  • Apply viewing constraints to the given view state.

    This applies active viewing constraints, such as min and max height and calculated tilt, if it’s on to the given view state. This is particularly useful when controlled tilt is on.

    Declaration

    Objective-C

    - (void)applyConstraintsToViewState:
    (WhirlyGlobeViewControllerAnimationState *_Nonnull)viewState;

    Swift

    func applyConstraints(toViewState viewState: WhirlyGlobeViewControllerAnimationState)

  • Find a selectable object at or near the given location.

    This runs immediately and looks for a Maply object at the given location. It differs from the WhirlyGlobeViewControllerDelegate in that it doesn’t require user interaction.

    Declaration

    Objective-C

    - (nullable id)findObjectAtLocation:(CGPoint)screenPt;

    Swift

    func findObject(atLocation screenPt: CGPoint) -> Any?

    Parameters

    screenPt

    The location on screen where we’re looking for an object.

    Return Value

    Returns a Maply object such as MaplyScreenLabel or MaplyShape or nil if it failed to find anything.

  • Return a location on the screen for a given geographic coordinate or CGPointZero if it’s not on the screen.

    Declaration

    Objective-C

    - (CGPoint)screenPointFromGeo:(MaplyCoordinate)geoCoord;

    Swift

    func screenPoint(fromGeo geoCoord: MaplyCoordinate) -> CGPoint

    Parameters

    geoCoord

    Point on the earth in lat/lon radians you want a screen position for.

    Return Value

    the point or CGPointZero

  • Return a location on the screen for a given geographic coordinate or false if it’s not on the screen.

    Declaration

    Objective-C

    - (_Bool)screenPointFromGeo:(MaplyCoordinate)geoCoord
                   screenPt:(CGPoint *_Nonnull)screenPt;

    Swift

    func screenPoint(fromGeo geoCoord: MaplyCoordinate, screenPt: UnsafeMutablePointer<CGPoint>) -> Bool

    Parameters

    geoCoord

    Point on the earth in lat/lon radians you want a screen position for.
    screenPt

    Location on the screen.

    Return Value

    True if the geo coord was on the screen, false otherwise.

  • Calculate a geo coordinate from a point on the screen.

    Declaration

    Objective-C

    - (_Bool)geoPointFromScreen:(CGPoint)screenPt
                   geoCoord:(MaplyCoordinate *_Nonnull)geoCoord;

    Swift

    func geoPoint(fromScreen screenPt: CGPoint, geoCoord: UnsafeMutablePointer<MaplyCoordinate>) -> Bool

    Parameters

    screenPt

    Location on the screen.
    geoCoord

    Point on the earth in lat/lon radians.

    Return Value

    True if the point was on the globe, false otherwise.

  • Calculate a geocentric coordinate from a point on the screen.

    Declaration

    Objective-C

    - (nullable NSArray *)geocPointFromScreen:(CGPoint)screenPt;

    Swift

    func geocPoint(fromScreen screenPt: CGPoint) -> [Any]?

    Parameters

    screenPt

    Location on the screen.

    Return Value

    An array of 3 NSNumber (with doubles). If the point wasn’t on the globe, returns nil

  • Calculate a geocentric coordinate from a point on the screen.

    Declaration

    Objective-C

    - (_Bool)geocPointFromScreen:(CGPoint)screenPt
                   geocCoord:(double *_Nonnull)retCoords;

    Swift

    func geocPoint(fromScreen screenPt: CGPoint, geocCoord retCoords: UnsafeMutablePointer<Double>) -> Bool

    Parameters

    screenPt

    Location on the screen.
    retCoords

    An array of 3 doubles. The geocentric coordinate will be returned here.

    Return Value

    True if the point was on the globe, false otherwise.

  • Calculate a size in meters by projecting the two screen points onto the globe. Return -1, -1 if the points weren’t on the globe.

    Declaration

    Objective-C

    - (CGSize)realWorldSizeFromScreenPt0:(CGPoint)pt0 pt1:(CGPoint)pt1;

    Swift

    func realWorldSize(fromScreenPt0 pt0: CGPoint, pt1: CGPoint) -> CGSize

  • Find a height that shows the given bounding box.

    This method will search for a height that shows the given bounding box within the view. The search is inefficient, so don’t call this a lot.

    Declaration

    Objective-C

    - (float)findHeightToViewBounds:(MaplyBoundingBox)bbox pos:(MaplyCoordinate)pos;

    Swift

    func findHeight(toViewBounds bbox: MaplyBoundingBox, pos: MaplyCoordinate) -> Float

    Parameters

    bbox

    The bounding box (in radians) we’re trying to view.
    pos

    The position the viewer will be at.

  • Return the extents of the current view.

    When we’re dealing with a globe the corners could be outside of the globe, in this case kMaplyNullBoundingBox is returned.

    Declaration

    Objective-C

    - (MaplyBoundingBox)getCurrentExtents;

    Swift

    func getCurrentExtents() -> MaplyBoundingBox

    Return Value

    Returns the bounding box if exists a bounding bbox for the current view, otherwise returns kMaplyNullBoundingBox.

  • Return the extents of the current view.

    When we’re dealing with a globe the corners could be outside of the globe, in this case false is returned.

    Declaration

    Objective-C

    - (_Bool)getCurrentExtents:(MaplyBoundingBox *_Nonnull)bbox;

    Swift

    func getCurrentExtents(_ bbox: UnsafeMutablePointer<MaplyBoundingBox>) -> Bool

    Parameters

    bbox

    The bbox will be returned here.

    Return Value

    Returns true if exists a bounding bbox for the current view, otherwise returns false

  • From the current view figure out a usable geo bounding box.

    This is similar to the WhirlyGlobeViewControllerDelegate methods and getCurrentExtents except that it goes a little deeper. It starts with the four corners of the screen and then tries to take tilt and orientation into account. Ideally it produces a bounding box that covers everything the user is looking at as opposed to where the four corners are.

    Declaration

    Objective-C

    - (int)getUsableGeoBoundsForView:(MaplyBoundingBox *_Nonnull)bboxes
                          visual:(_Bool)visualBoxes;

    Swift

    func getUsableGeoBounds(forView bboxes: UnsafeMutablePointer<MaplyBoundingBox>, visual visualBoxes: Bool) -> Int32

    Parameters

    bboxes

    The bounding boxes to fill in. Pass in two.
    visualBoxes

    If set, we’ll build bounding boxes you can display. If not set, we’ll build a single bounding box usable for math.

  • Make a gesture recognizer’s success depend on the pan gesture recognizer’s failure.

    When using the globe view within a scroll view, add swipe gesture recognizers to the scroll view to control paging, and call this method for each. See also the inScrollView property and its comment.

    Declaration

    Objective-C

    - (void)requirePanGestureRecognizerToFailForGesture:(id)other;

    Swift

    func requirePanGestureRecognizerToFail(forGesture other: Any!)

    Parameters

    other

    The other, subordinate gesture recognizer.