Manages information about a great circle path that extends from one point to another point, both or which are located on the surface of a unit sphere. More...

#include <GeoTessGreatCircle.h>

Public Member Functions
virtual	~GeoTessGreatCircle ()

	GeoTessGreatCircle ()

	GeoTessGreatCircle (const double *firstPoint, const double &distance, const double &direction)

	GeoTessGreatCircle (const double firstPoint, const double intermediatePoint, const double *lastPoint, const bool &shortestPath=true)

	GeoTessGreatCircle (const double firstPoint, const double lastPoint, const bool &shortestPath=true)

	GeoTessGreatCircle (GeoTessGreatCircle &other)

void	operator= (GeoTessGreatCircle &other)

bool	operator== (const GeoTessGreatCircle &other) const

void	set (double firstPoint, double intermediatePoint, double *lastPoint, const bool &shortestPath=true, const bool &deleteWhenDone=false)

void	set (double frstPoint, double lstPoint, const bool &shortestPath=true, const bool &deleteWhenDone=false)

void	set (double *firstPoint, const double &distance, const double &azimuth, const bool &deleteWhenDone=false)

double	getDistance ()

double	getDistanceDegrees ()

double	getDistance (const double *position)

double	getDistanceDegrees (const double *position)

double *	getFirst ()

double *	getLast ()

const double *	getNormal ()

double *	getPoint (const double &dist)

void	getPoint (const double &dist, double *location)

int	getNPoints (const double &spacing, const bool &onCenters=false)

double	getPoints (double **points, const int &npoints, const bool &onCenters=false)

double	getPoints (const double &spacing, double **points, int &npoints, const bool &onCenters=false)

bool	getIntersection (GeoTessGreatCircle &other, const bool &inRange, double *intersection)

double **	getTransform ()

void	transform (const double x, double v)

double *	transform (const double *x)

string	toString ()

Static Public Member Functions
static int	getNPoints (const double &dist, const double &spacing, const bool &onCenters=false)

Detailed Description

Manages information about a great circle path that extends from one point to another point, both or which are located on the surface of a unit sphere.

The GreatCircle class manages the information about a great circle path that extends from one point to another point, both or which are located on the surface of a unit sphere. It supports great circles where the distance from the firstPoint to the lastPoint are 0 to 2*PI radians apart, inclusive. Either or both of the points may coincide with one of the poles of the Earth.

There is a method to retrieve a point that is located on the great circle at some specified distance from the first point of the great circle.

The method getIntersection(other, inRange) will return a point that is located at the intersection of two great circles. In general, two great circles intersect at two points, and this method returns the one that is encountered first as one moves away from the first point of the first GreatCircle. If the Boolean argument inRange is true, then the method will only return a point if the point falls within the range of both great circles. In other words, the point of intersection has to reside in between the first and last point of both great circles. If inRange is false, then that constraint is not applied.

GreatCircle has the ability to transform the coordinates of an input point so that it resides in the plane of the great circle. This is useful for extracting slices from a 3D model for plotting purposes. The z-coordinate of the transformed point will point out of the plane of the great circle toward the observer. The y-coordinate of the transformed point will be equal to the normalized vector sum of the first and last point of the great circle and the x-coordinate will be y cross z.

The key to successfully defining a great circle path is successfully determining the unit vector that is normal to the plane of the great circle (firstPoint cross lastPoint, normalized to unit length). For great circles where the distance from firstPoint to lastPoint is more than zero and less than PI radians, this is straightforward. But for great circles longer than PI radians, great circles of exactly zero, PI or 2*PI radians length, or great circles where the first point resides on one of the poles, complications arise.

To determine the normal to the great circle, three constructors are provided (besides the default constructor that does nothing).

The first constructor is the most general. It takes four arguments: firstPoint (unit vector), intermediatePoint (unit vector), lastPoint (unit vector) and shortestPath (boolean). The normal is computed as firstPoint cross lastPoint normalized to unit length. If the distance from firstPoint to lastPoint is greater than zero and less than PI radians, then the resulting normal will have finite length and will have been successfully computed. If, however, the distance from firstPoint to lastPoint is exactly 0 or PI radians, then normal will have zero length. In this case, a second attempt to compute the normal is executed by computing firstPoint cross intermediatePoint. If this is successful, the calculation proceeds. If not successful, then the normal is computed as the first of: firstPoint cross Z, firstPoint cross Y or firstPoint cross X, whichever produces a finite length normal first. Z is the north pole, Y is (0N, 90E) and X is (0N, 0E). One of these calculations is guaranteed to produce a valid normal.

Once the normal has been computed, then the shortestPath argument is considered. If shortestPath is true, then no further action is taken, resulting in a great circle with length less than or equal to PI radians. If shortestPath is false then the normal is negated, effectively forcing the great circle to go the long way around the globe to get from firstPoint to lastPoint. When shortestPath is false the length of the great circle will be >= PI and <= 2*PI. For example, when shortestPath is true, a great circle path from (10N, 0E) to (30N, 0E) will proceed in a northerly direction for a distance of 20 degrees to get from firstPoint to lastPoint. But if shortestPath is false, the great circle will proceed in a southerly direction for 340 degrees to get from firstPoint to lastPoint.

The second constructor is a simplification of the first, taking only 3 arguments: firstPoint (unit vector), lastPoint (unit vector) and shortestPath (boolean). It calls the first constructor with intermediatePoint set to NULL. This is useful in cases where the calling application is certain that great circles of length exactly 0 or PI radians will not happen or is willing to accept an arbitrary path if it does happens.

There is a third constructor that takes 3 arguments: firstPoint (unit vector), distance (radians) and azimuth (radians). The lastPoint of the great circle is computed by moving the first point the specified distance in the specified direction. This constructor can produce great circles where the distance from firstPoint to lastPoint is >= 0 and <= 2*PI, inclusive. It can fail, however, if firstPoint coincides with either of the poles because the notion of azimuth from a pole in undetermined.

Memory management: The three parameterized constructors described above make copies of all of the unit vectors that are passed to them and delete the memory allocated for the copies when they are no longer needed. The calling application retains ownership of the variables passed to the constructors. There is an alternative strategy implemented by using the default GreatCircle constructor and then calling one of the 3 set() methods. The arguments of the set methods are the same as for the constructors, with one addition, and the calculation of the great circle parameters is identical. The difference is that the input unit vectors are not copied into internal variables but rather the input pointers are used directly by the GreatCircle object. Modification of these variables by the caller will have undesirable consequences for the GreatCircle object. The extra argument passed to the set() methods is deleteWhenDone (boolean). If true, then GreatCircle will delete the memory allocated for the unit vectors when it is done with them, otherwise it will not delete the memory and it is the responsibility of the caller to delete the memory after the lifetime of the GreatCircle object has expired.

Author: sballar

Definition at line 168 of file GeoTessGreatCircle.h.

Constructor & Destructor Documentation

◆ ~GeoTessGreatCircle()

virtual geotess::GeoTessGreatCircle::~GeoTessGreatCircle ( )

virtual

◆ GeoTessGreatCircle() [1/5]

geotess::GeoTessGreatCircle::GeoTessGreatCircle ( )

inline

Default constructor initializes everything to NULL.

Definition at line 235 of file GeoTessGreatCircle.h.

◆ GeoTessGreatCircle() [2/5]

geotess::GeoTessGreatCircle::GeoTessGreatCircle	(	const double *	firstPoint,
		const double &	distance,
		const double &	direction
	)

Constructor creates a great circle from firstPoint to another point located the specified distance and direction from the the first point.

GreatCircle makes a copy of first point for internal use. The copy is deleted in the destructor.

Parameters

firstPoint	unit vector.
distance	epicentral angular distance to lastPoint, in radians
direction	double direction to lastPoint, in radians

Exceptions

Exception if firstPoint is on one of the poles.

◆ GeoTessGreatCircle() [3/5]

geotess::GeoTessGreatCircle::GeoTessGreatCircle	(	const double *	firstPoint,
		const double *	intermediatePoint,
		const double *	lastPoint,
		const bool &	shortestPath = `true`
	)

Constructor that takes three unit vectors at the beginning, middle and end of the great circle path. Will not fail even when building GreatCircles that are 0, PI or 2PI radians long.

The key is to successfully compute a valid unit vector that is normal to the plane of the GreatCircle even when the firstPoint and lastPoint are 0 or PI radians apart. The following calculations are performed until normal is successfully computed, i.e., it has unit length.

normal = firstPoint X lastPoint, normalized to unit length
intermediatePoint != null and normal = firstPoint X intermediatePoint, normalized to unit length.
normal = firstPoint X [0., 0., 1.]
normal = firstPoint X [0., 1., 0.]
normal = firstPoint X [1., 0., 0.]

GreatCircle makes copies of the 3 unit vectors for internal use. The copies are deleted when they are no longer needed.

Parameters

firstPoint	unit vector of the origin of the great circle path.
intermediatePoint	unit vector of an intermediate point on the great circle path. If null, code will try the three cardinal directions (x, y, z).
lastPoint	unit vector the end of the great circle path.
shortestPath	if false, normal will be negated and distance from first to last will be >= PI.

◆ GeoTessGreatCircle() [4/5]

geotess::GeoTessGreatCircle::GeoTessGreatCircle	(	const double *	firstPoint,
		const double *	lastPoint,
		const bool &	shortestPath = `true`
	)

Constructor that takes just the two GeoVectors at the beginning and end of the great circle path. GreatCircle stores references to these arrays; no copies are made.

If firstPoint and lastPoint are 0 or PI radians apart, then the GreatCirlce will pass through one of the following lat,lon pairs: (90N, 0E), (0N, 90E), or (0N, 0E).

Parameters

firstPoint	unit vector the origin of the great circle path.
lastPoint	unit vector the end of the great circle path.
shortestPath	if false, direction from first to last is reversed and the distance from first to last will be greater than 180 degrees.

◆ GeoTessGreatCircle() [5/5]

geotess::GeoTessGreatCircle::GeoTessGreatCircle ( GeoTessGreatCircle & other )

Copy constructor.

Parameters

Member Function Documentation

◆ getDistance() [1/2]

double geotess::GeoTessGreatCircle::getDistance ( )

inline

Retrieve the angular distance from firstPoint to lastPoint, in radians.

Returns: double

Definition at line 419 of file GeoTessGreatCircle.h.

◆ getDistance() [2/2]

double geotess::GeoTessGreatCircle::getDistance ( const double * position )

inline

Retrieve the distance in radians measured from firstPoint to specified unit vector, measured in direction from firstPoint to lastPoint. Range is zero to 2*PI

Parameters

position an earth-centered unit vector

Returns: double

Exceptions

GreatCircleException

Definition at line 449 of file GeoTessGreatCircle.h.

◆ getDistanceDegrees() [1/2]

double geotess::GeoTessGreatCircle::getDistanceDegrees ( )

inline

Retrieve the angular distance from firstPoint to lastPoint, in degrees.

Returns: double

Definition at line 435 of file GeoTessGreatCircle.h.

◆ getDistanceDegrees() [2/2]

double geotess::GeoTessGreatCircle::getDistanceDegrees ( const double * position )

inline

Retrieve the distance in degrees measured from firstPoint to specified unit vector, measured in direction from firstPoint to lastPoint. Range is zero to 360.

Parameters

position an earth-centered unit vector

Returns: the distance in degrees measured from firstPoint to specified unit vector, measured in direction from firstPoint to lastPoint

Exceptions

GreatCircleException

Definition at line 470 of file GeoTessGreatCircle.h.

◆ getFirst()

double* geotess::GeoTessGreatCircle::getFirst ( )

inline

Retrieve a reference to the first unit vector on this GreatCircle.

Caller should not delete this array

Returns: unit vector

Definition at line 482 of file GeoTessGreatCircle.h.

◆ getIntersection()

bool geotess::GeoTessGreatCircle::getIntersection	(	GeoTessGreatCircle &	other,
		const bool &	inRange,
		double *	intersection
	)

inline

Retrieve the unit vector that lies at the intersection of this GreatCircle and another GreatCircle. There are, in general, two such intersections that are 180 degrees apart. This method returns the first one that is encountered when traveling from firstPoint in the direction of lastPoint. The other intersection can be retrieved by negating every element of the unit vector that is returned by this method.

If inRange is true then the point of intersection must reside between the firstPoint and the lastPoint of both this and other GreatCircles.

It is the responsibility of the caller to delete the array returned by this method.

Parameters

other	GreatCircle
inRange	if true then the point of intersection must reside between the firstPoint and the lastPoint of both this and other GreatCircles.
intersection	unit vector. returns NaN_DOUBLE if the this GreatCircle and other GreatCircle are coincident, i.e., their normals are equal. Also returns null if inRange is true and the point of intersection does not reside between firstPoint and lastPoint of both this and other GreatCircle.

Returns: true if successful, false otherwise.

Definition at line 681 of file GeoTessGreatCircle.h.

◆ getLast()

double* geotess::GeoTessGreatCircle::getLast ( )

inline

Retrieve a reference to the last unit vector on this GreatCircle.

Caller should not delete this array

Returns: unit vector

Definition at line 494 of file GeoTessGreatCircle.h.

◆ getNormal()

const double* geotess::GeoTessGreatCircle::getNormal ( )

inline

Retrieve a reference to the unit vector that is normal to the plane of this great circle (firstPoint cross lastPoint normalized to unit length). If firstPoint on left and lastPoint on right, normal points away from the observer.

Caller should not delete this array

Returns: double[]

Definition at line 508 of file GeoTessGreatCircle.h.

◆ getNPoints() [1/2]

static int geotess::GeoTessGreatCircle::getNPoints	(	const double &	dist,
		const double &	spacing,
		const bool &	onCenters = `false`
	)

inlinestatic

Return number of points required to span specified great circle distance with points that have spacing not to exceed specified value. If onCenters is true then points will reside in the centers of equal sized intervals. If onCenters is false (default), then first point coincides with start of great circle, last point coincides with end of great circle and other points are equally spaced in between. Actual spacing of points will generally be less than requested spacing so that integral number of equally spaced points will span the great circle.

Parameters

dist	length of great circle path in radians
spacing	maximum spacing between points in radians.
onCenters	if true, points in middle of intervals, other wise points at boundaries of intervals.

Definition at line 559 of file GeoTessGreatCircle.h.

◆ getNPoints() [2/2]

int geotess::GeoTessGreatCircle::getNPoints	(	const double &	spacing,
		const bool &	onCenters = `false`
	)

inline

Return number of points required to span this great circle with points that have spacing not to exceed specified value. If onCenters is true then points will reside in the centers of equal sized intervals. If onCenters is false (default), then first point coincides with start of great circle, last point coincides with end of great circle and other points are equally spaced in between. Actual spacing of points will generally be less than requested spacing so that integral number of equally spaced points will span the great circle.

Parameters

spacing	maximum spacing between points in radians.
onCenters	if true, points in middle of intervals, other wise points at boundaries of intervals.

Definition at line 578 of file GeoTessGreatCircle.h.

◆ getPoint() [1/2]

double* geotess::GeoTessGreatCircle::getPoint ( const double & dist )

inline

Retrieve a unit vector object located on the great circle path a specified distance from firstPoint.

It is the caller's responsibility to delete the returned array.

Parameters

dist	double the angular distance from firstPoint, in radians.

Returns: unit vector

Exceptions

GreatCircleException

Definition at line 524 of file GeoTessGreatCircle.h.

◆ getPoint() [2/2]

void geotess::GeoTessGreatCircle::getPoint	(	const double &	dist,
		double *	location
	)

inline

Retrieve a unit vector object located on the great circle path a specified distance from firstPoint.

Parameters

dist	double the angular distance from firstPoint, in radians.
location	(output) unit vector located on the great circle path a specified distance from firstPoint.

Definition at line 540 of file GeoTessGreatCircle.h.

◆ getPoints() [1/2]

double geotess::GeoTessGreatCircle::getPoints	(	const double &	spacing,
		double **	points,
		int &	npoints,
		const bool &	onCenters = `false`
	)

inline

Retrieve a bunch of unit vectors equally spaced along the great circle between initial and final points that define the great circle.

Supplied array of points must be large enough to hold the necessary number of points. Caller owns the unit vectors and should delete them when done with them. This method neither creates nor deletes any memory.

Parameters

spacing	the desired point spacing in radians. Actual spacing of points will generally be less than requested spacing so that integral number of equally spaced points will span the great circle.
points	an array of unit vectors that will be populated with equally spaced unit vectors along the great circle.
npoints	number of points along the great circle path
onCenters	if true, the points are located at the centers of path increments of equal size. If onCenters is false, the first point is located at the starting point of the great circle, the last point is located at the final point of the great circle and the remaining points are equally spaced in between.

Returns: actual spacing between the points in radians.

Definition at line 638 of file GeoTessGreatCircle.h.

◆ getPoints() [2/2]

double geotess::GeoTessGreatCircle::getPoints	(	double **	points,
		const int &	npoints,
		const bool &	onCenters = `false`
	)

inline

Retrieve a bunch of unit vectors equally spaced along the great circle between initial and final points that define the great circle.

Supplied array of points must be large enough to hold the specified number of points. Caller owns the unit vectors and should delete them when done with them. This method neither creates nor deletes any memory.

Parameters

points	an array of unit vectors that will be populated with equally spaced unit vectors along the great circle.
npoints	the number of points desired.
onCenters	if true, the points are located at the centers of path increments of equal size. If onCenters is false, the first point is located at the starting point of the great circle, the last point is located at the final point of the great circle and the remaining points are equally spaced in between.

Returns: actual spacing between the points in radians.

Definition at line 601 of file GeoTessGreatCircle.h.

◆ getTransform()

double** geotess::GeoTessGreatCircle::getTransform ( )

Retrieve a reference to the transform matrix owned by this GreatCircle. Transform is a 3 x 3 matrix such that when a vector is multiplied by transform, the vector will be projected onto the plane of this GreatCircle. The z direction will point out of the plane of the great circle in the direction of the observer (lastPoint cross firstPoint; parallel to normal). The y direction will correspond to the mean of firstPoint and lastPoint. The x direction will correspond to y cross z, forming a right handed coordinate system.

Caller should not delete this array

Returns: double**

◆ operator=()

void geotess::GeoTessGreatCircle::operator= ( GeoTessGreatCircle & other )

Equal operator.

Parameters

◆ operator==()

bool geotess::GeoTessGreatCircle::operator== ( const GeoTessGreatCircle & other ) const

inline

Return true if this and other are equal.

Parameters

other

Definition at line 320 of file GeoTessGreatCircle.h.

◆ set() [1/3]

void geotess::GeoTessGreatCircle::set	(	double *	firstPoint,
		const double &	distance,
		const double &	azimuth,
		const bool &	deleteWhenDone = `false`
	)

Set the components of this GreatCircle to specified values.

Memory: This method stores a reference to firstPoint, not a copy. If deleteWhenDone is true, then GreatCircle will delete this reference when it is done with it, otherwise it will not. The default is that GreatCircle will not delete the reference.

Parameters

firstPoint	unit vector.
distance	epicentral angular distance to lastPoint, in radians
azimuth	double direction to lastPoint, in radians
deleteWhenDone	if true, references to firstPoint, intermediatePoint and lastPoint will be deleted when no longer needed, otherwise not deleted. Default is false.

Exceptions

Exception if firstPoint is on one of the poles.

◆ set() [2/3]

void geotess::GeoTessGreatCircle::set	(	double *	firstPoint,
		double *	intermediatePoint,
		double *	lastPoint,
		const bool &	shortestPath = `true`,
		const bool &	deleteWhenDone = `false`
	)

Set the components of this GreatCircle to specified values.

The key is to successfully compute a valid unit vector that is normal to the plane of the GreatCircle even when the firstPoint and lastPoint are 0 or PI radians apart. The following calculations are performed until normal is successfully computed, i.e., it has unit length.

normal = firstPoint X lastPoint, normalized to unit length
intermediatePoint != null and normal = firstPoint X intermediatePoint, normalized to unit length.
normal = firstPoint X [0., 0., 1.]
normal = firstPoint X [0., 1., 0.]
normal = firstPoint X [1., 0., 0.]

Memory: This method stores references to firstPoint, intermediatePoint and lastPoint, not copies. If deleteWhenDone is true, then GreatCircle will delete these references when it is done with them, otherwise it will not. The default is that GreatCircle will not delete these variables.

Parameters

firstPoint	unit vector of the origin of the great circle path.
intermediatePoint	unit vector of an intermediate point on the great circle path. If null, code will try the three cardinal directions (x, y, z).
lastPoint	unit vector the end of the great circle path.
shortestPath	if false, normal will be negated and distance from first to last will be >= PI. Defaults to true.
deleteWhenDone	if true, references to firstPoint, intermediatePoint and lastPoint will be deleted when no longer needed, otherwise not deleted. Default is false.

◆ set() [3/3]

void geotess::GeoTessGreatCircle::set	(	double *	frstPoint,
		double *	lstPoint,
		const bool &	shortestPath = `true`,
		const bool &	deleteWhenDone = `false`
	)

inline

Set the components of this GreatCircle to specified values.

If firstPoint and lastPoint are 0 or PI radians apart, then the GreatCirlce will pass through one of the following lat,lon pairs: (90N, 0E), (0N, 90E), or (0N, 0E).

Memory: This method stores references to firstPoint and lastPoint, not copies. If deleteWhenDone is true, then GreatCircle will delete these references when it is done with them, otherwise it will not. The default is that GreatCircle will not delete these variables.

Parameters

frstPoint	unit vector of the origin of the great circle path.
lstPoint	unit vector the end of the great circle path.
shortestPath	if false, normal will be negated and distance from first to last will be >= PI. Defaults to true.
deleteWhenDone	if true, references to firstPoint, intermediatePoint and lastPoint will be deleted when no longer needed, otherwise not deleted. Default is false.

Definition at line 392 of file GeoTessGreatCircle.h.

◆ toString()

string geotess::GeoTessGreatCircle::toString ( )

◆ transform() [1/2]

double* geotess::GeoTessGreatCircle::transform ( const double * x )

inline

Project vector x onto the plane of this GreatCircle. Returns a 3 element vector g such that g[2] is the component of x that points out of the plane of the GreatCircle (toward the observer). g[1] is the component of x parallel to the mean of firstPoint and lastPoint, and g[0] is the remaining part of x. For an observer viewing the great circle from the normal direction (firstPoint on the left and lastPoint on the right), g[2] will be the component of x that points toward the observer, g[1] will be 'up' and g[0] will be 'to the right'. For plotting values on a great circle 'slice' through a model, g[0] will be the x-component, g[1] will be the y-component and g[2] should be ignored.

Caller must delete the array returned by this method.

Parameters

x	double[] the 3 element array containing the vector to be projected.

Returns: double[] the projection of x onto plane of this GreatCircle

Exceptions

GreatCircleException

Definition at line 775 of file GeoTessGreatCircle.h.

◆ transform() [2/2]

void geotess::GeoTessGreatCircle::transform	(	const double *	x,
		double *	v
	)

inline

Project vector x onto the plane of this GreatCircle. Returns a 3 element vector g such that g[2] is the component of x that points out of the plane of the GreatCircle (toward the observer). g[1] is the component of x parallel to the mean of firstPoint and lastPoint, and g[0] is the remaining part of x. For an observer viewing the great circle from the normal direction (firstPoint on the left and lastPoint on the right), g[2] will be the component of x that points toward the observer, g[1] will be 'up' and g[0] will be 'to the right'. For plotting values on a great circle 'slice' through a model, g[0] will be the x-component, g[1] will be the y-component and g[2] should be ignored.

Parameters

x	double[] the 3 element array containing the vector to be projected.
v	double[] the projection of x onto plane of this GreatCircle

Exceptions

GreatCircleException

Definition at line 742 of file GeoTessGreatCircle.h.

The documentation for this class was generated from the following file:

rstt/GeoTessCPP/include/GeoTessGreatCircle.h

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~GeoTessGreatCircle()

◆ GeoTessGreatCircle() [1/5]

◆ GeoTessGreatCircle() [2/5]

◆ GeoTessGreatCircle() [3/5]

◆ GeoTessGreatCircle() [4/5]

◆ GeoTessGreatCircle() [5/5]

Member Function Documentation

◆ getDistance() [1/2]

◆ getDistance() [2/2]

◆ getDistanceDegrees() [1/2]

◆ getDistanceDegrees() [2/2]

◆ getFirst()

◆ getIntersection()

◆ getLast()

◆ getNormal()

◆ getNPoints() [1/2]

◆ getNPoints() [2/2]

◆ getPoint() [1/2]

◆ getPoint() [2/2]

◆ getPoints() [1/2]

◆ getPoints() [2/2]

◆ getTransform()

◆ operator=()

◆ operator==()

◆ set() [1/3]

◆ set() [2/3]

◆ set() [3/3]

◆ toString()

◆ transform() [1/2]

◆ transform() [2/2]