work on spec

Author: birkskyum

build/generate-docs.ts

@@ -166,7 +166,7 @@ function typeToMarkdownLink(type: string): string {
         case 'promoteid':
             return ` [${type}](types.md)`;
         case 'color':
-        case 'projectiontype':
+        case 'projectiontransition':
         case 'number':
         case 'string':
         case 'boolean':

build/generate-style-spec.ts

@@ -126,7 +126,7 @@ export type ColorSpecification = string;
 
 export type PrimitiveProjection = 'mercator' | 'globe';
 export type ProjectionTransition = [PrimitiveProjection, PrimitiveProjection, number];
-export type ProjectionTypeSpecification = PrimitiveProjection | ProjectionTransition | PropertyValueSpecification<ProjectionTransition>
+export type ProjectionTransitionSpecification = PrimitiveProjection | ProjectionTransition | PropertyValueSpecification<ProjectionTransition>
 
 
 export type PaddingSpecification = number | number[];

docs/types.md

@@ -134,26 +134,37 @@ The following example applies 2em padding on top and bottom and 3em padding left
 }
 ```
 
-## ProjectionType
 
-The `projectionType` type is used to define the projection of the map.
+
+## ProjectionTransition
+
+The `projectionTransition` is used to configure which projection to use for the map.
 
 There are currently two projections implemented.
 
 - `mercator` - Web Mercator projection
+- `stereographic` - Stereographic sphere projection
+
+And the following [presets](#use-a-projection-preset)
+
 - `globe` - Globe projection
 
-This value can be uses either with a single projection or as an intermediate between two.
+The `projectionTransition` output sent to the renderer is always of the shape:
 
-It's possible to use an expression to change projection between zoom levels using a [`camera expression`](./expressions.md#camera-expressions), either with an immediate [`step`](./expressions.md#step), or an animated [`interpolate-projection`](./expressions.md#interpolate-projection).
+`[from, to, transition]: [string, string, number]`
 
-**Use a single projection**
+- `from` is the transition of lower zoom level
+- `to` is the transition of higher zoom level
+- `transition` is the interpolation value, going from 0 to 1, with 0 being in the `from` projection, and 1 being in the `to` projection.
 
-```ts
-type: "mercator"
-```
+In case `from` and `to` are equal, the `transition` will have no effect.
+
+### Examples
+
+#### Step between projection at discrete zoom levels
+
+Use a [`camera expression`](./expressions.md#camera-expressions), to discretely [`step`](./expressions.md#step) between projections at certain zoom levels.
 
-**Change projection at zoom level**
 
 ```ts
 type: ["step", ["zoom"],
@@ -162,18 +173,50 @@ type: ["step", ["zoom"],
 ]
 ```
 
-**Animate between different projections based on zoom level**
+`output at zoom 10.9: ["globe", "globe", 1]`
+`output at zoom 11.0: ["globe", "globe", 1]`
+`output at zoom 11.1: ["mercator", "mercator", 1]`
+
+#### Animate between different projections based on zoom level**
+
+Use a [`camera expression`](./expressions.md#camera-expressions), to animate between projections based on zoom, using [`interpolate-projection`](./expressions.md#interpolate-projection) function. The example below will yield an adaptive globe that transitions from `stereographic` to `mercator` between zoom 10 and 12.
 
 ```ts
 type: ["interpolate-projection", ["linear"], ["zoom"],
-    0,"globe",
-    10,"globe",
+    0,"stereographic",
+    10,"stereographic",
     12,"mercator"
 ]
 ```
 
-**Use a projection transition intermediate**
+`output at zoom 10: ["stereographic", "stereographic", 1]`
+`output at zoom 11: ["stereographic", "mercator", 0.5]`
+`output at zoom 12: ["mercator", "mercator", 1]`
+
+#### Provide a constant `projection` transition
 
 ```ts
-type: ["globe", "mercator", 0.7]
+type: ["stereographic", "mercator", 0.7]
 ```
+
+#### Use a projection preset
+
+For all supported projections, providing just name will convert into the projection transition syntax for convenience:
+
+
+```ts
+type: "mercator"
+```
+
+Is equivalent to:
+
+```ts
+["mercator", "mercator", 1]
+```
+
+There are also additional presets that yield commonly used expressions:
+
+
+| Preset | Full value | Description |
+|--------|------------|-------------|
+| `globe` | `["interpolate-projection", ["linear"], ["zoom"],`<br>`0, "stereographic", 10, "stereographic", 12, "mercator"]` | Adaptive globe: Transitions from stereographic to mercator projection between zoom levels 10 and 12. |

src/expression/definitions/interpolate.ts

@@ -1,7 +1,7 @@
 import UnitBezier from '@mapbox/unitbezier';
 
 import interpolate from '../../util/interpolate';
-import {array, ArrayType, ColorType, ProjectionTypeT, ColorTypeT, NumberType, NumberTypeT, PaddingType, PaddingTypeT, VariableAnchorOffsetCollectionType, VariableAnchorOffsetCollectionTypeT, toString, verifyType, ProjectionType} from '../types';
+import {array, ArrayType, ColorType, ProjectionTransitionT, ColorTypeT, NumberType, NumberTypeT, PaddingType, PaddingTypeT, VariableAnchorOffsetCollectionType, VariableAnchorOffsetCollectionTypeT, toString, verifyType, ProjectionTransition} from '../types';
 import {findStopLessThanOrEqualTo} from '../stops';
 
 import type {Stops} from '../stops';
@@ -19,7 +19,7 @@ export type InterpolationType = {
     name: 'cubic-bezier';
     controlPoints: [number, number, number, number];
 };
-type InterpolatedValueType = NumberTypeT | ColorTypeT | ProjectionTypeT | PaddingTypeT | VariableAnchorOffsetCollectionTypeT | ArrayType<NumberTypeT>;
+type InterpolatedValueType = NumberTypeT | ColorTypeT | ProjectionTransitionT | PaddingTypeT | VariableAnchorOffsetCollectionTypeT | ArrayType<NumberTypeT>;
 type InterpolationOperator = 'interpolate' | 'interpolate-hcl' | 'interpolate-lab' | 'interpolate-projection';
 class Interpolate implements Expression {
     type: InterpolatedValueType;
@@ -109,7 +109,7 @@ class Interpolate implements Expression {
         if (operator === 'interpolate-hcl' || operator === 'interpolate-lab') {
             outputType = ColorType;
         } else if (operator === 'interpolate-projection') {
-            outputType = ProjectionType;
+            outputType = ProjectionTransition;
         } else if (context.expectedType && context.expectedType.kind !== 'value') {
             outputType = context.expectedType;
         }
@@ -137,7 +137,7 @@ class Interpolate implements Expression {
 
         if (!verifyType(outputType, NumberType) &&
             !verifyType(outputType, ColorType) &&
-            !verifyType(outputType, ProjectionType) &&
+            !verifyType(outputType, ProjectionTransition) &&
             !verifyType(outputType, PaddingType) &&
             !verifyType(outputType, VariableAnchorOffsetCollectionType) &&
             !verifyType(outputType, array(NumberType))

src/expression/types.ts

@@ -13,7 +13,7 @@ export type BooleanTypeT = {
 export type ColorTypeT = {
     kind: 'color';
 };
-export type ProjectionTypeT = {
+export type ProjectionTransitionT = {
     kind: 'projection';
 };
 export type ObjectTypeT = {
@@ -43,7 +43,7 @@ export type VariableAnchorOffsetCollectionTypeT = {
 
 export type EvaluationKind = 'constant' | 'source' | 'camera' | 'composite';
 
-export type Type = NullTypeT | NumberTypeT | StringTypeT | BooleanTypeT | ColorTypeT | ProjectionTypeT | ObjectTypeT | ValueTypeT |
+export type Type = NullTypeT | NumberTypeT | StringTypeT | BooleanTypeT | ColorTypeT | ProjectionTransitionT | ObjectTypeT | ValueTypeT |
 ArrayType | ErrorTypeT | CollatorTypeT | FormattedTypeT | PaddingTypeT | ResolvedImageTypeT | VariableAnchorOffsetCollectionTypeT;
 
 export interface ArrayType<T extends Type = Type> {
@@ -59,7 +59,7 @@ export const NumberType = {kind: 'number'} as NumberTypeT;
 export const StringType = {kind: 'string'} as StringTypeT;
 export const BooleanType = {kind: 'boolean'} as BooleanTypeT;
 export const ColorType = {kind: 'color'} as ColorTypeT;
-export const ProjectionType = {kind: 'projection'} as ProjectionTypeT;
+export const ProjectionTransition = {kind: 'projection'} as ProjectionTransitionT;
 export const ObjectType = {kind: 'object'} as ObjectTypeT;
 export const ValueType = {kind: 'value'} as ValueTypeT;
 export const ErrorType = {kind: 'error'} as ErrorTypeT;
@@ -94,7 +94,7 @@ const valueMemberTypes = [
     StringType,
     BooleanType,
     ColorType,
-    ProjectionType,
+    ProjectionTransition,
     FormattedType,
     ObjectType,
     array(ValueType),

src/expression/values.ts

@@ -5,7 +5,7 @@ import Formatted from './types/formatted';
 import Padding from '../util/padding';
 import VariableAnchorOffsetCollection from '../util/variable_anchor_offset_collection';
 import ResolvedImage from './types/resolved_image';
-import {NullType, NumberType, StringType, BooleanType, ColorType, ObjectType, ValueType, CollatorType, FormattedType, ResolvedImageType, array, PaddingType, VariableAnchorOffsetCollectionType, ProjectionType} from './types';
+import {NullType, NumberType, StringType, BooleanType, ColorType, ObjectType, ValueType, CollatorType, FormattedType, ResolvedImageType, array, PaddingType, VariableAnchorOffsetCollectionType, ProjectionTransition} from './types';
 
 import type {Type} from './types';
 import {Projection} from '../util/projection';
@@ -77,7 +77,7 @@ export function typeOf(value: Value): Type {
     } else if (value instanceof Color) {
         return ColorType;
     } else if (value instanceof Projection) {
-        return ProjectionType;
+        return ProjectionTransition;
     } else if (value instanceof Collator) {
         return CollatorType;
     } else if (value instanceof Formatted) {

src/index.test.ts

@@ -70,7 +70,7 @@ function validSchema(k, v, obj, ref, version, kind) {
         'padding',
         'variableAnchorOffsetCollection',
         'sprite',
-        'projectionType'
+        'projectionTransition'
     ]);
     const keys = [
         'default',

src/reference/v8.json

@@ -3065,7 +3065,7 @@
         }
       },
       "interpolate-projection": {
-        "doc": "Produces continuous, smooth results by interpolating between pairs of input and output values (\"stops\"). Works like `interpolate`, but the output type must be a projection transition of shape `[from, to, transition]: [string, string, number]`.",
+        "doc": "Produces continuous, smooth results by interpolating between pairs of input and output values (\"stops\"). Works like `interpolate`, but the output type must be a [`projection transition](./types.md#projection-transition).",
         "example": {
           "syntax": {
             "method": ["[\"linear\"] | [\"exponential\", base] | [\"cubic-bezier\", x1, y1, x2, y2]", "number", "string", "number", "..."],
@@ -4592,7 +4592,7 @@
   },
   "projection": {
     "type": {
-      "type": "projectionType",
+      "type": "projectionTransition",
       "doc": "The projection type. Can be specified as a string, or as an expression for supported projection types.",
       "default": "mercator",
       "expression": {

src/util/interpolate.ts

@@ -3,7 +3,7 @@ import Color from './color';
 import Padding from './padding';
 import VariableAnchorOffsetCollection from './variable_anchor_offset_collection';
 import RuntimeError from '../expression/runtime_error';
-import type {PrimitiveProjection, VariableAnchorOffsetCollectionSpecification} from '../types.g';
+import type {ProjectionPrimitive, VariableAnchorOffsetCollectionSpecification} from '../types.g';
 import {Projection} from './projection';
 
 export type InterpolationColorSpace = 'rgb' | 'hcl' | 'lab';
@@ -39,7 +39,7 @@ function number(from: number, to: number, t: number): number {
     return from + t * (to - from);
 }
 
-function projection(from: PrimitiveProjection, to: PrimitiveProjection, interpolation: number): Projection {
+function projection(from: ProjectionPrimitive, to: ProjectionPrimitive, interpolation: number): Projection {
     return new Projection(from, to, interpolation);
 }
 

src/util/projection.ts

@@ -1,10 +1,10 @@
-import {PrimitiveProjection, ProjectionTransition, ProjectionTypeSpecification, PropertyValueSpecification} from '../types.g';
+import {ProjectionPrimitive, ProjectionTransition, ProjectionTransitionSpecification, PropertyValueSpecification} from '../types.g';
 
 export class Projection {
-    readonly from: PrimitiveProjection;
-    readonly to: PrimitiveProjection;
+    readonly from: ProjectionPrimitive;
+    readonly to: ProjectionPrimitive;
     readonly transition: number;
-    constructor(from: PrimitiveProjection, to: PrimitiveProjection, transition: number){
+    constructor(from: ProjectionPrimitive, to: ProjectionPrimitive, transition: number){
         this.from = from;
         this.to = to;
         this.transition = transition;
@@ -15,8 +15,8 @@ export class Projection {
     }
 }
 
-export function isProjectionType(value: unknown): value is ProjectionTypeSpecification {
-    return isPrimitiveProjection(value) || isProjectionTransition(value) || isPropertyValueSpecification(value);
+export function isProjectionTransitionConfig(value: unknown): value is ProjectionTransitionSpecification {
+    return isProjectionPrimitive(value) || isProjectionTransitionValue(value) || isPropertyValueSpecification(value);
 }
 
 export function isPropertyValueSpecification(value: unknown): value is PropertyValueSpecification<ProjectionTransition> {
@@ -27,14 +27,18 @@ export function isPropertyValueSpecification(value: unknown): value is PropertyV
     return false
 }
 
-export function isProjectionTransition(value: unknown): value is ProjectionTransition {
+export function isProjectionTransitionValue(value: unknown): value is ProjectionTransition {
     return Array.isArray(value) &&
         value.length === 3 &&
-        isPrimitiveProjection(value[0]) &&
-        isPrimitiveProjection(value[1]) &&
+        isProjectionPrimitive(value[0]) &&
+        isProjectionPrimitive(value[1]) &&
         typeof value[2] === 'number';
 }
 
-export function isPrimitiveProjection(value: unknown): value is PrimitiveProjection {
-    return value === 'mercator' || value === 'globe';
+export function isProjectionPrimitive(value: unknown): value is ProjectionPrimitive {
+    return value === 'mercator' || value === 'stereographic';
+}
+
+export function isProjectionPreset(value: unknown): value is ProjectionPrimitive {
+    return value === 'globe';
 }