Hexagon Geospatial
MENU

API

M.App Portfolio provides a modern, cloud-based platform for creating and delivering diverse geospatial web applications.
Through the M.App Studio, our partners can design, build, and deploy their own Hexagon Smart M.Apps.
Showing results for 
Search instead for 
Do you mean 

GVC API reference

by Technical Evangelist on ‎05-13-2016 03:40 AM (1,417 Views)

GVC API reference

 

GVC API is part of Hexagon Geospatial Smart M.App solution ©.

 

GVC API and GVC configuration are part of the Smart M.App Business Intelligence BI API.

 

Kind: global namespace

 

Version: 0.2.11-SNAPSHOT

 

Last modified: 2016-05-13

 

Everything in GVC is scoped under the gvc namespace.

 

 

Client code API

 

  • gvc.dataStage
  • DataStage
    • id
    • table
    • features
    • stageModel
    • target
    • widgets
    • cleanup
    • redraw
    • mountWidgets
    • unmountWidgets
  • StageModel
  • ChartModel
  • gvc.chart
    • gvc.chart.base
    • gvc.chart.choropleth
    • gvc.chart.bar
    • gvc.chart.pie
    • gvc.chart.row
    • gvc.chart.line
    • gvc.chart.debug
    • gvc.chart.scatter
    • gvc.chart.number

 

gvc.dataStage(id)

 

Returns new DataStage 


Returns stage object keeping the charts configuration and the state.

 

  • {String} id of the stage

 

DataStage

 

id()

 

If invoked without parameters, this method returns current stage id.

 

id(id)

 

Sets stage's id.

 

  • {String} id of the stage

table(rows)

 

Registers tabular data.


Note that this method returns the DataStage object, so that it may be chained.

 

  • {Object[]} rows an array of plain homogenous objects.

 

features()

 

If invoked without parameters, this method returns dictionary of currently configured features.

 

features(featureDesc, featureData)

 

Registers features.

 

  • {Object} featureDesc is a feature descriptor object: 
    • {String} id - Layer ID
    • {Boolean} useAsTable - Whether tabular data should be collected from the GeoJSON features instead of a separate table call
  • {Object} featureData can currently be either GeoJSON or TopoJSON (experimental)

stageModel()

 

If invoked without parameters, this method returns current stage model. StageModel properties are described below.

 

stageModel(stageModel)

 

Registers the stage model.

 

  • {StageModel} stageModel stage model JSON

target()

 

If invoked without parameters, this method returns dictionary of stage's targets, for example:

 

{map: NewClass} where NewClass is a Leaflet map object

 

target(id, obj)

 

Sets stage's target.

 

  • {String} id id of the target
  • {Object} obj target, for example leaflet map object

 

Example:

var lmap = new L.map('map', {
    zoomControl: false
}).setView([1,101], 5);
// ...
gvc.dataStage("test")
.target('map', lmap);

 

widgets()

 

If invoked without parameters, this method returns dictionary of currently registered widgets.

 

Example:

 

stage.widgets();

 

output:

 

{
    "areas": {
        "id": "areas",
        "chartM": {
            "id": "areas",
            "chart": "choropleth",
            "features": "geometries",
            "target": "map",
            "key": "id",
            "values": [
                "sum_property1"
            ],
            "colors": {
                "domain": [0, 200],
                "range": ["#ffffff","#dfe7f1","#becee4","#9eb7d6","#7ba1c8","#578aba","#4372ae","#3b57a3","#2d3e96","#08306b"],
                "type": "quantize"
            }
        },
        "needsUpdate": false,
        "chart": {
            "__dcFlag__": 1,
            "_groupName": "XXX"
        }
    }
}

 

For detailed descriptions of chartM and chart see ChartModel and particular chart types.

 

widgets(chartModel)

 

Registers widget using passed chartModel only. Note that the "id" must be present.

 

  • {ChartModel} chartModel chart model

widgets(chartMode, chartObj)

 

Registers widget using passed chartModel and an instance of the chart object

 

  • {ChartModel} chartModel chart model
  • {Object} chartObj chart object

cleanup()

 

Cleans the stage up.

 

redraw(stageModel)

 

Redraws the stage using the passed stageModel. It is possible to pass only things that actually changed.

 

  • {StageModel} stageModel Stage Model

mountWidgets(chartModel, chartObj)

 

Dynamically mounts widgets. See widgets(chartMode, chartObj)

 

unmountWidgets(chartId)

 

Dynamically unmounts a widget

 

  • {String} id id of the widget

 

StageModel

 

stageModel is a JSON object with the following properties:

 

  • {String} id ID of the stage
  • {Object[]} fields - Definition of objects that can be used as chart dimensions. Each object contains
    • {String} id - unique name
    • {Expression} value - expression.
    • {String} name - display name
  • {Object[]} totals - (Optional) Grand totals for the data table. Grand totals are precomputed. Each object contains
    • {String} id ID of the grand total
    • {Expression} value Typically it uses operators like "$sum(x)" or "$avg(x)"
  • {String[]} subtotals - (Optional) Subtotals for the data table computed dynamically within particular group. Each element represents what is behind by in group by
  • {Object} featuresObj (Deprecated in favor of features)
  • {Object[]} features - Definition of features. It makes possible to join geometric data with tabular data. Each object contains
    • {String} id This is the same id as the one used in stage.features method
    • {String} key Primary key that allows to join tabular data and geometries
    • {String[]} timekey (Optional) Time Key. Currently only one per data stage
    • {String} name Display name
  • {Object[]} values Measures. Each object contains:
    • {String} id
    • {Expression} value
    • {String} name
  • {Object} colors Dictionary of color definitions. Each key (color palette name) maps to an object that contains
    • {Number[]} domain
    • {RGBCode[]} range
    • {String} type threshold/quantize

 

ChartModel

 

ChartModel is a JSON object with the following properties:

 

  • {String} chart Chart type
  • {String} name
  • {String} key
  • {String/Expression/String[]/Expression[]} values
  • {String/RGBCode/String[]/RGBCode[]} colors
  • {Expression[]} tooltips
  • {Object} legend
    • {Number} x
    • {Number} y
  • {Object} <chart type> properties specific to particular chart type. In general it follows matching DC.js widget properties
  • {Object} margins Example: { "top": 60, "right": 50, "bottom": 30, "left": 45 }
  • {Object} axis Axis configuration. This object contains
    • {Object} x
      • {Number[]} domain [0, 2000]
      • {String} scale linear (See DC charts documentation)
      • {Number} units 30
      • {Number} padding in pixels 0
      • {String} label Test label
      • {Number} labelPadding in pixels 0
      • {Number} ticks 5
      • {String} tickFormat d
      • {String} tickPadding in pixels 3
      • {Boolean} elastic true
    • {Object} y Same as x but for the Y axis
      • {Number[]} domain [0, 2000]
      • {String} scale linear (See DC charts documentation
      • {Number} units 30
      • {Number} padding in pixels 0
      • {String} label Test label
      • {Number} labelPadding in pixels 0
      • {Number} ticks 5
      • {String} tickFormat d
      • {String} tickPadding in pixels 3
      • {Boolean} elastic true
    • {Object} grid
      • {Boolean} horizontal
      • {Boolean} vertical
      • {Boolean} brushing

 

gvc.chart

 

Please keep in mind that in the current implementation objects returned by specific gvc.chart creating functions return extended dc objects. As it may be tempting to assume that each GVC object type corresponds to a specific DC object type (and it is actually helpful for understanding the library concept), this implementation detail may change in the future and dc-ness of the GVC objects would be accessible by another means.

 

//...
chart = gvc.chart.specificChart(div);
//...
stage.widgets(specificChartModel, chart);

 

gvc.chart.base

 

Abstract chart type. Not to be instantiated. It may be a basis for GVC extensions.

Returns: dc.baseMixin

 

gvc.chart.choropleth

 

See: Choropleth configuration section

 

chart = gvc.chart.choropleth(leafletMapId, leafletLayerGroup);

Choropleth configuration properties:

 

  • {String} chart: "choropleth"
  • {String} name: Display name
  • {String} target: "map" ID of the Leaflet map object
  • {String} layer: ID of the featureLayer configured in the Stage Model
  • {String} key: Property that is ID of the feature
  • {String/Expression/String[]/Expression[]} values: Measures
  • {String} colors: Identifier of the color palette defined in the Stage Model
  • {Expression/Expression[]} tooltips: Definition of the aggregations that can be accessed in a tooltip data with mouse over event. Example: {round(green_percentage *100)/100 } % of green
  • {Object} legend: Legend for choropleth is rendered differently than for other widgets
    • {String} id: ID of the DIV
    • {Number} x: X coordinate
    • {Number} y: Y coordinate
    • {Number} gap: Gap between values
    • {Boolean} horizontal: Whether to render the legend horizontally

 

Following example creates choropleth chart which assign different colors to areas by green percentage:

 

var mychoroplethChart = {
    //Name of widget i.e. :
    "MyCustomMap": {
        chart: "choropleth", //chart type
        name: "choropleth chart", // name of chart
        target: 'map', // id of Leaflet map object
        layer: "zoneFeatures", // id of the featureLayer configured in the Stage Model
        key: "zoneId", // Property that is id of the feature, defined in "fields" in stageModel.js
        values: "green_percentage", // values from stageModel.js
        colors: "percentage_colors", //colors for chart that are defined in stageModel.js
        tooltips: ["{round(green_percentage *100)/100 } % of green"], //Definition of the aggregations that can be accessed in a tooltip data with mouse over event.
        legend:{
            "id": "legend",
            "x": 20,
            "y": 15,
            "gap": 5,
            "horizontal": false
        }
    }
}

 

Returns: dc.baseMixin

 

gvc.chart.bar

 

configuration properties:

 

  • {Boolean} centerBar Whether the bar chart will render each bar centered around the data position on the x-axis.
  • {Number} barPadding the spacing between bars as a fraction of bar size. Valid values are between 0-1. Setting this value will also remove any previously set gap. See the d3 docs for a visual description of how the padding is applied. 0
  • {Number} outerPadding the outer padding on an ordinal bar chart. This setting has no effect on non-ordinal charts. Will pad the width by padding * barWidth on each side of the chart. 0.5
  • {Number} gap Manually set fixed gap (in px) between bars instead of relying on the default auto-generated gap. By default the bar chart implementation will calculate and set the gap automatically based on the number of data points and the length of the x axis. 2
  • {Number} alwaysUseRounding whether rounding is enabled when bars are centered. If false, using rounding with centered bars will result in a warning and rounding will be ignored. This flag has no effect if bars are not centered. When using standard d3.js rounding methods, the brush often doesn't align correctly with centered bars since the bars are offset.

 

Following example creates bar chart which shows percantage of green area on map. Chart is located on the left side of map.

 

var mybarChart = {
    "absolute": {
        chart: "bar", // Chart type
        title: "absolute values", // Chart title
        target: "barChart",
        key: "greenP", // -- will be used as key
        values: ["green_total_percentage_value", "grey_total_percentage_value"], //these values are from stageModel.js
        colors: ["#74c476", "#f7c08a"],
        // -- base layout  parameters, if not specified defaults are applied (see dc.js documentaiton)
        width: 20,
        height: 30,
        margins: {
            "top": 20,
            "right": 50,
            "bottom": 30,
            "left": 25
        },
        tooltips: [
            //Definition of the aggregations that can be accessed in a tooltip data with mouse over event.
            "{round(key *100)/100} % of green in zone, {round(green_total_percentage_value *100)/100} % of green at all",
            "{round(key *100)/100} % of green in zone, {round(grey_total_percentage_value*100)/100} % of grey at all"
        ],
        legend: {
            // Defines placing on map
            "x": 80,
            "y": 20
        },
        // properties specific to particular chart type. In general it follows matching DC.js widget properties. In this example it's "bar"
        bar: {
            centerBar: true,
            barPadding: 0,
            outerPadding: 0.5,
            gap: 2,
            alwaysUseRounding: false
        }
    }
};

Returns: dc.barChart

 

gvc.chart.pie

 

configuration properties:

 

  • {Number} slicesCap the maximum number of slices the pie chart will generate. The top slices are determined by value from high to low. Other slices exeeding the cap will be rolled up into one single Others slice.
  • {Number} externalRadiusPadding the external radius padding of the pie chart. This will force the radius of the pie chart to become smaller or larger depending on the value.
  • {Number} innerRadius the inner radius of the pie chart. If the inner radius is greater than 0px then the pie chart will be rendered as a doughnut chart.
  • {Number} radius the outer radius. If the radius is not set, it will be half of the minimum of the chart width and height.
  • {Number} cx center x coordinate position. Default is center of svg.
  • {Number} cy center y coordinate position. Default is center of svg.
  • {Number} minAngleForLabel the minimal slice angle for label rendering. Any slice with a smaller angle will not display a slice label.
  • {Number} emptyTitle Title to use for the only slice when there is no data.
  • {Number} externalLabels Position slice labels offset from the outer edge of the chart
  • {Boolean} drawPaths Get or set whether to draw lines from pie slices to their labels.

Following example creates pie chart which shows distribution of green over particular areas on map:

 

 var mypieChart = {
     "MyPieChart": {
         id: "pieChart", //ID of the chart
         target: "pieChart", //ID of leaflet map object
         chart: "pie", //Type of chart
         title: "distribution of green over area", // Title of the chart
         key: "sector", //Property that is ID of the feature, key is from "fields" in stageModel.js
         values: ["green_total_percentage_value"], //Values are from stageModel.js
         colors: ['#a50026', '#d73027', '#f46d43', '#fdae61'],
         tooltips: "sector {key}  contributes with  {round(green_total_percentage_value*100)/100} % of green at all",
         legend: {
             "x": 140,
             "y": 100
         },
         pie: {
             "innerRadius": 90, // If the inner radius is greater than 0px then the pie chart will be rendered as a                     doughnut chart.
             "radius": 120 // If the radius is not set, it will be half of the minimum of the chart width and height.
             },
         margins: {
             "top": 50,
             "right": 50,
             "bottom": 30,
             "left": 45
         }
     }
 };

Returns: dc.pieChart

 

gvc.chart.row

 

configuration properties:

 

  • {d3.scale} x he x scale. The x scale can be any d3 quantitive scale
  • {d3.svg.axis} xAxis Get the x axis for the row chart instance. Note: not settable for row charts. See the d3 axis object documention for more information.
  • {Boolean} renderTitleLabel Turn on/off Title label rendering (values) using SVG style of text-anchor 'end'
  • {Boolean/Number} fixedBarHeight the fixed bar height. Default is [false] which will auto-scale bars. For example, if you want to fix the height for a specific number of bars (useful in TopN charts) you could fix height as follows (where count = total number of bars in your TopN and gap is your vertical gap space).
  • {Number} gap the vertical gap space between rows on a particular row chart instance
  • {Number} elasticX the elasticity on x axis. If this attribute is set to true, then the x axis will rescle to auto-fit the data range when filtered.
  • {Number} labelOffsetX the x offset (horizontal space to the top left corner of a row) for labels on a particular row chart.
  • {Number} labelOffsetY the y offset (vertical space to the top left corner of a row) for labels on a particular row chart.
  • {Number} titleLabelOffsetX the x offset (horizontal space between right edge of row and right edge or text.

Following example creates row chart which shows number of acres of green in particular area on map, chart is located on the left side of map:

 

var myrowChart = {
     id: "rowChart",
     target: "rowChart",
     chart: "row",
     name: "distribution of green over area",
     key: "beat", //key from "fields" in stageModel.js
     values: ["green_absolute"], // values are from stageModel.js 
     colors: ["#a50026"],
     tooltips: "sector {key}  has {round(green_absolute*100)/100} acres of green",
     legend: {
         "x": 80,
         "y": 20
     },
     row: {
         fixedBarHeight: false, //the fixed bar height. Default is [false] which will auto-scale bars.
         gap: 10, //the vertical gap space between rows on a particular row chart instance
         elasticX: true, //the elasticity on x axis. If this attribute is set to true, then the x axis will rescle to              auto-fit the data range when filtered.
         renderTitleLabel: false //Turn on/off Title label rendering (values) using SVG style of text-anchor 'end'
     },
     margins: {
         "top": 50,
         "right": 50,
         "bottom": 60,
         "left": 45
     },
     axis: {
         x: {
             domain: [40, 100],
             scale: 'linear',
             padding: 0, // xAxisPadding
             label: "Green %", // ?
             labelPadding: 0,
             ticks: 5,
             tickFormat: "d",
             tickPadding: 0,
             elastic: false
         }
     },
 };

Returns: dc.rowChart

 

gvc.chart.line

 

configuration properties:

 

  • {String} interpolate the interpolator to use for lines drawn, by string name, allowing e.g. step functions, splines, and cubic interpolation. This is passed to d3.svg.line.interpolate and d3.svg.area.interpolate, where you can find a complete list of valid arguments. Default value: linear
  • {Number[]} dashStyle the line's d3 dashstyle. This value becomes the 'stroke-dasharray' of line. Defaults to empty array (solid line).
  • {Number} tension the tension to use for lines drawn, in the range 0 to 1. This parameter further customizes the interpolation behavior. It is passed to d3.svg.line.tension and d3.svg.area.tension. Default value:.7
  • {function} defined Gets or sets a function that will determine discontinuities in the line which should be skipped: the path will be broken into separate subpaths if some points are undefined. This function is passed to d3.svg.line.defined
  • {Boolean} renderArea render area flag. If the flag is set to true then the chart will render the area beneath each line and the line chart effectively becomes an area chart.
  • {Boolean} xyTipsOn Turn on/off the mouseover behavior of an individual data point which renders a circle and x/y axis dashed lines back to each respective axis. This is ignored if the chart brush is on
  • {Number} dotRadius the radius (in px) for dots displayed on the data points.
  • {Object} renderDataPoints Always show individual dots for each datapoint. If options is falsy, it disables data point rendering. If no options are provided, the current options values are instead returned.
    • {Number} fillOpacity
    • {Number} strokeOpacity
    • {Number} radius

Following example creates line chart which shows distribution of green over areas on map. X axis is data about areas, Y axis is data of percentage on particular area:

 

var mylineChart = {
    id: "lineChart",
    target: "lineChart",
    chart: "line",
    name: "distribution of green over area",
    key: "area", //key is defined in "fields" in stageModel.js
    values: ["green_percentage", "grey_percentage"], //values are defined in stageModel.js
    colors: ["#74c476", "#f7c08a"],
    legend: {
        "x": 80,
        "y": 20
    },
    line: {
        interpolate: 'monotone',
        renderArea: true, //render area flag. If the flag is set to true then the chart will render the area beneath each         line and the line chart effectively becomes an area chart.
        renderDataPoints: true //Always show individual dots for each datapoint. If options is falsy, it disables data            point rendering
    },
    margins: {
        "top": 50,
        "right": 50,
        "bottom": 30,
        "left": 45
    },
    axis: {
        x: {
            domain: [0, 3800],
            scale: 'linear',
            units: 30,
            padding: 0, // xAxisPadding
            label: "zone area", // --xAxisLabel
            labelPadding: 15,
            ticks: 5,
            tickFormat: "d",
            tickPadding: 3,
            elastic: true
        },
        y: {
            domain: [0, 3800],
            scale: 'linear',
            padding: 0, // xAxisPadding
            useRightSide: false,
            label: "% on zone ",
            labelPadding: 15,
            ticks: 7,
            tickFormat: "d",
            tickPadding: 3,
            elastic: true
        },
        grid: {
            horizontal: true,
            vertical: false,
            brushing: true
        },
    },
};

Returns: dc.lineChart

 

gvc.chart.scatter

 

configuration properties:

 

  • {d3.svg.symbol().type()/String} symbol the symbol type used for each point. By default the symbol is a circle. Type can be a constant or an accessor.
  • {function} existenceAccessor Get or set the existence accessor. If a point exists, it is drawn with symbolSize radius and opacity 1; if it does not exist, it is drawn with emptySize radius and opacity 0. By default, the existence accessor checks if the reduced value is truthy.
  • {Number} symbolSize radius for symbols.
  • {Number} highlightedSize radius for highlighted symbols.
  • {Number} excludedSize Set or get size for symbols excluded from this chart's filter. If null, no special size is applied for symbols based on their filter status
  • {Number} excludedColor Set or get color for symbols excluded from this chart's filter. If null, no special color is applied for symbols based on their filter status
  • {Number} excludedOpacity Set or get opacity for symbols excluded from this chart's filter.
  • {Number} emptySize Set or get radius for symbols when the group is empty.
  • {Number} hiddenSize radius for symbols when the group is empty.

 

Following example creates scatter chart which shows info about distribution of green over areas. As in previous example, X axis is data about areas, Y axis is data about percentage of green:

 

var myscatterChart = {
    id: "rowChart",
    target: "rowChart",
    chart: "scatter",
    name: "distribution of green over area",
    key: ["(zoneId)", "(greenP)"], //keys are from stageModel.js
    //    values: ["green_percentage", "grey_percentage"], // -- we don't need values in scatter
    colors: "percentage_colors", // colors are from stageModel.js
    legend: {
        "x": 80,
        "y": 20
    },
    scatter: {
        symbol: 'circle', //the symbol type used for each point. By default the symbol is a circle. Type can be a constant or an accessor.
        symbolSize: 6, //radius for symbols.
        highlightedSize: 9, //radius for highlighted symbols.
        hiddenSize: 0 //radius for symbols when the group is empty.
    },
    margins: {
        "top": 50,
        "right": 50,
        "bottom": 40,
        "left": 45
    },
    axis: {
        x: {
            domain: [0, 30],
            scale: 'linear',
            padding: 0, // xAxisPadding
            label: "zone", // --xAxisLabel
            labelPadding: 15,
            ticks: 5,
            tickFormat: "d",
            tickPadding: 3,
            elastic: false
        },
        y: {
            domain: [0, 100],
            scale: 'linear',
            padding: 0, // xAxisPadding
            label: "Green %", // --xAxisLabel
            labelPadding: 15,
            ticks: 5,
            tickFormat: "d",
            tickPadding: 3,
            elastic: false
        },
        grid: {
            horizontal: true,
            vertical: true,
            brushing: true
        },
    }
};

Returns: dc.scatterPlot

 

gvc.chart.number

 

configuration properties:

 

  • {Number} value Calculate and return the underlying value of the display
  • {String} formatNumber. See d3.format.
  • {Object} html HTML templates to use depending on the number displayed. The text %number will be replaced with the current value.
    • {String} one Example: "%number record"
    • {String} some Example: "%number records"
    • {String} none Example: "No records"

Following example creates number chart which shows total green and grey in particular areas:

 

var mynumberChart = {
    id: "number",
    target: "number",
    chart: "number",
    name: "Total Green and Grey",
    // key: "zoneNum",
    values: {
        group: "greengrey", //id from stageModel.js
        value: "green_absolute + grey_absolute", //values from stageModel.js
        colors: "total_percentage_colors" //colors from stageModel.js
    },
    colors: "percentage_colors",
    number: {
        html: { //HTML templates to use depending on the number displayed. The text %number will be replaced with the current value.
            one: "<span style=\"color:darkgreen; \">%number  </span> ",
            some: "dfg <span style=\"color:darkgreen; \">%number  </span>",
            none: "<span style=\"color:steelblue; \">0 %</span>",
            negative: "<span style=\"color:darkred; \">%number  </span>"
        },
        format: ".0f" //See d3.format.
    }
};

Returns: dc.numberDisplay

 

gvc.chart.debug

 

gvc.chart.debug is a special chart for debugging and development. It shows raw text values in tabular form instead of any graphical elements so that it is possible to check whether values computed for another chart are correct.

 

gvc.chart.debug(div)
  • {String/HTMLElement} div String ID or entire HTML Element where the debug chart is to be rendered.