rapid-sdk
    Preparing search index...

    Class Viewport

    Viewport is a class for managing the state of the viewer and converting between Lon/Lat [λ,φ] and Cartesian [x,y] coordinates

    Original geographic coordinate data is in WGS84 (Lon,Lat) and "projected" into screen space [x,y] using the Web Mercator projection see: https://en.wikipedia.org/wiki/Web_Mercator_projection

    Some nomenclature on the coordinates that this code uses:

    • "WGS84 coordinates" - These are Lon/Lat [λ,φ]
    • "world coordinates" - These are Mercator projected into Cartesian [x,y] and pre-scaled to WORLD_ZOOM
      • origin puts [0,0] at top left of world and [WORLD_SIZE, WORLD_SIZE] (256 × 2^WORLD_ZOOM) at bottom right.
      • pre-scaling to z=WORLD_ZOOM means geometry projected once can be rendered at any zoom without recalculating.
    • "screen coordinates" - These are the Cartesian coordinates with view transform applied
      • origin puts [0,0] at top left of screen and they are in pixels

    The parameters of this projection are stored in _transform

    • x,y - translation, (from origin coordinate [0,0], to top-left screen coordinate)
    • z - zoom (the scale factor is 2^z)
    • r - rotation, optionally applied post-projection to change the map bearing away from north-up

    The viewport (what a user can see) is defined by: A rectangular Extent A-B-C-D (stored in _dimensions), representing the user's screen. By default, the origin of the screen space is top-left coordinate 'A' [0,0]. When a rotation is applied, the visible extent extends to E-F-G-H and top-left coordinate 'E'.

          |  E__
          |r/   ''--..__
          |/           r''--..__
    [0,0] A═══════════════════════D__
         /║                       ║  ''H         N
        /r║                       ║   /      W._/
       /  ║           +           ║  /         /'-E
      /   ║                       ║r/         S
     F__  ║                       ║/
        ''B═══════════════════════C [w,h]
             ''--..__r           /|
                     ''--..__   /r|
                             ''G  |
    Index

    Constructors

    constructor

    Accessors

    dimensions transform v

    Methods

    center centerLoc project screenToWorld unproject visibleDimensions visibleExtent visiblePolygon visibleWorldExtent wgs84ToWorld worldToScreen worldToWgs84

    Constructors

    • Constructs a new Viewport

      Parameters

      Returns Viewport

      Default viewport corresponds to the world at zoom 1 with origin at "Null Island" [0, 0].

      const view1 = new Viewport();
      const view2 = new Viewport({ x: 20, y: 30, z: 2 });

    Accessors

    • get dimensions(): Vec2

      Returns Vec2

    • set dimensions(val: Vec2): void

      Sets/Gets the screen dimensions

      Parameters

      • val: Vec2

        viewport dimensions

      Returns void

      When argument is provided, sets the viewport max dimensions and returns this for method chaining. Returns the viewport max dimensions otherwise

      const v = new Viewport();
      v.dimensions = [800, 600];  // sets dimensions
      v.dimensions;               // gets dimensions, returns [800, 600]
    • get transform(): Transform

      Returns Transform

    • set transform(val: Partial<TransformProps>): void

      Sets/Gets a transform object

      Parameters

      • val: Partial<TransformProps>

        a Transform-like object containing the new Transform properties

      Returns void

      When argument is provided, sets x,y,z,r from the Transform and returns this for method chaining. Returns a Transform object containing the current x,y,z,r values otherwise

      const t = { x: 20, y: 30, z: 1, r: Math.PI / 2 };
      const v = new Viewport();
      v.transform = t;    // sets transform `x`,`y`,`z`,`r` from given Object
      v.transform;        // gets transform
    • get v(): number

      version

      Returns number

    • set v(val: number): void

      Parameters

      • val: number

      Returns void

    Methods

    • Returns the screen center coordinate in [x, y]

      Returns Vec2

      viewport screen center coordinate in [x, y]

      const v = new Viewport()
      v.dimensions = [800, 600];
      v.center();   // returns [400, 300]

    • Returns the screen center coordinate in [lon, lat]

      Returns Vec2

      viewport screen center coordinate in [lon, lat]

      const v = new Viewport();
      v.dimensions = [800, 600]
      v.transform = { x: 400, y: 300 };
      v.centerLoc();   // returns [0, 0]  ("Null Island")

    • Projects a coordinate from Lon/Lat [λ,φ] to Cartesian [x,y]

      Parameters

      • loc: Vec2

        Lon/Lat [λ,φ]

      • OptionalincludeRotation: boolean

        if true, consider rotation when working with the screen coordinate

      Returns Vec2

      Cartesian [x,y]

      const v = new Viewport();
      v.project([0, 0]);                  // returns [0, 0]
      v.project([180, -85.0511287798]);   // returns [256, 256]
      v.project([-180, 85.0511287798]);   // returns [-256, -256]

    • Converts from screen coordinate to world coordinate applying view transform

      Parameters

      • screen: Vec2

        the screen coordinate [x,y]

      • OptionalincludeRotation: boolean

        if true, consider rotation when working with the screen coordinate

      Returns Vec2

      The world coordinate [x,y]

    • Unprojects a coordinate from given Cartesian [x,y] to Lon/Lat [λ,φ]

      Parameters

      • point: Vec2

        Cartesian [x,y]

      • OptionalincludeRotation: boolean

        if true, consider rotation when working with the screen coordinate

      Returns Vec2

      Lon/Lat [λ,φ]

      const v = new Viewport();
      v.unproject([0, 0]);         // returns [0, 0]
      v.unproject([256, 256]);     // returns [180, -85.0511287798]
      v.unproject([-256, -256]);   // returns [-180, 85.0511287798]

    • Returns the viewport's visible polygon (wound counterclockwise) (in "screen" coordinates) We construct a rotated rectangle that contains the original screen rectangle. The rotated rectangle has the same center point as the original screen rectangle. see https://math.stackexchange.com/questions/1628657/dimensions-of-a-rectangle-containing-a-rotated-rectangle The first coordinate in the rotated rectangle is the rotated origin (E)

            |  E__
            |r/   ''--..__
            |/           r''--..__
      [0,0] A═══════════════════════D__
           /║                       ║  ''H         N
          /r║                       ║   /      W._/
         /  ║           +           ║  /         /'-E
        /   ║                       ║r/         S
       F__  ║                       ║/
          ''B═══════════════════════C [w,h]
               ''--..__r           /|
                       ''--..__   /r|
                               ''G  |

      Returns Quad

    • Converts from world coordinate to screen coordinate applying view transform

      Parameters

      • world: Vec2

        the world coordinate [x,y]

      • OptionalincludeRotation: boolean

        if true, consider rotation when working with the screen coordinate

      Returns Vec2

      The screen coordinate [x,y]

    Settings

    Member Visibility

    On This Page

    Constructors
    Accessors
    Methods