RAMANI MAPS-API

RAMANI Maps-API is a Java library to build maps with OpenGL vector-tile rendering such asOpenScienceMap, MapForge, MapBox, GeoJSON, and RAMANI WMS maps. This library also providesmethods to request georeference information from the COPERNICUS and Sentinel data services.

Table of Contents

Product summaryScreen CapturesSample AppProject RepositoryCore FunctionalityKnown UsesBackground KnowledgeUML DiagramSystem RequirementLibrary DependenciesGetting StartedReleasesTestingContributingLicenceAcknowledgements

Product summary

Product description. RAMANI Maps-API is a java library to build maps with OpenGL vector-tilerendering such as OpenScienceMap, MapForge, MapBox, GeoJSON, RAMANI WMS maps. Thislibrary also provides methods to request georeference information from the COPERNICUS andSentinel data services.Value proposition. Build and test your own maps using RAMANI Maps-API.Company description. RAMANI Maps-API provides a better map content and vizualization ofCopernicus and Sentinel-data using OpenGL vector-tile renderingMission. RAMANI Maps-API makes it easy for Android Developers to create their own geo-spatial,location-aware smartphone offerings.

Screen Captures

Sample App

Project Repository

Core Functionality

JAVA libraryOpenGL vector-tile renderingAccess online map data through various RAMANI ServicesSupport for multiple tile sources:OpenScienceMap vector tilesMapsforge vector mapsMapbox vector tilesGeoJSON vector tilesRaster tiles: any quadtree-scheme tiles as textureMaps as WFS-T (Transactional WFS), WMS, and WMS-T (WMS with time support)Georeference information from the COPERNICUS and Sentinel data services.Store and Get geometry data in Ramani Cloud

Known Uses

Has been used in many previous apps developed at ESA Space App CampDehydromatic App [brochure]CHEETAH App [Slide]Ramani Location Manager App [brochure]Walkability App [brochure]

Known Issues

On every development project, you can get a fault or defect in a system or machine. For furtherinformation about our current development progress, please check our open issues.

Background Knowledge

Vector Map Vs Bitmap Map

Bitmap (or raster) images are stored as a series of tiny dots called pixels. Each pixel is actually a very smallsquare that is assigned a color, and then arranged in a pattern to form the image. And vector images usemathematical formulas to draw lines and curves that can be combined to create an image from geometricobjects such as circles and polygons. Thus, Vector images have some important advantages over bitmapimages, such as:

Smaller SizeBitmap image has to store color information for each individual pixel that forms the image. While avector image just has to store the mathematical formulas that make up the image, which take up lessspace.

More ScalableWhen a bitmap image is scaled up you begin to see the individual pixels that make up the image. Thisis most noticeable in the edges of the image. There are ways of making these jagged edges lessnoticeable but this often results in making the image blurry as well. When a vector image is scaledup, the image is redrawn using the mathematical formula, so the resulting image is just as smooth asthe original.

OpenGL

Open Graphics Library (OpenGL) is a cross-language, cross-platform application programming interface(API) for rendering 2D and 3D vector graphics. The API is typically used to interact with a graphicsprocessing unit (GPU), to achieve hardware-accelerated rendering.

The OpenGL specification describes an abstract API for drawing 2D and 3D graphics. Although it ispossible for the API to be implemented entirely in software, it is designed to be implemented mostly orentirely in hardware. The Android itself supports OpenGL both through its framework API and the NativeDevelopment Kit (NDK).

OpenGL ES 1.0 and 1.1 - This API specification is supported by Android 1.0 and higher.OpenGL ES 2.0 - This API specification is supported by Android 2.2 (API level 8) and higher.OpenGL ES 3.0 - This API specification is supported by Android 4.3 (API level 18) and higher.OpenGL ES 3.1 - This API specification is supported by Android 5.0 (API level 21) and higher.

Semantic Web

The Semantic Web is a mesh of data that are associated in such a way that they can easily be processed bymachines instead of human operators. It can be conceived as an extended version of the existing WorldWide Web, and it represents an effective means of data representation in the form of a globally linkeddatabase. By supporting the inclusion of semantic content in Web pages, the Semantic Web targets theconversion of the presently available Web of unstructured documents to a Web of information/data.

The term Semantic Web was coined by Tim Berners-Lee.

Basic of Semantic Web:* Going from a web of documents to a web of data* Based on Open Standards* Providing the same freedom as the WWW, but a little less unorganized* Linking between datasets to provide more knowledge and structure:http://lod-cloud.net/versions/2017-02-20/lod.svg

System Requirement

Android Studio (Version 2.3 and up)The minimum Android OS to install RAMANi MAPS-API is Jelly Bean (4.1 and up).

Library Dependencies

Mapforge VTMSquare OkHttplibGDX

Getting Started

These instructions will help you how to development with our Maps-API in your project. See descriptionsbelow for our Maps-API.

Include Library to Android Project

Add this line on your project, build.gradle :

allprojects { repositories { google() jcenter() maven { url 'http://team.ujuizi.com/archiva/repository/internal/' } }}

Then on your app build.gradle , add this line on dependencies :

compile 'com.ujuizi.ramani:maps-api:version_number'

To see the version, please visit our repository on archiva

API Key

You must provide the API_KEY that you get from our client-area webpage before accessing our services.Below is the step-by-step guide :

Sign inSelect Tab Api Keys and then Add Key

Input your Product Name and your Package NamePress Create KeyDone

Android Sample Code

Load Basemap And Ramani Map Layer (using layerID)

public class MainActivity extends AppCompatActivity implements RMAccountManager.RMAccountManagerListener{

/** * for layer id, get it on https://ramani.ujuizi.com/maps/index.html# * select one of the layers, and check on layer information */ private String layerID = "simS3seriesLaiGlobal/lai"; private Map mMap; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_main);

// init map MapView mMapView = findViewById(R.id.mapView); mMapView.setMapPosition(new GeoPoint(51.221297, 4.399128), 13); mMap = mMapView.map(); // adding basemap VectorTileLayer mBaseLayer = mMap.setBaseMap(new OSciMap4TileSource()); mMap.layers().add(new BuildingLayer(mMap, mBaseLayer)); mMap.layers().add(new LabelLayer(mMap, mBaseLayer)); mMap.setTheme(ThemeLoader.load(VtmThemes.DEFAULT), true); // authentication before using our services RMAccountManager.init(this, this,"YOUR_USERNAME","YOUR_API_KEY"); }

@Override public void onMapAuthDone() { // false if auth success and token generated if (RMServicesManager.getToken().isEmpty()) return; RMMapTileLayer rmTileLayer = new RMMapTileLayer(mMap, new RMMapTileSource(layerID)); // you can also set the layer opacity, range 0 - 1 rmTileLayer.tileRenderer().setBitmapAlpha(0.5f); mMap.layers().add(2, rmTileLayer); //index hierarchy, 0 is basemap mMap.render(); }}

Load Ramani Map Layer (using OPeNDAP URL)

If you are using the OPeNDAP URL, the usage is the same as layerID . You only need to add /wmsmap onthe URL.

private Map mMap;private String url = "https://analytics.ramani.ujuizi.com/SOURCES/.Copernicus/.Land/.LAI/.LAI/wmsmap"

@Overridepublic void onMapAuthDone() { // false if auth success and token generated if (RMServicesManager.getToken().isEmpty()) return; RMMapTileLayer rmTileLayer = new RMMapTileLayer(mMap, new RMMapTileSource(url)); mMap.layers().add(2, rmTileLayer); //index hierarchy, 0 is basemap mMap.render();}

Load Ramani Map Layer (using OPeNDAP Shorten URL)

To get OPeNDAP Shorten URL, click Get Shorten URL on your OPeNDAP URL page.

private Map mMap;private String shortenURL = "https://analytics.ramani.ujuizi.com/goto/7604357ee7b1a4aad560559e5bab1199"

@Overridepublic void onMapAuthDone() { // false if auth success and token generated if (RMServicesManager.getToken().isEmpty()) return; mapServices = new RMMapServices(); mapServices.setRMServiceListener(this); mapServices.getMapFromOPeNDAPURL(shortenURL); // to decode your shorten URL}

@Overridepublic void onStringResult(RMMapServices.Task task, String result) { if (task.equals(RMMapServices.Task.MAP)) { RMMapTileLayer rmTileLayer = new RMMapTileLayer(mMap, new RMMapTileSource(result)); mMap.layers().add(2, rmTileLayer); //index hierarchy, 0 is basemap mMap.render(); }}

When using the shorten OPeNDAP URL, you need to decode it first, to get full OPeNDAP URL.

Marker

Markers indicate locations on the map. You can customize your markers by changing the color, usingcustom image as marker icon. And you can use info window to add more information such as title,description, sub description, and image.

// single marker (without info window information)Marker mk1 = new Marker(mMapView, this); mk1.add(new GeoPoint(51.221297, 4.399128));

// using custom DefaultInfoWindow And custom icon Marker mk2 = new Marker(mMapView, this); mk2.setInfoWindow(new MyDefaultInfoWindow(mMapView)); mk2.add("Frascati", "Rome Italy", new GeoPoint( 41.806830, 12.675612), getResources().getDrawable

// or if you want to make marker for multiple locationArrayList<ExtendedMarkerItem> list = new ArrayList<>();list.add(new ExtendedMarkerItem(new GeoPoint(51.221297, 4.399128)));list.add(new ExtendedMarkerItem("Frascati", "Rome Italy", new GeoPoint(41.806830, 12.67561)));Marker mk3 = new Marker(mMapView, this, list);

After you create the marker, you’re able to show/hide, remove, and handle the marker event.

Polyline

A polyline is a list of points, where line segments are drawn between consecutive points.

Polyline line1 = new Polyline(mMap); line1.createLine(geoPoints); //or you can customize itPolyline line2 = new Polyline(mMap, Color.RED, 2); //map, color, size line2.createLine(geoPoints);

Polygon

A plane figure with at least using 3 coordinates. Or have a shape with at least three straight sides andangles, and typically five or more.

Polygon polygon1 = new Polygon(mMap); polygon1.createPolygon(geoPoints);

// or you can customize it with your own stylePolygon polygon2 = new Polygon(mMap, Style.builder() .strokeColor(0) .strokeWidth(2) .fillColor(Color.RED) .build())); polygon2.createPolygon(geoPoints);

Ramani Services

The RAMANI API specification defines an HTTP interface for requesting georeference information fromthe COPERNICUS and Sentinel data services. While RAMANI supports the most common OGC protocols(notably WMS 1.1.1 as well as WMS 1.3.0) to request map images, we also provide access to the physicalunits underlying this data. The data will be retrieved by the API as GeoJSON and other common data-access formats, for backend consumption custom or visualisation.

Below is the sample code from one of our services, GetVerticleProfile . To get more information onthe features along a vertical dimension instead of a single point.

@Overridepublic void onMapAuthDone() { if (RMServicesManager.getToken().isEmpty()) return; // token is not generated, auth failed // init our service class and its listener RMMapServices mapServices = new RMMapServices(); mapServices.setRMServiceListener(this); GeoPoint point = new GeoPoint(51.221297, 4.399128); String layerID = "simS3seriesLaiGlobal/lai"; RMMapInfo.Type format = RMMapInfo.Type.JSON; // supported format : JSON, PNG mapServices.getVerticleProfile(point, layerID, format);}

// no need to set AsyncTask@Override public void onStringResult(RMMapServices.Task task, String s) { if (task == RMMapServices.Task.VERTICLE) { //for JSON format } }

@Override public void onByteResult(RMMapServices.Task task, InputStream inputStream) { if (task == RMMapServices.Task.VERTICLE) { //for PNG format Bitmap bitmap = RMUtils.convertStreamToBitmap(inputStream); } }

For further information about our API, you can check our Android Maps API Documentation and APIReference.

Releases

ALPHAThis channel should test new functionality on the demo project corresponding library. If new functionalityworks, then will be merge to BETA channel.

See our last testing at 23 July 2018,

BETATester needs to verify that every feature (old and new) are working. After this BETA testing phase iscomplete, and all test results prove satisfactory, the corresponding testing issues may be closed one-by-one. With each closed testing issue your personal branch, with each commit, may be merged into thePRODUCTION-channel.

PRODUCTIONThis channel mean that the App is completely ready for use on any of the supported phones (this is sameas the version released to the general public via the Google Play store).

Testing

Testing the App

Install and explore our Sample Maps-API. And fell free to give us some feedback, such as :

The app is confusing, because ____Can you add more information on ____Can you change this part to ____What do you mean by ____etc.

Because your experiences when using the app is very important to us.

Testing Library Code

Make sure you have already included the library dependencies to the project (see LibraryDependenciesUse the latest version from ReleasesTest and explore all the method (for examples, see Getting Started)Provide us with your Feedback (see Contributing)

Contributing

For testing purposes, users are invited to try early releases from our various release channels, eitherAlpha, Beta, or Production (depending on how brave you are you can opt-in for our early accessreleases). To join the Alpha and Beta channel please register your Google account here.Install and explore our sample app.Evaluating our source code.Build your own product or use-case with our library.Give us some feedback about your experiences feedback

Feedback

At any moment in the sample App, you can submit feedback to report your experience as follows:

1. Press the Volume-down key, and a Feedback-form will be shown (touch the Back button to revertany time)

2. Draw any on-screen feature to point out wrong or missing elements in the App3. Touch the OK button to finish your on-screen annotations4. Use the comment section to provide some textual information clarifying the issue or idea and select

the feedback type5. Touch the Send button to submit

A confirmation e-mail is send for tracking purposes and follow-up correspondence.

You can also create some issue or mail us at ramani@ujuizi.com

Licence

Copyright © 2017 RAMANI B.V.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software andassociated documentation files (the “Software”), to deal in the Software without restriction, includingwithout limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copiesof the Software, and to permit persons to whom the Software is furnished to do so, subject to thefollowing conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portionsof the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR APARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS ORCOPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER INAN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTIONWITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Acknowledgements

Authors

Wahyu Anggara RayaFirdaus Kurniawan ZulqornainValentijn VenusFirman Wahyudi

Reviewers

Wahyu Anggara RayaFirdaus Kurniawan ZulqornainKun Alfin HidayatValentijn VenusFirman Wahyudi

Publisher

Ujuizi Laboratories B.V.