Turf: New module proposal: Transform

[stebogit]

Inspired by PR #729 and the necessity to use a rotated gridPoint as turf-isobands input, I'd like to implement the following basic transformation functions, if of interest in Turf:

@turf/transform-translate

• [x] Moves a feature of distance kilometers (or units) on a specific direction angle
• [x] 3rd (z) coordinates support

/**
@param {GeoJSON}` **object** to be translated
@param {Number}` **distance** length of the motion
@param {Number}` **direction** angle/bearing of the motion, in degrees from North (positive clockwise)
@param {String}` **units** (optional, default Km) unit for distance
@returns {Feature<any>}` the translated Feature

@turf/transform-scale

• [x] Enlarges or shrinks a feature by a scale factor.
• [x] 3rd (z) coordinates support

/**
@param {GeoJSON}` **object** to be scaled
@param {Number}` **factor** scale factor (positive number)
@param {Feature|Geometry<Point>|Array<number>}` **origin** point (of the Feature) around which the scaling will occur, defaults to centroid
@returns {Feature<any>}` the scaled Feature

@turf/transform-rotate

• [x] Rotates a feature of angle degrees around a fixed point (default to its center/center of mass/centroid)
• [x] 3rd (z) coordinates support (rotation only by z axis, i.e. on the x,y plane)

/**
@param {GeoJSON}` **object** to be rotated
@param {Number}` **angle** extent of the rotation, in degrees from North (positive clockwise)
@param {Feature|Geometry<Point>|Array<number>}` **pivot**, point around which the rotation will occur, defaults to `centroid`
@returns {Feature<any>}` the rotated Feature

Geometry Support

• Geometry|Feature<Point> => Feature<Point>
• Geometry|Feature<LineString> => Feature<LineString>
• Geometry|Feature<Polygon> => Feature<Polygon>
• Geometry|Feature<MultiPoint> => Feature<MultiPoint>
• Geometry|Feature<MultiLineString> => Feature<MultiLineString>
• Geometry|Feature<MultiPolygon> => Feature<MultiPolygon>

[DenisCarriere]

Love it!! Big +1 👍 for me

[DenisCarriere]

I believe all these modules should support all geometries.

[stebogit]

Should @turf/transform-rotate default to the feature center, center of mass, or centroid?
Don't know exactly the difference, or better their main/typical use

[DenisCarriere]

One tricky thing to consider for @turf/transform-rotate on MultiPoint.

[stebogit]

Well, if no rotation point was given, a MultiPoint should have its own center/center of mass/centroid, right? The rotation then should not be different for any shape/feature.
We'll see though

[DenisCarriere]

@turf/transform-rotate default to the feature center, center of mass, or centroid?

Good question, not too sure which one would be best for this, maybe having a pivot parameter => Geometry|Feature<Point>|Array<number> that you can provide your own point to do the rotation on, if the pivot param is not supplied then it defaults to centroid or center-of-mass (not sure which one would be the most appropriate).

[stebogit]

Same for @turf/transform-scale: should it transform the feature growing/shrinking from the center or from the bottom-left corner, for instance? I'd say the center, and again here we should decide center, center of mass, or centroid.

[DenisCarriere]

I think by default it should use @turf/centroid (opinion me) but allow the user to provide their own pivot point.

Maybe @morganherlocker or @mourner can weigh in on the center, center of mass, or centroid topic.

[morganherlocker]

Love this proposal. One very minor suggestion is that we put all of these in a "Translation" category, and make the names translate, scale, and rotate. destination probably belongs in the category as well (maybe superseded by translate, although we would want to guarantee no serious perf regressions, because destination is used in many hot loops).

Good question, not too sure which one would be best for this, maybe having a pivot parameter => Geometry|Feature|Array that you can provide your own point to do the rotation on, if the pivot param is not supplied then it defaults to centroid or center-of-mass (not sure which one would be the most appropriate).

User supplied pivot point is a great idea. If we provide a default, it should be the fastest, most neutral one. In my opinion, this is centroid.

[stebogit]

all of these in a "Translation" category

@morganherlocker do you mean like a single module?
And, just to clarify, why naming it "Translation" instead of maybe "Transformation"? After all those are all linear transformations.

destination probably belongs in the category as well

Even though the concept is quite similar, often I guess even the same output, I believe destinationhas a specific meaning (rout) and follows geodesics or great circle lines, while these transformations apply plane geometry, i.e. I guess they would be suitable for relatively small regions (small enough to ignore Earth's curvature)

[morganherlocker]

@morganherlocker do you mean like a single module?

Turf has high level categories that each module falls into. ie: http://turfjs.org/docs/#transformation

Each of these proposed modules would be individual modules belonging to a single category.

And, just to clarify, why naming it "Translation" instead of maybe "Transformation"? After all those are all linear transformations.

Agree. Putting these in the existing Transformation category makes sense.

Even though the concept is quite similar, often I guess even the same output, I believe destinationhas a specific meaning (rout) and follows geodesics or great circle lines, while these transformations apply plane geometry, i.e. I guess they would be suitable for relatively small regions (small enough to ignore Earth's curvature)

👍

[dpmcmlxxvi]

A few thoughts:

• Is it just 2D?
  
  
  
  • Inputs could be 3D. Spec discourages any more than 3 dimensions.
  
  
  • I suspect rotation is probably most common in 2D lat/lon plane.
  
  
  • I could see scale and translate commonly being applied to z-direction.
  
  
• Might want to apply different scale in different dimensions.
• Will these be three separate functions or a single RST function?
  
  
  
  • If it's a singe function may want to give some thought on a simple API to let users apply the transforms in different orders.
  
  
• I think origin may be more common term than pivot but others may disagree.

[stebogit]

@dpmcmlxxvi the implementation in 3D would not be an issue at all I think. I wonder however if that third dimension would be actually "appropriate" to Turf, which "speaks GeoJSON".

From the specs I'd say we're talking about 0 to 2D space:

GeoJSON comprises the seven concrete geometry types defined in the
OpenGIS Simple Features Implementation Specification for SQL [SFSQL]:
0-dimensional Point and MultiPoint; 1-dimensional curve LineString
and MultiLineString; 2-dimensional surface Polygon and MultiPolygon;

and also:

The coordinate reference system for all GeoJSON coordinates is a
geographic coordinate reference system, using the World Geodetic
System 1984 (WGS 84) datum, with longitude and latitude units
of decimal degrees. This is equivalent to the coordinate reference
system identified by the Open Geospatial Consortium (OGC) URN
urn:ogc:def:crs:OGC::CRS84. An OPTIONAL third-position element SHALL
be the height in meters above or below the WGS 84 reference
ellipsoid. In the absence of elevation values, applications
sensitive to height or depth SHOULD interpret positions as being at
local ground or sea level.

Apply different scale in different dimensions is definitely a useful option 👍

In my understanding of the module setup I'd say a single module per function would be consistent with the library format.

I vote for pivot 😄

[dpmcmlxxvi]

@stebogit The dimensionality of the geometries is not the same as the dimensionality of the space in which they are embedded. A 0-dimensional point can represent a 1D, 2D, or 3D coordinate. Same goes for a line and polygon.

Also, agreed that height is optional in the spec. Though, since this is a new module and the implementation would be starting from scratch I think it would be helpful to keep the full spec in mind, even if not all the bells and whistles are implemented in the first draft.

[stebogit]

The dimensionality of the geometries is not the same as the dimensionality of the space in which they are embedded.

Very true! I was thinking about the actual representation of the geometries on a (2D) map.

Again, I'm all in for 3 coordinates support! 🌐 🌎

[DenisCarriere]

My 👍 votes for the following:

• 3 coordinates support (on initial draft don't worry about it too much, as long as the 3rd coordinate isn't dropped)
• having 3 separate modules for this proposal (initial names defined by @stebogit, @turf/transform-rotate, @turf/transform-translate, @turf/transform-scale)
• pivot param name for @turf/transform-rotate
• origin param for `@turf/transform-scale

[stebogit]

@DenisCarriere @dpmcmlxxvi I'm working on the scale module and I was wondering if instead of origin required to be part of the feature, which would involve a quite complex validation (or is there a simple way?), why don't we give the user just two options:

• origin = centroid (default?):
  

• origin = the most south-west point of a bbox containing the feature:
  

I believe both are "natural" ways of picturing a scaling, like one would do with any drawing software when enlarging/shrinking an object (i.e. like I did to create these images).
Also, how convenient/useful would actually be defining the origin as a point of the feature?
What do you think?

[DenisCarriere]

👍 Love the diagrams! We should try to post these somewhere

[DenisCarriere]

Woot 🎉 https://github.com/Turfjs/turf/pull/759