ViewportParams.h

Go to the documentation of this file.

// SPDX-License-Identifier: LGPL-2.1-or-later
//
// SPDX-FileCopyrightText: 2007 Inge Wallin <ingwa@kde.org>
// SPDX-FileCopyrightText: 2008 Jens-Michael Hoffmann <jensmh@gmx.de>
//
 
#ifndef MARBLE_VIEWPORTPARAMS_H
#define MARBLE_VIEWPORTPARAMS_H
 
/** @file
 * This file contains the headers for ViewportParams.
 *
 * @author Inge Wallin  <inge@lysator.liu.se>
 */
 
#include <QSize>
 
#include "GeoDataCoordinates.h"
#include "MarbleGlobal.h"
#include "Quaternion.h"
#include "marble_export.h"
 
class QPolygonF;
class QPainterPath;
 
namespace Marble
{
 
class GeoDataLatLonAltBox;
class GeoDataLatLonBox;
class GeoDataLineString;
class AbstractProjection;
class ViewportParamsPrivate;
 
/**
 * @short A public class that controls what is visible in the viewport of a Marble map.
 *
 */
 
class MARBLE_EXPORT ViewportParams
{
public:
    ViewportParams();
    explicit ViewportParams(Projection projection, qreal centerLongitude = 0, qreal centerLatitude = 0, int radius = 2000, const QSize &size = QSize(100, 100));
    ~ViewportParams();
 
    // Getters and setters
    Projection projection() const;
    const AbstractProjection *currentProjection() const;
    void setProjection(Projection newProjection);
 
    int polarity() const;
 
    const GeoDataLatLonAltBox &viewLatLonAltBox() const;
 
    GeoDataLatLonAltBox latLonAltBox(const QRect &screenRect) const;
 
    // Calculates an educated guess for the average angle in radians covered per pixel.
    // Given a certain resolution it doesn't make much sense
    // - to display an object that covers an angle that is smaller than that.
    // - to display two points as distinct points if they are separated by a
    //   an angular distance that is smaller. Instead only one point should be shown.
    // So this method helps to filter out details.
    // It's somewhat related to https://en.wikipedia.org/wiki/Angular_resolution
 
    qreal angularResolution() const;
 
    // Determines whether a geographical feature is big enough so that it should
    // represent a single point on the screen already.
    // See angularResolution()
 
    bool resolves(const GeoDataLatLonBox &latLonBox, qreal pixel = 2.0) const;
 
    bool resolves(const GeoDataLatLonAltBox &latLonAltBox, qreal pixel = 2.0, qreal altitude = 10000.0) const;
 
    // Determines whether two points are located enough apart so that it makes
    // sense to display them as distinct points. If this is not the case
    // calculation and drawing of one point can be skipped as only a single
    // point will be displayed on the screen.
 
    bool resolves(const GeoDataCoordinates &coord1, const GeoDataCoordinates &coord2) const;
 
    int radius() const;
 
    /**
     * @brief Change the radius of the planet
     * @param radius Size of the planet radius in pixel. Non-positive values are ignored.
     */
    void setRadius(int radius);
 
    void centerOn(qreal lon, qreal lat);
    void setHeading(qreal heading);
 
    Quaternion planetAxis() const;
    const matrix &planetAxisMatrix() const;
 
    int width() const;
    int height() const;
    QSize size() const;
 
    void setWidth(int newWidth);
    void setHeight(int newHeight);
    void setSize(const QSize &newSize);
 
    qreal centerLongitude() const;
    qreal centerLatitude() const;
 
    /**
     * @brief Get the screen coordinates corresponding to geographical coordinates in the map.
     * @param lon    the lon coordinate of the requested pixel position in radians
     * @param lat    the lat coordinate of the requested pixel position in radians
     * @param x      the x coordinate of the pixel is returned through this parameter
     * @param y      the y coordinate of the pixel is returned through this parameter
     * @return @c true  if the geographical coordinates are visible on the screen
     *         @c false if the geographical coordinates are not visible on the screen
     *
     * @see ViewportParams
     */
    bool screenCoordinates(const qreal lon, const qreal lat, qreal &x, qreal &y) const;
 
    /**
     * @brief Get the screen coordinates corresponding to geographical coordinates in the map.
     *
     * @param geopoint the point on earth, including altitude, that we want the coordinates for.
     * @param x      the x coordinate of the pixel is returned through this parameter
     * @param y      the y coordinate of the pixel is returned through this parameter
     * @param globeHidesPoint  whether the point gets hidden on the far side of the earth
     *
     * @return @c true  if the geographical coordinates are visible on the screen
     *         @c false if the geographical coordinates are not visible on the screen
     *
     * @see ViewportParams
     */
    bool screenCoordinates(const GeoDataCoordinates &geopoint, qreal &x, qreal &y, bool &globeHidesPoint) const;
 
    // Will just call the virtual version with a dummy globeHidesPoint.
    bool screenCoordinates(const GeoDataCoordinates &geopoint, qreal &x, qreal &y) const;
 
    /**
     * @brief Get the coordinates of screen points for geographical coordinates in the map.
     *
     * @param coordinates the point on earth, including altitude, that we want the coordinates for.
     * @param x      the x coordinates of the pixels are returned through this parameter
     * @param y      the y coordinate of the pixel is returned through this parameter
     * @param pointRepeatNum      the amount of times that a single geographical
                                  point gets represented on the map
     * @param size   the size of the point
     * @param globeHidesPoint  whether the point gets hidden on the far side of the earth
     *
     * @return @c true  if the geographical coordinates are visible on the screen
     *         @c false if the geographical coordinates are not visible on the screen
     *
     * @see ViewportParams
     */
    bool screenCoordinates(const GeoDataCoordinates &coordinates, qreal *x, qreal &y, int &pointRepeatNum, const QSizeF &size, bool &globeHidesPoint) const;
 
    bool screenCoordinates(const GeoDataLineString &lineString, QList<QPolygonF *> &polygons) const;
 
    /**
     * @brief Get the earth coordinates corresponding to a pixel in the map.
     * @param x      the x coordinate of the pixel
     * @param y      the y coordinate of the pixel
     * @param lon    the longitude angle is returned through this parameter
     * @param lat    the latitude angle is returned through this parameter
     * @param unit   the unit of the angles for lon and lat.
     * @return @c true  if the pixel (x, y) is within the globe
     *         @c false if the pixel (x, y) is outside the globe, i.e. in space.
     */
    bool geoCoordinates(const int x, const int y, qreal &lon, qreal &lat, GeoDataCoordinates::Unit unit = GeoDataCoordinates::Degree) const;
 
    qreal heading() const;
    bool mapCoversViewport() const;
 
    QPainterPath mapShape() const;
 
    QRegion mapRegion() const;
 
    /**
     * @return The current point of focus, e.g. the point that is not moved
     * when changing the zoom level. If not set, it defaults to the
     * center point.
     * @see centerCoordinates setFocusPoint resetFocusPoint
     */
    GeoDataCoordinates focusPoint() const;
 
    /**
     * @brief Change the point of focus, overridding any previously set focus point.
     * @param focusPoint New focus point
     * @see focusPoint resetFocusPoint
     */
    void setFocusPoint(const GeoDataCoordinates &focusPoint);
 
    /**
     * @brief Invalidate any focus point set with @ref setFocusPoint.
     * @see focusPoint setFocusPoint
     */
    void resetFocusPoint();
 
private:
    Q_DISABLE_COPY(ViewportParams)
    ViewportParamsPrivate *const d;
};
 
}
 
#endif