public class Camera extends Object implements AutoCloseable
map reference
to view coordinates (device independent pixel coordinates).
In layman's terms: just like with television, the camera's position, orientation (and other parameters like the projection) determines what is shown on screen.
Note that the Camera
API is a low-level API. For simple map navigation use cases, it's recommended to use the higher-level API. The MapNavigator
API works in both 2D and 3D, on all map references. If you use the low-level Camera
API, keep in mind that the same camera manipulation implementation might not work for other types of cameras (OrthographicCamera
vs PerspectiveCamera
) or other (types of) map references (projected vs. geocentric).
This is a base class shared by both PerspectiveCamera
and OrthographicCamera
. It describes the position, orientation and viewport of the camera, as well as provide functions to transform between 3D map
and view (device independent pixel coordinates on the camera's viewport) points.
The camera's position, orientation and viewport are described by the following parameters:
eye
point: the 3D position that the camera is looking from, in map coordinates
forward
vector: the 3D direction the camera is looking in, in map coordinates. The combination of the forward and up vector determines the orientation of the camera, in map space.
up
vector: the 3D direction that indicates the up direction of the camera, in map coordinates. The combination of the forward and up vector determines the orientation of the camera, in map space.
near plane
distance: the distance from the eye to the near clipping plane. Points that fall outside of the near/far interval are clipped.
far plane
distance: the distance from the eye to the far clipping plane. Points that fall outside of the near/far interval are clipped.
width
in device independent pixels of the camera's viewport. This is the same as the Map width
.
height
in device independent pixels of the camera's viewport. This is the same as the Map height
.
In practice, you only work with PerspectiveCamera
and OrthographicCamera
. Besides the camera position, orientation and viewport, these subclasses also define a projection (orthographic vs. perspective).
Unlike Map.ViewMapTransformation
, the coordinate conversion
methods
do not take into account the content on the screen. The camera's methods are nothing more than low-level mathematical functions. In most cases, it is advised to convert coordinate from view to map and vice versa using Map.ViewMapTransformation
.
See also related article.
OrthographicCamera
,
PerspectiveCamera
Modifier and Type | Class and Description |
---|---|
static class |
Camera.Look
Structure describing the position and orientation of the camera.
|
static class |
Camera.Look2D
Structure describing the position of the camera for an orthographic top-down view.
|
static class |
Camera.LookAt
Structure to
orient a camera based on a specific target point. |
static class |
Camera.LookFrom
Structure describing the position and orientation of the camera.
|
Modifier and Type | Method and Description |
---|---|
void |
close() |
protected void |
finalize() |
Coordinate |
getEye()
Returns the current location of the camera in
map coordinates . |
double |
getFar()
Returns the distance from the eye to the far clipping plane.
|
Coordinate |
getForward()
Returns the (normalized) direction corresponding to the forward direction of the view.
|
double |
getHeight()
Returns the height in device independent pixels of the viewport of this camera.
|
double |
getNear()
Returns the distance from the eye to the near clipping plane.
|
Coordinate |
getUp()
Returns the (normalized) direction corresponding to the upward direction of the view.
|
double |
getWidth()
Returns the width in device independent pixels of the viewport of this camera.
|
Coordinate |
mapToView(Coordinate mapPoint)
Transforms a point in
map coordinates to view coordinates. |
Coordinate |
viewToMap(Coordinate viewPoint)
Transforms a view point to
map coordinates . |
public void close()
close
in interface AutoCloseable
@NotNull public Coordinate getEye()
map coordinates
.map coordinates
.@NotNull public Coordinate getForward()
It is defined in the map reference
.
@NotNull public Coordinate getUp()
It is defined in the map reference
.
public double getNear()
Points that fall outside of the near/far interval are clipped.
public double getFar()
Points that fall outside of the near/far interval are clipped.
public double getWidth()
public double getHeight()
@NotNull public Coordinate viewToMap(@NotNull Coordinate viewPoint)
map coordinates
.
When the camera is a perspective camera, the z-value of the view point is used to determine the depth of the Map
point:
near plane
near plane
and the far plane
far plane
.
ViewMapTransformation
to convert a view location to a map point on the terrain or a visible surface.viewPoint
- A view point, in device independent pixels. (0, 0) is defined in the top-left corner of the screen.map reference
.@NotNull public Coordinate mapToView(@NotNull Coordinate mapPoint)
map coordinates
to view coordinates.
For perspective cameras, the resulting view coordinate will contain a z-coordinate. This allows to transform the resulting view point back to the original point.
ViewMapTransformation
to convert a location in map coordinates to view coordinates.mapPoint
- A point, defined in the reference of the Map
.