nasa / common-mapping-client

CMC is a starter-kit for creating web-based mapping applications

Welcome to the Common Mapping Client!

Overview

The Common Mapping Client (CMC) is a foundation for web-based mapping applications that leverages, combines, and abstracts certain commonly used mapping functionalities, enabling developers to spend less time reinventing the wheel and more time solving their specific problems. Sitting somewhere between a starter-kit and a framework, CMC aims fulfill the basic needs of a mapping application without getting in the way of any given project's unique goals.

Over the years, there have been many projects that try to solve the same issue: put data on a map and explore it. Unfortunately, there is an increasingly steep hill to climb when it comes to actually starting one of these projects. All of them have to decide: Which framework should I start from? Which library will give me the features I need? How to I glue all these together with a code layout that I won't want to burn next week? CMC solves this by bundling together a solid and modular base framework with robust mapping libraries, a well thought out structure, and a thick shield against feature-creep to let you start building the cool stuff faster.

We maintain a list of further example projects and projects that began from CMC so that you can easily get examples of building intricate and detailed workflows on top of this tool.

View our live demo.

Features

• 2D/3D Map library abstraction
• Map layer controls
• Map layer ingestion and merging (from JSON and WMTS capabilities XML)
• Highly customizable user analytics
• Configurable map projection
• Basic vector layer support
• Map extent synchronization across all maps (2D and 3D)
• Geodesic map geometry synchronization across all maps (2D and 3D)
• Global time widget, and interactive timeslider
• Adjustable map layer cache
• Shareable/loadable application state via url parameters with share widget (facebook, twitter, email, google plus)
• Core set of UI elements necessary for most basic applications
• Basemap switching
• Basic shape drawing tools in 2D and 3D
• Basic geodesic measurement (distance and area) tools in 2D and 3D
• Display help documentation from markdown files
• A preconfigured testing framework
• A preconfigured build process
• Handy development tools
  • Hot reloading
  • Local dev and production node servers
  • BrowserSync

Quickstart

Install

1. Install NodeJS
2. Get the code
   1. Option A: Grab a tag that suits you
   2. Option B: Fork the repo into your new project and get the cutting edge goodness
   3. Option C: Clone the repo, contribute back, and get the cutting edge goodness
3. npm install: install node dependencies
4. npm start: build and server development code bundle
5. Start building.

Build

• npm run build: build production code bundle
• npm run open:dist: serve production code bundle

Test

• npm run test: Single run of tests
• flags
  • --includecoretests: Include cmc-core tests as well
  • --nowebgl: Run tests in phantomJS and skip tests that require webgl
  • --watch: Run tests with code watch

Contributing to the Project

Contributing Directly to CMC-Core

You are more than welcome to create forks to fix bugs, add features or enhancements or otherwise improve the tool. Please submit these changes through pull-requests for review.

Contributing to the CMC Ecosystem

If you use CMC for your own project, please let us know so that we may list it under our Example Projects for others to find inspiration in.

If you create a particularly useful or robust widget in your own CMC descendant, please create an example project demonstrating just that widget so that others who have the same problem down the road may find a solution faster.

Documentation Shortcut

• Walkthrough
• Developer Guide
• Example Projects

common-mapping-client's Issues

Should src/App container an index.js?

Right now our starter src/App/ does not container an index.js file. Should we add one? And maybe an empty scss file as well?

update MUI

Material-UI has released an official 1.0.0: https://medium.com/material-ui/material-ui-v1-is-out-e73ce13463eb

Layer menu controls should toggle popovers instead of just opening them

Break all components into HOC wrappers and "simple" React components

Inheriting from and sharing many of our components is made difficult by the fact that the default export is the result of the redux connect() function that makes them an HOC. Additionally, it means that to use those components without relying on state requires more or less duplicating the component.

If we instead created standard react components and then created wrapper components that used the connect() HOC, we could have the best of all the worlds. At the cost of inflating the number of files we have significantly.

Fit basemap thumbnail text to item

If a basemap option thumbnail fails to load, the default text of "basemap preview image" overflows the container.

The following styles should be added to the .preview class in BaseMapList.scss

white-space: normal;
font-size: 1.2rem;
line-height: 1.2rem;

Simplify Tile Overrides

RIght now, we have tile overrides configured per library for each layer. However if we change the TileHandler utility to take in a source library reference string then we could configure a single override string for the layer and handle the library separation in the util.

Something like...

layers.json

{
  "id": "layer_id_str",
  "wmtsOptions": {
     "urlFunction":  "kvpTimeParam",
     "tileFunction":  "coolTileThing"
    }
}

TileHandler.js

static getUrlFunction(functionString = "", libraryString = "") {
...
}

Change old githib repo references to reflect new public repo

change all configs to use lat/lon internally

standardizing the expected format of coordinates to lat/lon would allow switching between default projections without needing to change default view or rendering extents.

We should use lat/lon within the application and reproject coordinates on the fly just before they are applied to the map objects.

Cesium imagery provider wrappers should make use of the optional layer extent

Need to translate the optional layer "extents" parameter into the "rectangle" parameter used in Cesium imagery provider construction, use case being non-global layers. Right now Cesium will request tiles for non-global layers which fills the console log with loads of failed request warnings.

Fix tooltip flicker

MUI Tooltips (esp in the layer menu) can behave erratically when they overlay their target node.

Ticket in MUI: mui/material-ui#10735

Fix:

<Tooltip PopperProps={{ style: { pointerEvents: 'none' } }}>
  ...
</Tooltip>

We could create a simple custom Tooltip component that applies that fix and use that component instead of the native MUI component

Use MomentJS dates everywhere

Currently, we store dates as vanilla js date objects in state/config and then parse them with moment for all date related queries/display. This makes it difficult to do things like use UTC in an application and is probably quite efficient with the amount of moment parsings we do. If we switch to using momentjs dates by default everywhere, we could dramatically cut down the number of parsings we have to do and it would be much easier to set a global timezone

Make deletion of layer partials optional

Currently, partial layer configs loaded from wmts or other non-json source are removed from state. I believe this choice was made in order to keep state light, but given our use of Immutable and the fact that the partials set of layers can just be ignored by any components that care, there doesn't seem to be a good reason to keep this behavior. Indeed, at least making this optional would enable users more easily to create an application that bases its layer configs solely on a GetCapabilites call

Convert actions to static classes

Overriding and extending actions is currently a tedious affair. We could mimic the approach taken by the util classes and use classes with static functions that can be more easily manipulated.

CesiumDrawHelper should accept an optional ellipsoid definition parameter in the constructor

Applications that use CMC for non-Earth bodies need to be able to customize the ellipsoid used by CesiumDrawHelper.

Break out layer model use in MapReducer.mergeLayers

if we move the line mergedLayer = layerModel.mergeDeep(mergedLayer); into a seperate function, users can override the base layer model without having to override the entire mergeLayers method

Firefox label positioning issue

Label not displaying inline with slider

DedupePlugin has been removed from Webpack

See migration notes: https://webpack.js.org/guides/migrating/#dedupeplugin-has-been-removed

Including the plugin spits warnings out in the build report but does not cause errors

Fix colorbar label display for Firefox

The max value label for colorbars displays on a new line in Firefox because of how Firefox handles float: right

Fix: https://stackoverflow.com/questions/26306864/firefox-float-bug-how-do-i-get-my-floatright-on-the-same-line

Alternate fix: use flexbox for positioning instead of float

Layer control clickaway listener children are not wrapped with a parent

Clickaway listener can't seem to handle more than one child. Fix is to wrap all these children in parents or make clickaway listener optionally emit some sort of parent.

Static class actions

If we took a class based approach to actions like we do with utility functions, then we could more easily override actions in child applications. Most of the time this doesn't matter for actions, but for some actions like runUrlConfig it would be helpful to be able to extend/customize that function in a child application.

Additionally, if we combined all of the actions into a single class, then we could have a default action class in the user space pre-populated to inherit from the _core action class (similar to our reducer setup) and all of our components could pull actions from there which means overriding the actions could be simpler. This would likely mean changing our mapDispatchToProps methods to favor specific functions instead of groups of functions like:

function mapDispatchToProps(dispatch) {
    return {
         functionA: bindActionCreators(ActionClass.functionA, dispatch),
         functionB: bindActionCreators(ActionClass.functionB, dispatch)
    };
}

instead of

function mapDispatchToProps(dispatch) {
    return {
         actions: bindActionCreators(actions, dispatch)
    };
}

Move mapStateToProps and mapDispatchToProps to be static class functions of the component

Making these functions part of the component would allow components that inherit from _core components to more easily override/extend their props

Example:

export class ComponentName extends Component {
    static mapStateToProps(state) {...}
    static mapDispatchToProps(dispatch) {...}
    ...
    render() {...}
}

export default connect(ComponentName.mapStateToProps, ComponentName.mapDispatchToProps)(ComponentName);

Ensure that core components like MapControlsContainer accept optional classname parameters

Right now to do something like change the position of the MapControlsContainer you have to extend or duplicate the core component. MapControlsContainer and other components like it (if they don't already) should take an optional classname parameter that it applies to the root of the component.

Map measurement capability not taking into account other projections

date picker shows error erroneously

When you use the inputs to change the date and hit enter the input underlines red, indicating an error even if the date change was successful

Problems changing map projection with SET_MAP_VIEW

Hi CMC folks,

I'm working on migrating the Sea Level Data Access Tool to the new Common Mapping Client. This tool allows the user to switch between latlon/south polar/north polar projections.

I didn't see projections covered in the docs, but from my reading of the code it seems like I'm supposed to use the SET_MAP_VIEW action to change projections. However, I haven't been able to get this working yet. First I tried to switch to a south polar projection by firing the following action:

{
  "type": "SET_MAP_VIEW",
  "viewInfo": {
    "projection": "EPSG:3031",
    "extent": [-90, -45, 90, 45]
  },
  "targetActiveMap": true
}

However, this didn't seem to have any effect on the map view, even though I can see the change to app state in my debugger. Then I suspected that I was using an invalid "extent" parameter, so I tried firing the same action with the default extent for that projection which is defined in appStrings.js:

{
  "type": "SET_MAP_VIEW",
  "viewInfo": {
    "projection": "EPSG:3031",
    "extent": [-4194304, -4194304, 4194304, 4194304]
  },
  "targetActiveMap": true
}

However, this completely froze my tab & spiked the CPU until the tab eventually crashed. Yikes! Any idea what's happening here?

Thanks,
Dan

Use same color for primary and secondary in palette

The last MUI update contained a change to reflect a Material Design guideline stating that selection controls should use the secondary theme color. For our Core demo we only want one color so we'll want to have our theme in app container use the same color for primary and secondary.

Set z-index to 1 for layer control popovers

Interactions for layer control popovers are currently partially blocked by lower layer controls due to z-indexing.