diff --git a/build/vega-lite-schema.json b/build/vega-lite-schema.json index cb3d8b1c24..ab5b6c26bc 100644 --- a/build/vega-lite-schema.json +++ b/build/vega-lite-schema.json @@ -5095,7 +5095,8 @@ "description": "The end angle of arc marks in radians. A value of 0 indicates up or “north”, increasing values proceed clockwise." }, "time": { - "$ref": "#/definitions/TimeDef" + "$ref": "#/definitions/TimeDef", + "description": "Time position of animated marks." }, "tooltip": { "anyOf": [ @@ -9223,7 +9224,8 @@ "description": "The end angle of arc marks in radians. A value of 0 indicates up or “north”, increasing values proceed clockwise." }, "time": { - "$ref": "#/definitions/TimeDef" + "$ref": "#/definitions/TimeDef", + "description": "Time position of animated marks." }, "tooltip": { "anyOf": [ @@ -22019,7 +22021,7 @@ "additionalProperties": false, "properties": { "animationDuration": { - "description": "Default animation duration (in seconds) for time encodings, except for [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales.\n\n__Default value:__ `5`", + "description": "Default animation duration (in seconds) for [`time`](https://vega.github.io/vega-lite/docs/encoding.html#time) encodings (except for [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales, which use `framesPerSecond` instead).\n\n__Default value:__ `5`", "type": "number" }, "bandPaddingInner": { @@ -22111,7 +22113,7 @@ "minimum": 0 }, "framesPerSecond": { - "description": "Default framerate (frames per second) for time [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales.\n\n__Default value:__ `2`", + "description": "Default framerate (frames per second) for [`time`](https://vega.github.io/vega-lite/docs/encoding.html#time) encoding animation [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales.\n\n__Default value:__ `2`", "type": "number" }, "invalid": { diff --git a/examples/compiled/animated_gapminder.png b/examples/compiled/animated_gapminder.png index 4dff78c574..d8ad0a5237 100644 Binary files a/examples/compiled/animated_gapminder.png and b/examples/compiled/animated_gapminder.png differ diff --git a/examples/compiled/animated_gapminder.svg b/examples/compiled/animated_gapminder.svg index 28b20d36f1..25c88b4044 100644 --- a/examples/compiled/animated_gapminder.svg +++ b/examples/compiled/animated_gapminder.svg @@ -1 +1,5 @@ -0123456789fertility0102030405060708090life_expectAfghanistanArgentinaAustraliaAustriaBahamasBangladeshBarbadosBelgiumBoliviaBrazilCanadaChileChinaColombiaCosta RicaCroatiaCubaDominican RepublicEcuadorEgyptEl SalvadorFinlandFranceGeorgiaGermanyGreeceGrenadaHaitiHong Kong, China…33 entriescountry \ No newline at end of file +<<<<<<< HEAD +0123456789fertility0102030405060708090life_expectAfghanistanArgentinaAustraliaAustriaBahamasBangladeshBarbadosBelgiumBoliviaBrazilCanadaChileChinaColombiaCosta RicaCroatiaCubaDominican RepublicEcuadorEgyptEl SalvadorFinlandFranceGeorgiaGermanyGreeceGrenadaHaitiHong Kong, China…33 entriescountry +======= +02468fertility020406080life_expect +>>>>>>> e169c8ed8 (animation docs first pass) diff --git a/examples/compiled/animated_gapminder.vg.json b/examples/compiled/animated_gapminder.vg.json index cede23a2a7..63dca90d2e 100644 --- a/examples/compiled/animated_gapminder.vg.json +++ b/examples/compiled/animated_gapminder.vg.json @@ -191,20 +191,5 @@ "tickCount": {"signal": "ceil(height/40)"}, "zindex": 0 } - ], - "legends": [ - { - "stroke": "color", - "symbolType": "circle", - "title": "country", - "encode": { - "symbols": { - "update": { - "fill": {"value": "transparent"}, - "opacity": {"value": 0.7} - } - } - } - } ] } diff --git a/examples/compiled/animated_hop.svg b/examples/compiled/animated_hop.svg index 4a0bf61361..d03cfe784a 100644 --- a/examples/compiled/animated_hop.svg +++ b/examples/compiled/animated_hop.svg @@ -1 +1,5 @@ -0102030405060precipitation \ No newline at end of file +<<<<<<< HEAD +0102030405060precipitation +======= +0102030405060precipitation +>>>>>>> 225066019 (hop example) diff --git a/examples/specs/animated_gapminder.vl.json b/examples/specs/animated_gapminder.vl.json index 11fdbb767d..d362939dfc 100644 --- a/examples/specs/animated_gapminder.vl.json +++ b/examples/specs/animated_gapminder.vl.json @@ -25,7 +25,8 @@ ], "encoding": { "color": { - "field": "country" + "field": "country", + "legend": null }, "x": { "field": "fertility", diff --git a/site/_data/examples.json b/site/_data/examples.json index 99568b67ea..677efc59e2 100644 --- a/site/_data/examples.json +++ b/site/_data/examples.json @@ -955,5 +955,19 @@ "png": true } ] + }, + "Animated": { + "": [ + { + "name": "animated_gapminder", + "title": "Gapminder Frame Animation", + "description": "An animated scatterplot showing the relationship between fertility rates and life expectancy across different countries, based on Gapminder data. Each point represents a country, with points colored by country and the visualization updating over time to show how these metrics have changed across years." + }, + { + "name": "animated_hop", + "title": "Hypothetical outcome plot", + "description": "An animated tick chart displaying precipitation measurements from Seattle weather data. Each horizontal tick mark represents a precipitation value for a specific date, with the visualization updating over time to show the temporal progression of rainfall patterns." + } + ] } } diff --git a/site/docs/encoding.md b/site/docs/encoding.md index 1781e80c1c..210b454fbf 100644 --- a/site/docs/encoding.md +++ b/site/docs/encoding.md @@ -84,6 +84,7 @@ The keys in the `encoding` object are encoding channels. Vega-Lite supports the - [Position Offset Channels](#position-offset): `xOffset`, `yOffset` - [Polar Position Channels](#polar): `theta`, `theta2`, `radius`, `radius2` - [Geographic Position Channels](#geo): `longitude`, `latitude`, `longitude2`, `latitude2` +- [Time Channel](#time): `time` - [Mark Property Channels](#mark-prop): `angle`, `color` (and `fill` / `stroke`), `opacity`, `fillOpacity`, `strokeOpacity`, `shape`, `size`, `strokeDash`, `strokeWidth` - [Text and Tooltip Channels](#text): `text`, `tooltip` - [Hyperlink Channel](#href): `href` @@ -261,6 +262,36 @@ Polar field and datum definitions may include `scale`, `stack`, and `sort` prope See [an example that uses `longitude` and `latitude` channels in a map]({{ site.baseurl }}/examples/geo_circle.html) or [another example that draws line segments (`rule`s) between points in a map]({{ site.baseurl }}/examples/geo_rule.html). +{:#time} + +## Time Channel + +The `time` channel maps data values to animation keyframes over time. When a time encoding is specified, together with a [selection parameter](selection.html) that has a `timer` [event stream](selection.html#on), marks are animated to show different data values as time progresses. + +See [an example scatterplot animation]({{ site.baseurl }}/examples/animated_gapminder.html) that uses the `time` channel and a `timer` selection parameter. + +{% include table.html props="time" source="Encoding" %} + +Note: `time` encoding animations currently have a few restrictions. See the [example gallery]({{ site.baseurl }}/examples/#animated) for examples of animated visualizations. + +- must also explicility specify a selection parameter + - parameter must have a `timer` event + - parameter must select the same field as the `time` field definition +- must explicitly define a filter using that parameter +- currently, the `time` channel only supports `band` scales (these are the default for discrete frame animation) +- currently, only unit specifications are supported (no multi-view animations) + + + {:#mark-prop} ## Mark Property Channels diff --git a/site/docs/encoding/scale.md b/site/docs/encoding/scale.md index 8a5c6f9e2c..ed116575c8 100644 --- a/site/docs/encoding/scale.md +++ b/site/docs/encoding/scale.md @@ -458,6 +458,14 @@ To provide themes for all scales, the scale config (`config: {scale: {...}}`) ca {% include table.html props="invalid" source="ScaleConfig" %} +#### Animation + + + + + +{% include table.html props="framesPerSecond" source="ScaleConfig" %} + #### Other {% include table.html props="clamp,round,xReverse,useUnaggregatedDomain,zero" source="ScaleConfig" %} diff --git a/src/channeldef.ts b/src/channeldef.ts index 8e69bb08fe..c04840d72a 100644 --- a/src/channeldef.ts +++ b/src/channeldef.ts @@ -525,6 +525,11 @@ export type PolarDef = PositionFieldDefBase | PositionDatumD export type TimeDef = TimeFieldDef; export interface TimeMixins { + /* + Optional. A boolean flag. When rescale is true, scale domains update according to the subset of data inside the current keyframe. When rescale is false, scale domains are generated from the entire dataset. + + __Default value:__ `false` + */ rescale?: boolean; } export type TimeFieldDef = ScaleFieldDef & TimeMixins; diff --git a/src/compile/scale/range.ts b/src/compile/scale/range.ts index c635d1561d..9f6ccd3abf 100644 --- a/src/compile/scale/range.ts +++ b/src/compile/scale/range.ts @@ -322,7 +322,7 @@ function defaultRange(channel: ScaleChannel, model: UnitModel): VgRange { // if (scaleType === 'band') { return {step: 1000 / config.scale.framesPerSecond}; // } - // return [0, config.scale.animationDuration * 1000]; // TODO(jzong): uncomment for linear scales when interpolation is implemented + // return [0, config.scale.animationDuration * 1000]; // TODO(jzong): uncomment for linear scales when interpolation is implemented https://github.com/vega/vega-lite/issues/9590 } case STROKEWIDTH: diff --git a/src/compile/scale/type.ts b/src/compile/scale/type.ts index 3812db7ab8..ef0bae2c60 100644 --- a/src/compile/scale/type.ts +++ b/src/compile/scale/type.ts @@ -118,7 +118,7 @@ function defaultType( return 'utc'; } else if (isTime(channel)) { // return 'linear'; - return 'band'; // TODO(jzong): when interpolation is implemented, this should be 'linear' + return 'band'; // TODO(jzong): when interpolation is implemented, this should be 'linear' https://github.com/vega/vega-lite/issues/9590 } return 'time'; @@ -136,7 +136,7 @@ function defaultType( return 'ordinal'; } else if (isTime(channel)) { // return 'linear'; - return 'band'; // TODO(jzong): when interpolation is implemented, this should be 'linear' + return 'band'; // TODO(jzong): when interpolation is implemented, this should be 'linear' https://github.com/vega/vega-lite/issues/9590 } return 'linear'; diff --git a/src/compile/selection/point.ts b/src/compile/selection/point.ts index dd88743f35..b9c9ede9be 100644 --- a/src/compile/selection/point.ts +++ b/src/compile/selection/point.ts @@ -27,7 +27,7 @@ const animationSignals = (selectionName: string, scaleName: string): Signal[] => }, // scale signals - // TODO(jzong): uncomment commented signals below when implementing interpolation + // TODO(jzong): uncomment commented signals below when implementing interpolation https://github.com/vega/vega-lite/issues/9590 {name: `${selectionName}_domain`, init: `domain('${scaleName}')`}, {name: MIN_EXTENT, init: `extent(${selectionName}_domain)[0]`}, // {name: 'max_extent', init: `extent(${selectionName}_domain)[1]`}, diff --git a/src/encoding.ts b/src/encoding.ts index 3fc6753a66..428ebdce95 100644 --- a/src/encoding.ts +++ b/src/encoding.ts @@ -187,6 +187,9 @@ export interface Encoding { */ radius2?: Position2Def; + /** + * Time position of animated marks. + */ time?: TimeDef; /** diff --git a/src/scale.ts b/src/scale.ts index 7af9ae5e69..f4d9e926ad 100644 --- a/src/scale.ts +++ b/src/scale.ts @@ -436,7 +436,7 @@ export interface ScaleConfig extends ScaleInvali zero?: boolean; /** - * Default framerate (frames per second) for time [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales. + * Default framerate (frames per second) for [`time`](https://vega.github.io/vega-lite/docs/encoding.html#time) encoding animation [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales. * * __Default value:__ `2` * @@ -444,12 +444,14 @@ export interface ScaleConfig extends ScaleInvali framesPerSecond?: number; /** - * Default animation duration (in seconds) for time encodings, except for [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales. + * + * Default animation duration (in seconds) for [`time`](https://vega.github.io/vega-lite/docs/encoding.html#time) encodings (except for [`band`](https://vega.github.io/vega-lite/docs/scale.html#band) scales, which use `framesPerSecond` instead). * * __Default value:__ `5` * */ - animationDuration?: number; + // TODO(jzong): uncomment when linear scales for animation are implemented https://github.com/vega/vega-lite/issues/9590 + // animationDuration?: number; } export const defaultScaleConfig: ScaleConfig = { @@ -481,7 +483,7 @@ export const defaultScaleConfig: ScaleConfig = { zero: true, framesPerSecond: 2, - animationDuration: 5, + // animationDuration: 5, //TODO(jzong): uncomment when linear scales for animation are implemented https://github.com/vega/vega-lite/issues/9590 }; export interface SchemeParams {