Coordinate systems
Almost every MapCore call takes or returns a position, and getting the frame wrong is the most common source of results that look plausible and are not. There are three frames, plus a fourth that replaces the first in one specific case.
The conventions
They are stated on IMcMapViewport itself, whose description is included here in full rather than
paraphrased, so that this page cannot drift away from the contract:
Interface for a map viewport.
A viewport is one rendered view of the world, drawn into a window (an HTMLCanvasElement in the JavaScript API) or, as a non-window viewport, into buffers the application reads back. It owns its cameras, holds the terrains added to it and decides which of their layers and which overlays are visible in it, so several viewports can show the same terrain differently. A viewport is created by Create() on a device (see IMcMapDevice) and released with IMcBase::Release(). It inherits IMcMapCamera, IMcSpatialQueries, IMcGlobalMap, IMcPrintMap and IMcImageProcessing, so their methods are called on the viewport itself.
All positions, direction vectors, boxes and planes are expressed in the world coordinate system: the x and y axes form the horizontal plane and z is the height. World units are meters for metric coordinate systems; for geographic coordinate systems, x and y are in units of 1/100000 of a degree of longitude and latitude respectively, and z is in meters.
Screen coordinates are in pixels, originating at the viewport's top-left corner with y growing downward; window coordinates are in pixels relative to the window's top-left corner (see IMcMapViewport::WindowPixelToViewportPixel()).
In an anchored-image map (see IMcMapCamera::EMT_2D) along with its camera model (IMcMapViewport::SCreateData::pImageCalc), the camera's position, look-at, visible-area and screen-conversion methods work in image coordinates instead of world coordinates: pixels of the image, originating at its bottom-left corner with y growing upward.
All angles are plain degrees. Yaw is measured from the world +y axis (north) and increases clockwise (like an azimuth); pitch 0 is horizontal and -90 looks straight down; roll increases clockwise when looking along the camera's forward direction (the world +y axis at zero yaw and pitch). The three angles are applied in the order roll, pitch, yaw; a 2D camera uses yaw only.
Used for:
- The view itself: Create() and GetCreateParams(); the window handle, size and position in the window (ViewportResized(), SetRelativePositionInWindow(), SetTopMostZOrderInWindow()), the physical pixel size, full-screen mode, and stereo rendering (SetStereoMode()).
- Cameras: CreateCamera(), DestroyCamera(), SetActiveCamera(), GetActiveCamera() and GetCameras(), with ICameraUpdateCallback reporting active-camera changes.
- Content: AddTerrain() / RemoveTerrain() and each terrain's tile-request limits, tile cache and draw priority; the grid (SetGrid()), height lines (SetHeightLines()) and DTM visualization (SetDtmVisualization()); the background color and per-stage brightness (SetBrightness()).
- Rendering: Render() and RenderAll() to the window; RenderPFrameToBuffer(), RenderScreenRectToBuffer() and the rolling-shutter variants to buffers; HasPendingUpdates() and PerformPendingUpdates() for applications that redraw only when needed; render statistics, clip planes, terrain noise and shadow modes, material schemes and post-processes (AddPostProcess()).
- Objects: visibility scale limits, movement threshold, spatial-partition cache and screen-size factor, objects delay and visualization freeze, visibility options per overlay and per object, one-bit alpha and transparency ordering.
- Coordinate conversions: between the viewport and its overlay manager, another viewport or an image calc, and WindowPixelToViewportPixel() between window and viewport pixels.
- Navigating, as IMcMapCamera: every camera method - position, orientation, zoom, visible area, attachment and the screen/world conversions - forwarded to the active camera.
- Querying the terrain, as IMcSpatialQueries: heights, intersections, lines and areas of sight and the other spatial queries over the viewport's terrains, as displayed.
- Serving as a global map, as IMcGlobalMap: registering local map viewports and drawing their footprints (on a 2D viewport created with an overlay manager).
- Printing, as IMcPrintMap: the screen or a world rectangle, to a printer or to raw raster data.
- Image processing, as IMcImageProcessing: filters, color tables and histogram operations on a raster layer or on the whole image.
See also: IMcMapDevice, IMcMapCamera, IMcSpatialQueries, IMcMapTerrain, IMcHeatMapViewport, IMcSectionMapViewport
— from Map/IMcMapViewport.h
Which frame does an API use?
The rule of thumb: the camera works in world coordinates, the viewport works in pixels, and
anything named Screen takes or returns pixels regardless of which interface it hangs off.
| Frame | Origin and direction | Units |
|---|---|---|
| World | x/y horizontal plane, z up | Metres in a metric coordinate system. In a geographic coordinate system, x and y are 1/100000 of a degree of longitude and latitude, z is still metres |
| Screen | Viewport's top-left corner, y downward | Pixels |
| Window | Window's top-left corner | Pixels |
| Image | Image's bottom-left corner, y upward | Original image pixels |
Two of those are easy to conflate. Screen and window coordinates differ whenever the viewport is
not flush with the window's top-left corner, and the only correct way between them is
IMcMapViewport::WindowPixelToViewportPixel(), which also reports whether the point fell inside
the viewport at all. Subtracting an offset you tracked yourself will drift the moment the layout
changes.
The 1/100000-degree unit for geographic coordinate systems is not a scaling factor you may choose.
It is the unit world values are expressed in, so a longitude of 34.78° is 3478000, and a distance
of "one unit" in x is not the same ground distance as one unit in y anywhere except the equator.
Anchored-image maps
An anchored-image map — "oriented imagery" — is the exception that catches people. When the map
type is IMcMapCamera::EMT_2D and the viewport was created with a camera model in
IMcMapViewport::SCreateData::pImageCalc, the camera's position, look-at, visible-area and
screen-conversion methods stop working in world coordinates and work in image coordinates
instead: pixels of the original image, measured from its bottom-left corner with y growing upward.
Two consequences worth stating plainly:
- The y axis points the opposite way from screen coordinates. A value that round-trips successfully through a conversion may still be upside down relative to what you expected.
IMcMapCamera::ScreenToWorldOnTerrain()performs no terrain intersection in this mode. It is a coordinate conversion, not a query, so an "intersection found" result says nothing about the terrain.
Angles
All angles are plain degrees — no radians anywhere in the public API.
| Angle | Zero | Increases |
|---|---|---|
| Yaw | World +y axis (north) | Clockwise, like an azimuth |
| Pitch | Horizontal | Negative looks down; -90 is straight down |
| Roll | Level | Clockwise when looking along the camera's forward direction |
The three are applied in the order roll, pitch, yaw. A 2D camera uses yaw only, so setting pitch or roll on one changes nothing and reports no error.
Converting between frames
| From | To | Call |
|---|---|---|
| World | Screen | IMcMapCamera::WorldToScreen() |
| Screen | World, on the terrain | IMcMapCamera::ScreenToWorldOnTerrain() |
| Screen | World, on a given plane | IMcMapCamera::ScreenToWorldOnPlane() |
| Window | Screen | IMcMapViewport::WindowPixelToViewportPixel() |
| World | Section offset | IMcSectionMapViewport::WorldToSection() |
Three behaviours in these calls are worth knowing before you rely on a result:
WorldToScreen() has no "off-screen" answer. The z component of the result carries the
post-projection normalised depth, and a point behind the camera is mirrored around the screen
centre with no indication that it happened. A returned coordinate inside the viewport rectangle is
therefore not proof the point is visible — test the depth, or test containment yourself.
ScreenToWorldOnTerrain() is a spatial query, with the timing rules of one. It is synchronous
only at the default query precision, which is the levels of detail currently shown in the viewport.
Any other precision must be asynchronous when the viewport has layers fetching tiles straight from
a server, and asking for the wrong combination is rejected with
IMcErrors::ASYNC_QUERY_WITH_CURRENT_LOD or IMcErrors::SYNC_QUERY_WITH_NON_CURRENT_LOD rather
than silently degrading. With purely local layers an asynchronous query still completes
synchronously — the callback fires before the call returns, and the call itself returns no
results, which surprises code that reads its output parameters afterwards.
A missed intersection is reported differently in 2D and 3D. In 2D, if nothing is hit,
the output point is still filled in from a horizontal-plane intersection with z set to
MC_NO_DTM_VALUE (-1000). In every other no-intersection case the output is left untouched, so a
caller that does not check the "found" flag reads whatever was in the variable before the call.
Related
- Rendering and cameras — camera models and the render loop.
- Architecture — how the device, viewports and layers relate.