# Equirectangular projection
## Wiki2Reveal

This learning resource can be used as Wiki2Reveal slides in mathematics courses as introduction to projective geometry.
* Start Wiki2Reveal

## Introduction

In this learning resource the generation of an equirectangular projection is the objective. The learning resource is use-case driven, AFrame Example Durlach is the first use-case of equirectangular projection. Look around by dragging the direction of view with the mouse with left mouse button pressed.
Preview of the equirectangular projection in AFrame - Drag the preview of the equirectangular image with your mouse button pressed.

### Example of the equirectangular image

Preview the equirectangular JPG-image and explore the distortion of the image at the top and the bottom of the rectangular JPEG image.

### Navigation with multiple equirectangular images

The AFrame Navigation example from the river Rhine in Germany allows to jump from one location at the river rhine to another location at to the equirectangular preview.

## Subtopics

* Origin of terminology
* Maps and Distortion

## Use-Case

From a set of standard images of the camera covering a full the from center point of view. In general you cover 360 degree circle with rectangular standard images and you take image with camera for the sky and the floor (preferred without seeing the tripod that might be used for the other images). These set of images are aggregate in one equirectangular image representing a full spheric panorama image, that be be viewed e.g. in Aframe or other panoramic OpenSource viewes, that support equirectangular images.

### EQUI2SPH Projection

The underlying type of projection is an equirectangular projection EQUI2SPH, that is used e.g in geographical context, where a sphere is projected to rectangular plane on the map. First of all we explore the use-case in 3D Modelling about the spherical use of an spherical panorama image.

### IMG2EQUI Projection

The second transformation of this learning resource is the mapping of several image into a complete equirectangular projection IMG2EQUI and reverse from an equirectangular projection towards a rectangular preview as a standard image.

## Definition - Equirectangular Projection from Sphere

The following transformation refers to the spherical coordinates (latitude/longitude) to equirectangular projection:
* (SPH2EQUI) The forward projection transforms spherical coordinates into planar coordinates of the equirectangular projection.
* (EQUI2SPH) The reverse projection transforms equirectangular coordinates from the plane back onto the sphere. The formulae presume a spherical model

## Definition - Equirectangular Projection from Images

The following transformation is relevant for creating an equirectangular projection from several standard image from you camera.
* (IMG2EQUI) The forward projection transforms standard rectangular image from a camera into planar coordinates of the equirectangular projection.
* (EQUI2IMG) The reverse projection transforms equirectangular coordinates from the plane back into standard image.

### Spherical - Longitude and Latitude - SPH

* Longitude $\lambda \in [-180^{\circ },+180^{\circ }]$
* Latitude $\phi \in [-90^{\circ },+90^{\circ }]$

### Visualization

A perspective view of the Earth showing how latitude ($\phi$) and longitude ($\lambda$) are defined on a spherical model. The graticule spacing is 10 degrees.

#### Longitude - SPH

Longitude is given as an angular measurement referring to the 0° Greenich Meridian as the Prime Meridian and is ranging to $+180^{o}$ eastward and $-180^{o}$ westward. The Greek letter $\lambda$ (lambda) is used to denote the location of a place on Earth east or west of the Prime Meridian

#### Latitude - SPH

Latitude is given as an angular measurement referring to the 0° Equator and is ranging to $+90^{o}$ towards the North Pole and $-90^{o}$ towards the South Pole. The Greek letter $\phi$ or $\varphi$ (phi) denotes that angle.

#### Mnemonic - Greek Letter - Phi

There are two different notations of the greek letter $\phi$ and $\varphi$. In this learning resource the notation $\phi$ is used to indicate that it denotes the angle at circle that intersects with the North Pole and the South Pole.

### Definition of Spherical Variables

The projections are mathematical function/mappings. For definition of these projections the following variables are defined:
* $\lambda$ is the longitude of the location to project;
* $\phi$ is the latitude of the location to project;
* $\phi _{1}$ are the standard parallels (north and south of the equator) where the scale of the projection is true;
* $\phi _{0}$ is the central parallel of the map (e.g. $\phi _{0}=0^{\circ }$ equator);
* $\lambda _{0}$ is the central meridian of the map;
* $R$ is the radius of the globe.
Longitude and latitude variables are defined here in terms of radians.

### Definition of Equirectangular Planar Variables - EQUI

* $x_{e}$ is the horizontal coordinate of the projected location on the map;
* $y_{e}$ is the vertical coordinate of the projected location on the map;

### Forward Projection - Spherical to Planar - SPH2EQUI

${\begin{aligned}x&=R\cdot (\lambda -\lambda _{0})\cdot \cos(\phi _{1})\\y&=R\cdot (\phi -\phi _{0})\end{aligned}}$

### Special Case - Forward Projection

The plate carrée (French, for flat square), is the special case where $\varphi _{1}$ is zero. This projection maps x to be the value of the longitude and y to be the value of the latitude, and therefore is sometimes called the latitude/longitude or lat/lon(g) projection.
When the $\phi _{1}$ is not zero, such as Marinus's $\phi _{1}=36$, or Ronald Miller's $\phi _{1}=(37.5,43.5,50.5)$, the projection can portray particular latitudes of interest at true scale.

### Remarks - Ellipsoidal Model

While a projection with equally spaced parallels is possible for an ellipsoidal model, it would no longer be equidistant because the distance between parallels on an ellipsoid is not constant. More complex formulae can be used to create an equidistant map whose parallels reflect the true spacing.

### Reverse - Planar to Spherical - EQUI2SPH

${\begin{aligned}\lambda &={\frac {x}{R\cdot \cos(\phi _{1})}}+\lambda _{0}\\\phi &={\frac {y}{R}}+\phi _{0}\end{aligned}}$

### Alternative names

In spherical panorama viewers, usually:
* $\lambda$ is called "yaw";
* $\phi$ is called "pitch";
where both are defined in degrees.

## Learning Activities

The following learning activities address Projective Geometry from a standard snapshot taken with your camera onto an area on the sphere according to the equirectangular projection. Keep in mind to distinguish between the following projective converters:
* (SPH2EQUI / EQUI2SPH): (Latitude,Longitude) coordinates sphere $\Longleftrightarrow$ $(x_{e},y_{e})$ coordinates of an equirectangular image
* (SPH2IMG / IMG2SPH): $(x_{e},y_{e})$ equirectangular coordinates $\Longleftrightarrow$ $(x,y)$ coordinates standard image of your smartphone or camera.
* (EQUI2IMG / IMG2EQUI): (Latitude,Longitude) coordinates sphere $\Longleftrightarrow$ $(x,y)$ coordinates standard image of your smartphone or camera.

### Angle of View

For the learning activities it is important to understand the
* (HAV) Horizontal Angle of View in landscape format and
* (VAV) Vertical Angle of View in landscape format.

### Learning Task - Angle of View

The HAV and VAV differ from camera to camera. Explain why the HAV and VAV are relevant for the calculation of IMG2EQUI projection. Use the following figure to explain the requirements for projection.

### Visualization of Angle of View

The following figure depicts besides the Horizontal (HAV) and Vertical Angle of View (VAV) also the Diagonal Angle of View (DAV).

### Remark - IMG2EQUI Projection

The current projection type of the learning activities is the (IMG2EQUI) projection between the $(x,y)$ coordinates of a standard image and the distorted $(x_{e},y_{e})$ coordinates of an equirectangular image and vice verca.

### HAV and VAV as camera specifc properties

Due to the fact that different cameras have different angles of view (HAV and VAV) the visible area of the standard image (taken with your smartphone) might vary. The following animation shows different horizontal angles of view (HAV) e.g. for taking a snapshot vertically upwards towards the sky or blue ceiling.

## Polar Region - Distortion

The projection creates especially at the "North Pole" and the "South Pole" the heaviest distortion in comparison to distances measured on the surface of the sphere. For panoramic views the distortion is just a matter of storage of the spheric pixel information in a rectangular format. On the image of a market place you will see that the panoramic viewes transfer the rectangular images into a natural view where you can look around and explore the location from different angles and with multiple equirectangular images from many locations (see river Rhine example Cologne).

### IMG2EQUI Projection - Polar Regions

In this learning step we take pictures with a standard camera or smartphone and want to calculate the (Latitude,Longitude) coordinates of the sphere from (x,y) coordinates of standard image created with your smartphone or camera. In the first learning step we consider the sphere at the polar regions. These regions are the most distorted areas in the equirectangular projections.

### IMG2SPH Projection - Take Snapshots for Learning Task

* Take your mobile phone and take two snapshots vertical down and vertical up from your floor and from the ceiling. Select an position in your room where the top and the floor has some visible elements (e.g. a lamp, wooden decorative elements, ...). Alternatively you can create the two images outside with a cloudy sky and objects lying on the ground.
* select a center of a circle and a radius that fits into both images (maximize the radius of the circle,
* in this module we will project these two images to the polar regions of the sphere within the rectangular coordinate system of the image.

#### Initial State - Image Sky

The following image shows the initial state taking a picture from the sky. The camera is located in the center of the red sphere and takes an image of the blue sky or the ceiling in a room. The ceiling is visualized as a blue plane. The learning task is to calculate the angles for the corresponding point on the sphere.

#### Side view with polar image

The side view can be used to derive the calculation of the green angle with $\alpha :=\arctan(x)$. The relevant angle for the equirectangular projection of the polar region is marked red.

#### Trigonometric Functions

To use trigonometric functions it is required to identify the right-angled triangle. We denote the point $M_{P}:=(0,4)$. The polygon $\langle M,P_{2},M_{P}\rangle$ right-angled triangle. According to the definition of tangens, we get the following equation:
    $\tan(\alpha ):={\frac {|M_{P}P_{2}|}{|M_{P}M|}}$

#### Angle of View

The full angle of view is $2\cdot \alpha$. If the distance to the object $|M_{P}M|$ (e.g. a door) and the width of the door $|P_{1}P_{2}|$ are known, then the angle of view can be calculated in the following way:
    $2\cdot \alpha :=2\cdot \arctan \left({\frac {|M_{P}P_{2}|}{|M_{P}M|}}\right)=2\cdot \arctan \left({\frac {|P_{1}P_{2}|}{2\cdot |M_{P}M|}}\right)$

#### Used Part of Snapshot with a Camera

The first image is snapshot with a camera taking a picture vertically upwards to the ceiling (into the sky). The red circle is the projected area from the image (sky/ceiling) onto a part of the equirectangular image visualized in the next section of the learning resource. The following red circle in the rectangular source image will become a rectangle in the equirectangular projection.

#### Equirectangular Projection of Circle - Rectangle

Explain, why the circle in the source image of the polar region (North Pole) is a rectangle after projection in the equirectangular image.

#### Learning Task - Function for Coordinate Transformation IMG2EQUI

We denote by $P_{IMG}(x,y)$ the color information of a pixel in the source image (IMG) and with $P_{EQUI}(x_{e},y_{e})$ the color information of the pixel in the image in the destination format (EQUI). Define the function $P_{EQUI}(x_{e},y_{e})$ by calculating the corresponding $(x,y)$ coordinates in the IMG source image. This calculation is used to set pixels in the destination format EQUI by setting
    $P_{EQUI}(x_{e},y_{e}):=P_{IMG}(x,y).$
Remark: You need basic knowledge in trigonometry to perform this learning task.

#### Coordinate System of Graphics

The coordinate system of an image has a different orientation in y-axis. This is shown in the diagram.
* $x_{max}$ is the maximal value of the on the x-axis of the image
* $y_{max}$ is the maximal value of the on the y-axis the of the image
* The origin of the coordinate system is on the top left.
Keep this in mind, when you use the coordinate system for your experiments with projections (see also equirectangular projection.

#### Rectangular to Sphere - Projection

Now we use a the standard rectangular image on the right as in input for the equirectangular projection on the sphere and we view the image in panoramic preview on the sphere. What can be observed, if you analyze the projected area of red ceiling and a marked green rectangle on the floor.
* Drag the image upwards to the ceiling
* and downwards to floor.

#### Screenshots - Projection on Sphere of the standard Image

Screenshot of projection :
| Ceiling/Sky | Floor |

#### Learning Task - Projection of Sky in Graphics Coordinate System

Graphics have an own coordinate system to display points in pixel graphics or geometric objects like lines, polygons and circles in the coordinate system. The diagram shows the coordinate system of the image. Keep in mind that the coordinate of the y-axis has a different orientation than the y-axis in the standard 2D Cartesian coordinate system. This information is relevant if you experiment with equirectangular projections in Projective Geometry Playground.
Calculate the $y_{sky}$ for a specific angle of view of your camera.

#### Learning Task - Calculation

Calculate the equirectangular projection for any $(x,y)$ point in the red circle of the source image IMG into the destination format EQUI with:
* LibreOffice - HAV/VAV: Take image of a door and calculate the horizontal and vertical angle of view (HAV and VAV)
* LibreOffice - Coordinates: Create a Spreadsheet document for the calculation of coordinates from a given coordinate in the equirectangular image the corresponding coordinates in the source image of your camera.
* Javascript and HTML canvas - (see Projective Geometry Playground),
* Octave with image-package, or
* Python with Image Processing Library pillow by Jeffrey A. Clark
Select an implementation of your choice. LibreOffice has the minimal requirements on programming skill but only coordinate transformation can be performed without a visual output.

### Learning Task - Sky - North Pole

A sky image can be used to project a circular area in the source image to the rectangular part at the top of the generated equirectangular image.
Import the equirectangular projection in Aframe to preview the result.

#### Learning Task - Floor - South Pole

Transfer the lesson learned from north pole to the south pole and project the beach image as floor to the south pole.
* What are differences and similarities between both projections?

## Final Result

* Final Results would can be previewed in Aframe (see HuginSample Files on Github) or with the Wiki,
* Aldara Parks 360 Degree Image in Aframe with an already uploaded equirectangular image in WikiMedia Commons by U.Bardins
* PanoViewer 360 degree view of Aldara Parks image]