From 02fe621a50eba18545e11f1736977d60d0df37b0 Mon Sep 17 00:00:00 2001 From: Google Code Exporter Date: Mon, 3 Aug 2015 10:40:44 -0400 Subject: [PATCH] Migrating wiki contents from Google Code --- DeveloperHints.md | 386 +++++++++++++++++++++++++++++++++++++++++ OpenMap.md | 15 ++ OpenMapApplications.md | 53 ++++++ OpenMapLicense.md | 153 ++++++++++++++++ ProjectHome.md | 13 ++ UsingMapTiles.md | 87 ++++++++++ 6 files changed, 707 insertions(+) create mode 100644 DeveloperHints.md create mode 100644 OpenMap.md create mode 100644 OpenMapApplications.md create mode 100644 OpenMapLicense.md create mode 100644 ProjectHome.md create mode 100644 UsingMapTiles.md diff --git a/DeveloperHints.md b/DeveloperHints.md new file mode 100644 index 000000000..55901aa83 --- /dev/null +++ b/DeveloperHints.md @@ -0,0 +1,386 @@ +# Introduction # + +The OpenMap Developer's Guide is an in-depth resource for how OpenMap components work. This page is a summary of the high points, to give you a quick idea of what's what. + + +# Details # + +Consider OMGraphics... + +

+OMGraphics are important, because they are how you represent data as
+objects on a map. OMGraphics come in different flavors -
+OMBitmap, OMCircle, OMLine, OMPoint, OMPoly, OMRaster, OMRect,
+OMText. An OMGraphicList can be used to contain OMGraphics, and
+is also an OMGraphic itself. This allows you to nest
+OMGraphicLists.
+
+

+When considering how to represent your data as OMGraphics, there are a
+couple of things to think about:
+
+

+You can create customized OMGraphics by combining standard OMGraphics
+into a new object that contains an OMGraphicList, or extend
+OMGraphicList to contain the OMGraphics you need, adding methods you
+require. The com.bbn.openmap.layer.location.Location object is
+an example of creating an object to contain OMGraphics, combining a
+generic OMGraphic marking a location, and a OMText object for the
+location label.
+
+

+OMGraphics contain an attribute map that can contain any other objects you need to associate with the OMGraphic. You can access these attributes using the putAttribute(key, value) and getAttribute(key, value) methods. This can be really
+handy to use to store more information about the data you are
+representing with that OMGraphic (web page addresses, additional
+attributes, etc).
+
+

+OMGraphics can be rendered in three ways, which are
+represented by renderType.
+

+ +There are three different line types associated with OMGraphics that
+have lines rendered in lat/lon space. These setting do not
+affect OMGraphics with RENDERTYPE_XY or RENDERTYPE_OFFSET:
+
+ + +Most importantly, there is a paradigm you have to work
+in with OMGraphics. Once an OMGraphic is created, it MUST be
+projected, which means that its representation, in relation to the
+map, needs to be calculated. This is done by taking the
+Projection object that arrives in the ProjectionChanged event, and
+using it on the OMGraphic.generate(Projection) method. If the
+projection changes, the OMGraphics will need to be generated().
+If the position of the OMGraphic has changed, or certain attributes of
+the OMGraphic are changed, the OMGraphics needs to be generated.
+The OMGraphics are smart enough to know when a attribute change
+requires a generation, so go ahead an call it, and the OMGraphic will
+decide to do the work or not. If you try to render an OMGraphic
+that has not been generated, it will not appear on the map.
+After the OMGraphic is generated, the java.awt.Graphics object
+that arrives in the Layer.paint() method can be passed to the
+OMGraphic.render(java.awt.Graphics) method. See the layer section
+below for more information about managing the Projection object for
+use with your OMGraphics.
+
+

+and Layers... + +

+Layers can do anything they want to in order to render
+their data on the map. When a layer is added to a map, it
+becomes a Java Swing component, so its rendering in relation to other
+layers on the map is taken care of automatically.
+
+

+When a layer is added to the MapBean, it automatically
+gets added as a ProjectionListener to the MapBean. That means
+that when the map changes, the layer will receive a ProjectionChanged
+event, letting it know what the new map projection looks like.
+It's then up to the layer to decide what it wants to draw on the
+screen based on that projection, and then call repaint() on itself
+when it is ready to have its paint() method called. The Java
+AWT event thread will then call paint() on the layer at the proper
+time. paint() can also be called automatically by the AWT
+thread, for map window repaints and when another layer asks to be
+repainted. paint() methods should not do more than simply render
+graphics that are currently on the map, in order to take up as little
+time as necessary with that AWT thread.
+
+

+The OMGraphicHandlerLayer is a super-class implementation of Layer that does a lot of work for you. You should extend any layer you write from this class, and simply override the prepare() method to create and return OMGraphics to display on the map. The prepare() method is called whenever the projection changes (pan, zoom, window resize). The current projection can be retrieved in the prepare method by calling getProjection(), and this can be used to call generate(projection) on your OMGraphics before they are returned from this method. You must do this. Look at the com.bbn.openmap.layer.learn package to see best practices of creating layers to do different things. The OMGraphicHandlerLayers in that package are well commented, and each demonstrate a certain aspect of managing and interacting with OMGraphics.
+

+The OMGraphicHandlerLayer automatically launches a separate thread when it calls prepare(), and automatically calls repaint() on itself when prepare() returns. If you want to force a new thread to be created to call prepare() on the layer, call doPrepare().
+
+

+You can also use the OpenMap layers as examples of different ways to
+create and manage OMGraphics. The GraticuleLayer creates its
+OMGraphics internally, while the ShapeLayer reads data from a
+file. The DTED and RpfLayers have image caches. The
+CSVLocationLayer uses a quadtree to store OMGraphics. You can
+also access a spatial database to create OMGraphics. Any
+technique of managing graphics can be used within a layer.
+
+

+The LayerHandler object is used in the OpenMap
+application to manage layers - both those visible on the map, and
+those available for the map. The LayerHandler uses the
+Layer.isVisible() attribute to decide which layers are active on the
+map. It has methods to change the visibility of layers, add
+layers, remove layers, and change their order. It does not have
+a user interface, so it can be used with any application.
+
+

+For the OpenMap application, layers are added or removed
+by modifying the openmap.properties file. The property file
+contains instructions on how to do this. For OpenMap layers,
+their unique properties that can be set to initialize them should be
+listed in the layer's JavaDocs.
+
+

+The Layer.getGUI() method provides a way for a layer to
+create its user interface which can control its attributes. The
+getGUI() method should just return a java.awt.Component, which means
+you can customize it any way you want. The parent Layer class
+returns null by default if you decide not to provide a
+GUI.
+
+

+and Mouse Events.... + +

+MouseEvents can be managed by certain OpenMap
+components, directing them to layers and to OMGraphics.
+MouseModes describe how MouseEvents and MouseMotionEvents are
+interpreted and consumed.
+
+

+The MouseDelegator is the real MouseListener and
+MouseMotionListener on the MapBean. The MouseDelegator manages a
+list of MouseModes, and knows which one is 'active' at any given
+time. The MouseDelegator also asks the active Layers for their
+MapMouseListeners, and adds the ones that are interested in events
+from the active MouseMode as listeners to that mode.
+
+

+When a MouseEvent gets fired from the MapBean, it goes
+through the MouseDelegator to the active MouseMode, where the
+MouseMode starts providing the MouseEvent to its
+MapMouseListeners. Each listener is given the chance to consume
+the event. A MapMouseListener is free to act on an event and not
+consume it, so that it can continue to be passed on to other
+listeners.
+
+

+From the Layer point of view, it has a method where it
+can be asked for its MapMouseListener. The Layer can implement
+the MapMouseListener interface, or it can delegate that responsibility
+to another object, or can just return null if it's not interested in
+receiving events (the Layer default). The MapMouseListener
+provides a String array of all the MouseMode ID strings it is
+interested in receiving events from, and also has its own methods
+that the MouseEvents and MouseMotionEvents arrive in. The
+MapMouseListener can use these events, combined with the
+OMGraphicList, to find out if events have occurred over any OMGraphics,
+and respond if necessary. Remember, if something on the layer
+changes as a result of an event, the layer can call repaint() on
+itself.
+
+

+Once again, the OMGraphicHandlerLayer makes things easier for you" by handling MouseEvents over its OMGraphics. Look at thecom.bbn.openmap.layer.learn.InteractionLayerfor instructions on how to take advantage of this functionality. + +

+PlugIns can also provide and/or implement the
+MapMouseListener interface - the PlugInLayer passes the request
+through to the PlugIn.
+
+

+and the BeanContext, a.k.a. the MapHandler... + +

+Understanding the MapHandler is one of the most important aspects of
+customizing an OpenMap application if you want to make the whole
+process pretty trivial.
+
+

+The MapHandler is a Java BeanContext, which is a big bucket where you
+can add or remove objects. If an object is a
+BeanContextMembershipListener, it will receive events when other
+objects get added to or removed from the BeanContext.
+
+

+The reason that the MapHandler (as opposed to simply using the
+BeanContext) exists is that it is an extended BeanContext that keeps
+track of SoloMapComponents. SoloMapComponent is an interface,
+and can be used to say that there is only supposed to be one instance
+of a component type in the BeanContext at a time. For instance,
+the MapBean is a SoloMapComponent, and there can only be one MapBean
+in a MapHandler at a time. The SoloMapComponentPolicy is an
+object that tells the MapHandler what to do if another MapBean (or
+other duplicate SMC instance) is added to the MapHandler, either
+rejecting the second instance of the MapBean, or replacing the
+previous MapBean.
+
+

+So, a MapHandler can be thought of as a Map, complete with the
+MapBean, Layers, and other management components that are contained
+within.
+
+

+That said, the MapHandler is incredibly useful. It can be used
+by objects that need to get a hold of other objects and
+services. It can be used to add or remove components to the
+application, at runtime, and all the other objects added to the
+MapHandler get notified of the addition/removal automatically.
+
+

+In the OpenMap application, the openmap.properties file has an
+openmap.components property that lists all the components that make up
+the application. To change the components in the application,
+edit this list.
+
+

+If you want your component to be told of the BeanContext, make it a
+BeanContextChild. It will get added to the MapHandler so that
+other components can find it, if it is on the openmap.components
+property list. If you are creating your own components
+programmatically, simply add the BeanContextChild component to the
+MapHandler yourself.
+
+

+The com.bbn.openmap.MapHandlerChild is an abstract class that contains
+all the methods and fields necessary for an object to be a
+BeanContextChild and a BeanContextMembershipListener. If your
+object extends this class, you just have to implement the methods
+findAndInit() which is called whenever an object is added to the
+MapHandler, and childrenRemoved() which is called when objects are
+removed. You can use the Iterator that gets send to these
+methods to find other components that have been added to or removed
+from the application, and adjust your component accordingly.
+Make sure your component is stable if it doesn't find what it needs -
+you shouldn't assume that the other objects will be added in any
+particular order, or even added at all. Also, you should check
+that when objects are removed that the instance of the object is the
+same that is being used by your component before you disconnect from
+it (not just the same class type). As a MapHandlerChild, your
+component can be added to the OpenMap application without recompiling
+any OpenMap source code. You'll notice that the application
+class (com.bbn.openmap.app.OpenMap) is pretty basic, using the
+PropertyHandler to instantiate all the components and add them to the
+MapHandler.
+
+

+and the PropertyConsumer interface... + +

+The PropertyConsumer interface can be implemented by any component
+that wants to be able to configure itself with a java.awt.Properties
+object. It also has methods that let it provide information about the
+properties it can use, and what they mean.
+
+

+In general, Properties are a set of key-value pairs, each defined as
+Java Strings. The com.bbn.openmap.layer.util.LayerUtils class has
+methods that can be used to translate the value Java Strings into Java
+primitives and objects, like ints, floats, booleans, Color, etc.
+
+

+Several PropertyConsumers may have their properties defined in a
+single properties file, which is what happens when the OpenMap
+application uses the openmap.properties file. In order for each
+PropertyConsumer to be able to figure out which properties are
+intended for it, the PropertyConsumer can be given a unique scoping
+property prefix string. In the openmap.properties instructions, this
+scoping string is referred to as a marker name. If the property prefix
+is set in a PropertyConsumer, it should prepend that string to each
+property key, separating them with a period. For example a layer may
+have a property key called lineWidth, which tells it how thick to draw
+its line graphics. If it is given a property prefix of layer1, it
+should check its properties for a 'layer1.lineWidth' property. If the
+layer is given a null prefix (default), then it should look for a
+'lineWidth' property.
+
+

+The methods for the PropertyConsumer are:
+
+

+ +

+PropertyConsumers can use the
+com.bbn.openmap.util.propertyEditor.Inspector to provide an interface
+to the user to configure it at runtime. It also allows the
+PropertyConsumer to provide its current state for properties files
+being saved for later use.
+
+

+Lastly, when the OpenMap application is creating objects from the
+openmap.components property, the marker name on that list becomes the
+property prefix for components. The ComponentFactory, which creates
+the components on behalf of the PropertyHandler, checks to see if the
+component is a PropertyConsumer, and if so it calls
+setProperties(prefix, properties) on it to let the component configure itself.
+
+

+and hints to help with certain application Design Patterns... + +

+The OpenMap application is really a framework. The application can
+be adjusted and components swapped in and out by modifying the
+openmap.components property to create the components you want. If
+you want to create your own application, it's likely that you can
+still use the OpenMap application for it and still completely
+customize it.
+
+

+You don't have to use Properties - feel free to create any object you want, programmatically, and simply add it to the MapHandler.
+
+

+If you want your layer to be driven by an external object, check out
+the com.bbn.openmap.plugin.graphicLoader package. A GraphicLoader is
+an object that is able to provide OMGraphics to an OMGraphicHandler
+(which can be thought of as a receiver). The graphicLoader package
+contains the AbstractGraphicLoader, an abstract GraphicLoader
+implementation that has a Swing Timer in it to trigger itself to
+deliver OMGraphic updates. You can extend this class to customize how
+and when these updates occur. If you place the GraphicLoaderConnector
+in the MapHandler along with your GraphicLoaders, the
+GraphicLoaderConnector will create a GraphicLoaderPlugIn/PlugInLayer
+combination to listen to each GraphicLoader if the GraphicLoader
+doesn't already have a receiver specified. \ No newline at end of file diff --git a/OpenMap.md b/OpenMap.md new file mode 100644 index 000000000..5fe9d1448 --- /dev/null +++ b/OpenMap.md @@ -0,0 +1,15 @@ +# What is OpenMap? # + +OpenMap is a Java Beans based toolkit for building applications and applets needing geographic information. Using OpenMap components, you can access data from legacy applications, in-place, in a distributed setting. At its core, OpenMap is a set of Swing components that understand geographic coordinates. These components help you show map data, and help you handle user input events to manipulate that data. + +# What are the license terms for using OpenMap? # + +Take a look at the OpenMapLicense. We want you to be able to do pretty much anything with it as long as we get credit for our work and as long as you offer your changes to us so we can possibly add them to the standard version we distribute. + +# OpenMap is a trademark # + +OpenMap is a trademark of BBN Technologies. + +# Please help out! # + +There's much room for improvement of the OpenMap sources. We are interested in any changes you make to the core source, or layers you develop, or other derivative works. \ No newline at end of file diff --git a/OpenMapApplications.md b/OpenMapApplications.md new file mode 100644 index 000000000..0d9d48b47 --- /dev/null +++ b/OpenMapApplications.md @@ -0,0 +1,53 @@ +# Introduction # + +The OpenMap package includes applications that demonstrate the capabilities of the toolkit. There are many layer examples that also demonstrate how to create custom layers for displaying your own data. + + +# Applications # + +The application classes in OpenMap are in the {{com.bbn.openmap.app}}} package. + +The `com.bbn.openmap.app.Main` class was introduced in OpenMap 5.0. It uses the openmap.properties file for configuration, with the `main.components` defining the application components. The `openmap.layers` property defines the layers used in the application. This is the application that gets started by the scripts in the bin directory. You can start this application at the command line by typing: + +`java -classpath ./lib/openmap.jar:./share com.bbn.openmap.app.Main -properties ./openmap.properties` + +The `com.bbn.openmap.app.OpenMap` class is the legacy application that uses the `openmap.properties` file to define the components in the application. The `openmap.components` property in `openmap.properties` lists the components that will be added to the application, and the `openmap.layers` property defines the layers in the application. + +`java -classpath ./lib/openmap.jar:./share com.bbn.openmap.app.OpenMap -properties ./openmap.properties` + +Both applications are the best way to start getting to know OpenMap, and the best starting point for your own application. You can add or remove components in the application using the {{openmap.properties}}} file, which contains instructions for how to modify the various properties within it. + +If you want to a deeper understanding on how the OpenMap application framework should be used, the `com.bbn.openmap.app.example` package contains `SimpleMap` and `SimpleMap2`. Both examples are heavily commented, and provide examples of how to programmatically configure OpenMap mapping components. + +`java -classpath ./lib/openmap.jar:./share com.bbn.openmap.app.example.SimpleMap` + +`java -classpath ./lib/openmap.jar:./share com.bbn.openmap.app.example.SimpleMap2` + +# Layers # + +OpenMap includes many layers that work with standard map data formats. These layers are under the `com.bbn.openmap.layers` package. The `openmap.properties` file contains examples of how to configure properties for some of them, and the javadocs for a layer class should contain property settings and instructions for configuring the layer. + +If you want to learn to write your own layer, look at the layers in the `com.bbn.openmap.layers.learn` package: + * `BasicLayer` shows how to make a layer where the data doesn't change depending on time or map projection. A good first layer. + * `ProjectionResponseLayer` shows how to make a layer that responds to the map projection to display map features for the current view. + * `InteractionLayer` shows how to make the layer react to user input. + * `SimpleAnimationLayer` shows how to move features around on a map. + +Also, the `com.bbn.openmap.layer.DemoLayer` is an excellent tool, demonstrating almost anything you may want to do with a layer. It is heavily commented, and studying that layer will reveal how to respond to user input, use the drawing tool to edit map features, create a Layer gui to change properties of the layer, use the MIL-STD-2525 symbology components, and display various OMGraphic map features with labels. This layer is also part of the standard `OpenMap` and `Main` application configuration, so you can see that layer in action by running those applications. + +# Servlets # + +OpenMap can be used to power servlets (using glassfish or tomcat) that provide map data to other applications. From the src directory: + + * `wmsservlet` provides a servlet that can be used to provide WMS images. In addition to whole map images, the wmsservlet can respond to request to create TMS (Tile Map Specification) sized images on the fly. + * `maptileservlet` provides a servlet that can handle requests for TMS (Tile Map Specification) layers, such as Leaflet, OpenLayers and Google Maps. These tile map sets are assumed to be pre-created using mapnik, TileMill, GDAL, or OpenMap's MapTileMaker. The OpenMap `MapTileLayer` can talk to this servlet (and any other TMS server). Also, when the `maptileservlet` is loaded with `MapTileSet` tiles, contacting the servlet at the top-level will bring up a Leaflet map allowing you to look at the tile sets. + +The `MapTileMaker` is a class that creates tile sets. It uses a properties file to define layers and lets zoom levels be defined to dictate which layers are active for different tile scales. The `MapTileMaker` has recently been updated to implement `EmptyTileHandler`, which means it can now be used by the `maptileservlet` to create tiles on the fly, and cache them for later use. + +The `vpfservlet` doesn't serve VPF data, it provides a way to explore VPF datasets. + +# Other # + +You can use OpenMap map components in any java application that supports Swing components (so mobile SDKs generally don't work with OpenMap). You can embed OpenMap into an existing application. Look at the `BasicMapPanel` and `OverlayMapPanel` as the main component to embed into another application. + +OpenMap runs as an applet. The share directory contains an omapplet.html page to get started. There is a jnlp file to run OpenMap as a Java WebStart application. \ No newline at end of file diff --git a/OpenMapLicense.md b/OpenMapLicense.md new file mode 100644 index 000000000..53a146ae9 --- /dev/null +++ b/OpenMapLicense.md @@ -0,0 +1,153 @@ +# OpenMap Software License Agreement # + +This Agreement sets forth the terms and conditions under which +the software known as OpenMap(tm) will be licensed by BBN +Technologies ("BBN") to you ("Licensee"), and by which Derivative +Works (as hereafter defined) of OpenMap will be licensed by you to BBN. + +## Definitions ## + +> "Derivative Work(s)" shall mean any revision, enhancement, +> modification, translation, abridgement, condensation or +> expansion created by Licensee or BBN that is based upon the +> Software or a portion thereof that would be a copyright +> infringement if prepared without the authorization of the +> copyright owners of the Software or portion thereof. + +> "OpenMap" shall mean a programmer's toolkit for building map +> based applications as originally created by BBN, and any +> Derivative Works thereof as created by either BBN or Licensee, +> but shall include only those Derivative Works BBN has approved +> for inclusion into, and BBN has integrated into OpenMap. + +> "Standard Version" shall mean OpenMap, as originally created by +> BBN. + +> "Software" shall mean OpenMap and the Derivative Works created +> by Licensee and the collection of files distributed by the +> Licensee with OpenMap, and the collection of files created +> through textual modifications. + +> "Copyright Holder" is whoever is named in the copyright or +> copyrights for the Derivative Works. + +> "Licensee" is you, only if you agree to be bound by the terms +> and conditions set forth in this Agreement. + +> "Reasonable copying fee" is whatever you can justify on the +> basis of media cost, duplication charges, time of people +> involved. + +> "Freely Available" means that no fee is charged for the item +> itself, though there may be fees involved in handling the item. +> It also means that recipients of the item may redistribute it +> under the same conditions that they received it. + +1. BBN maintains all rights, title and interest in and to +OpenMap, including all applicable copyrights, trade secrets, +patents and other intellectual rights therein. Licensee hereby +grants to BBN all right, title and interest into the compilation +of OpenMap. Licensee shall own all rights, title and interest +into the Derivative Works created by Licensee (subject to the +compilation ownership by BBN). + +2. BBN hereby grants to Licensee a royalty free, worldwide right +and license to use, copy, distribute and make Derivative Works of +OpenMap, and sublicensing rights of any of the foregoing in +accordance with the terms and conditions of this Agreement, +provided that you duplicate all of the original copyright notices +and associated disclaimers. + +3. Licensee hereby grants to BBN a royalty free, worldwide right +and license to use, copy, distribute and make Derivative Works of +Derivative Works created by Licensee and sublicensing rights of +any of the foregoing. + +4. Licensee's right to create Derivative Works in the Software is +subject to Licensee agreement to insert a prominent notice in +each changed file stating how and when you changed that file, and +provided that you do at least ONE of the following: + +> a) place your modifications in the Public Domain or otherwise +> > make them Freely Available, such as by posting said +> > modifications to Usenet or an equivalent medium, or +> > placing the modifications on a major archive site and by +> > providing your modifications to the Copyright Holder. + + +> b) use the modified Package only within your corporation or +> > organization. + + +> c) rename any non-standard executables so the names do not +> > conflict with standard executables, which must also be +> > provided, and provide a separate manual page for each +> > non-standard executable that clearly documents how it +> > differs from OpenMap. + + +> d) make other distribution arrangements with the Copyright +> > Holder. + +5. Licensee may distribute the programs of this Software in +object code or executable form, provided that you do at least ONE +of the following: + + +> a) distribute an OpenMap version of the executables and +> > library files, together with instructions (in the manual +> > page or equivalent) on where to get OpenMap. + + +> b) accompany the distribution with the machine-readable +> > source code with your modifications. + + +> c) accompany any non-standard executables with their +> > corresponding OpenMap executables, giving the non-standard +> > executables non-standard names, and clearly documenting +> > the differences in manual pages (or equivalent), together +> > with instructions on where to get OpenMap. + + +> d) make other distribution arrangements with the Copyright +> > Holder. + +6. You may charge a reasonable copying fee for any distribution +of this Software. You may charge any fee you choose for support +of this Software. You may not charge a fee for this Software +itself. However, you may distribute this Software in aggregate +with other (possibly commercial) programs as part of a larger +(possibly commercial) software distribution provided that you do +not advertise this Software as a product of your own. + +7. The data and images supplied as input to or produced as output +from the Software do not automatically fall under the copyright +of this Software, but belong to whomever generated them, and may +be sold commercially, and may be aggregated with this Software. + +8. BBN makes no representation about the suitability of OpenMap +for any purposes. BBN shall have no duty or requirement to +include any Derivative Works into OpenMap. + +9. Each party hereto represents and warrants that they have the +full unrestricted right to grant all rights and licenses granted +to the other party herein. + +10. THIS PACKAGE IS PROVIDED "AS IS" WITHOUT WARRANTIES OF ANY +KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING (BUT NOT LIMITED TO) +ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, AND +WITHOUT ANY WARRANTIES AS TO NONINFRINGEMENT. + +11. IN NO EVENT SHALL COPYRIGHT HOLDER BE LIABLE FOR ANY DIRECT, +SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES WHATSOEVER RESULTING +FROM LOSS OF USE OF DATA OR PROFITS, WHETHER IN AN ACTION OF +CONTRACT, NEGLIGENCE OR OTHER TORTIOUS CONDUCT, ARISING OUT OF OR +IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS PACKAGE. + +12. Without limitation of the foregoing, You agree to commit no +act which, directly or indirectly, would violate any U.S. law, +regulation, or treaty, or any other international treaty or +agreement to which the United States adheres or with which the +United States complies, relating to the export or re-export of +any commodities, software, or technical data. \ No newline at end of file diff --git a/ProjectHome.md b/ProjectHome.md new file mode 100644 index 000000000..d8c8162d0 --- /dev/null +++ b/ProjectHome.md @@ -0,0 +1,13 @@ +BBN Technologies' OpenMap TM package is an Open Source JavaBeans TM based programmer's toolkit. Using OpenMap, you can quickly build applications and applets that access data from legacy databases and applications. OpenMap provides the means to allow users to see and manipulate geospatial information. OpenMap is under constant development - the latest version is **OpenMap 5.1.11, released July 20, 2015**. Note that with v5.0, you need to be using Java 5 or later. A complete list of updates is maintained in the [CHANGELOG](http://code.google.com/p/openmap/source/browse/CHANGELOG) file in the package. + +You can [download](https://drive.google.com/folderview?id=0B-Y9CwNIsUOHenpDWGhBSk42b1E&usp=sharing) a copy for free, use it, and make changes to it. Be sure to read the [license](OpenMapLicense.md) before you do. + +Follow [OpenMap on Twitter](http://twitter.com/openmap) for announcements about new releases and updates to the code base. If you need help, you can post questions on the [Google OpenMap-Users Group](https://groups.google.com/forum/#!forum/openmap-users) forum. For a historical perspective, the [old BBN openmap-users mailing list archive](http://openmap.bbn.com/mailArchives/openmap-users/thread.html) is still available. + +Google Code has removed the ability to provide downloadable compressed release files in the Download tab (as of version 5.0.3). The latest download packages are available via the External Links -> [Downloads](https://drive.google.com/folderview?id=0B-Y9CwNIsUOHenpDWGhBSk42b1E&usp=sharing) link to the left. The current Java API documents can be found [here](http://dietricks.com/openmap/api) or they can be [downloaded](https://drive.google.com/folderview?id=0B-Y9CwNIsUOHenpDWGhBSk42b1E&usp=sharing) as a zip file. + +Developer documentation can be found on the [Wiki page](http://code.google.com/p/openmap/w/list) and in the [Downloads section](http://code.google.com/p/openmap/downloads/list). + +Since OpenMap is open source, we welcome additions and changes from the user community. We've incorporated a number of contributions, with plenty of submissions available to the user community separate from the official distribution. + +BBN Technologies is an innovative research and development company, providing both advanced research and custom, research-based solutions for our customers. We have over 50 years of experience in technological innovation, and provide expertise in a number of technology focus areas, including acoustic technologies, agent-based systems, logistics, planning, and decision support, and speech and language processing, among others. For a complete list of our offerings, be sure to visit our corporate site. \ No newline at end of file diff --git a/UsingMapTiles.md b/UsingMapTiles.md new file mode 100644 index 000000000..4d39cba1c --- /dev/null +++ b/UsingMapTiles.md @@ -0,0 +1,87 @@ +# Introduction # + +Map tiles are images stored in a directory structure, usually by zoom level, x coordinate and then named by their y coordinate (z/x/y.png). + +The _com.bbn.openmap.layer.imageTile.MapTileLayer_ can be used to display map tiles, stored locally on your computer or downloaded from a server. There are many options available for the MapTileLayer, and they can be set in the _openmap.properties_ file, or in a _tiles.omp_ file stored in the root directory of a tile set. + +# Configuration Options # + +The most basic configuration of a MapTileLayer simply define a **rootDir** property defining where the tiles are located and how they should be referenced. + +``` +class=com.bbn.openmap.layer.imageTile.MapTileLayer +prettyName=Map Tiles +rootDir=/data/tiles/MapTileSet1/{z}/{x}/{y}.png +``` + +Other options: + +**rootDir**: The rootDir can be a URL, absolute or relative path to the tile files. It can also be a jar file. If you use a jar file to hold the tiles, you should use a tiles.omp inside the jar to hold other properties, like another rootDir property for the relative path to the files within the jar. The **rootDir** can also point to a TileMill mbtiles file. If it does, you'll need to set the **tileFactory** to use the _com.bbn.openmap.dataAccess.mapTile.TileMillMapTileFactory_. You'll also need to include the sqlitejdbc jar file in the classpath to use the TileMillMapTileFactory. + +**localCacheRootDir**: If the **rootDir** is defined as a URL, you can also use a **localCacheRootDir** property to define local storage for the tiles. If the layer will check the **localCacheRootDir** first for tiles, and then move to the **rootDir** location if needed. This will drastically reduce the server load. + +**tileFactory**: The MapTileLayer uses a MapTileFactory to handle the fetching of tiles. For URLs and file paths, you generally don't have to set this, the layer will figure out which one to use. You can check out the _com.bbn.openmap.dataAccess.mapTile_ package for various MapTileFactory implementations, and look at their javadocs for more information about specific properties for those factory objects. + +**cacheSize**: the number of tiles to hold in memory for the layer, defaults to 50. + +**attribution**: if you aren't using your own tiles, this property can be used to display the tiles' owner's name in the lower left corner of the map. + +**mapTileTransform**: The default MapTileCoordinateTransform is the _com.bbn.openmap.dataAccess.mapTile.OSMMapTileTCoordinateTransform_ class, and that defines the tile coordinates from the upper left corner of the Mercator projection, with zoom levels starting at 0 and zooming into higher levels. If you are working with tiles defined differently, you can specify a different class to use for those tiles. For instance, if you use GDAL to create image tiles sets you may need to use the _com.bbn.openmap.dataAccess.mapTile.TMSMapTileCoordinateTransform_. + +**tileImagePreparer**: defines a class that can be used to process the images before display. The _com.bbn.openmap.dataAccess.mapTile.GreyscaleImagePreparer_ will convert all tiles to greyscale. + +**emptyTileHandler**: defines a class that determines what to do when a tile is missing. The _com.bbn.openmap.dataAccess.mapTile.ShpFileEmptyTileHandler uses a shape file to draw a basic shape onto a temporarily used tile._ + +``` +emptyTileHandler=com.bbn.openmap.dataAccess.mapTile.ShpFileEmptyTileHandler +shpFile=File, resource or URL to shape file for land representation. + + # Properties to set how the shp file contents are rendered. + land.fillColor=hex RGB color + land.lineColor=hex RGB color + land.fillPattern=path to resource, file or URL of pattern to use for tile fill. + + # From SimpleEmptyTileHandler superclass, handling the 'water' + # clear by default if not specified + background.fillColor=hex RGB color + background.lineColor=hex RGB color + background.fillPattern=path to resource, file or URL of pattern to use for tile fill. + + # Zoom level to start using noCoverage attributes. Is 0 by default if the shape file + # is not specified. If the shape file is specified and this isn't the zoom level + # will be set to 20. + noCoverageZoom=zoom level when you don't want empty tiles, you want no coverage tiles + + # How to render standard empty tiles, will be clear if not defined + noCoverage.fillColor=hex RGB color + noCoverage.lineColor=hex RGB color + noCoverage.fillPattern=path to resource, file or URL of pattern to use for tile fill. +``` + +# Adding a MapTileLayer to the Application # + +To add a MapTileLayer to the map, you can modify the _openmap.properties_ file. First, pick short word name for your layer, any little word, your choice. It should be unique compared to all of the other names listed in the _openmap.layers_ property. Next, add your name to that _openmap.layers_ list where you want your layer to be listed in the layer stack (first on the list is on top of the map). Then, add properties for your layer in the _openmap.properties_ file, using the name you picked for your layer as a scoping prefix for the properties. For example, let's say you chose 'osm\_tiles' for your name. + +``` +openmap.layers=... osm_tiles ... + +osm_tiles.class=com.bbn.openmap.layer.imageTile.MapTileLayer +osm_tiles.prettyName=OSM Tiles +osm_tiles.rootDir=http://c.tile.openstreetmap.org/ + +# Add other properties, starting with 'osm_tiles.', as needed for your configuration +``` + +If you want the layer to show up when the application is started, also add the **osm\_tiles** name to the _openmap.startupLayers_ list. + +To add a MapTileLayer to the SimpleMap2 example, you don't really need a property prefix for the properties: + +``` + // Just add this code + MapTileLayer mapTileLayer = new MapTileLayer(); + Properties tileProperties = new Properties(); + tileProperties.setProperty("rootDir", "http://c.tile.openstreetmap.org/"); + mapTileLayer.setProperties(tileProperties); + mapTileLayer.setVisible(true); + mapHandler.add(mapTileLayer); +``` \ No newline at end of file