$Source: /cvs/distapps/openmap/README,v $ $RCSfile: README,v $ $Revision: 1.11 $ $Date: 2002/11/06 19:11:02 $ $Author: bmackiew $ OpenMap(tm) What is it? ----------- 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 file called LICENSE in the distribution. 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 Corporation. Just so you're not confused, BBN Corporation is the legal entity, but we're actually part of Verizon Communications. Technically, we do business as "BBN Technologies, a part of Verizon". Downloads and home page ----------------------- The homepage is at http://openmap-java.org/ Downloads of the current distribution are available from the homepage. Where to start? ------------------------ - OpenMap Viewer The com.bbn.openmap.app.Main.java example is the default "face" of OpenMap. While it looks like a complex example to start with, it's really a simple framework that uses the MapHandler to add and connect the OpenMap components. See the old viewer User's Guide (http://openmap.bbn.com/doc/user-guide.html) for more information. You can check out the com.bbn.openmap.app.OpenMap application class for the older version of the main example class. You can write your own components that can display your data in the OpenMap Viewer. Once you've written the layer or plugin, all you need to do is to add a reference to it in your openmap.properties file. The OpenMap Viewer reads this file to get configuration information. The properties file has instructions for adding layers and plugins to the application. Check out the layers in com.bbn.openmap.layer.learn for examples and explanations on how to create your own layers. Likewise, you can change the look of the application by modifying the openmap.components property in the openmap.properties file. There are instructions in the properties file for modifying this property, but the main point is that changing the application does not require a code change. The components are defined in the openmap.properties file and are connected at runtime. If you want to get more into how the components interact with each other, you should take a look at the example applications in the com.bbn.openmap.app.example package, SimpleMap and SimpleMap2 - SimpleMap This class is a very simple example that shows how you use the MapBean and a layer which shows a map of the world. This com/bbn/openmap/app/example/SimpleMap.java uses the MapBean to create a static political map in a window with these steps: 1. Create a JFrame window. 2. Create a MapBean. 3. Create the Political boundary Layer 4. Add the Layer to the MapBean. 5. Add the MapBean to the ContentPane of the JFrame. 6. Show the JFrame window. - SimpleMap2 This com/bbn/openmap/app/example/SimpleMap2.java example is a little more complicated than the previous one, but is more usable. It shows the same political layer along with a background graticule layer (com/bbn/openmap/layer/GraticuleLayer.java) and a simple foreground layer (com/bbn/openmap/layer/learn/BasicLayer.java) which shows hypothetical data features. The openmap.properties file ------------------------ The OpenMap application is configured at runtime by the contents of the openmap.properties file. The openmap.properties file is located in the openmap directory, and has guidance inside it on how to modify various properties to change a) what components are part of the OpenMap application, including what layers are available, b) how those components are configured, and c) the initial map projection used by the application. When the OpenMap application starts up, the PropertyHandler object checks the CLASSPATH to find an openmap.properties file, and then checks the user's home directory for one. If an openmap.properties file was found in the home directory, all of its properties get added to any properties created previously from a CLASSPATH openmap.properties file. If there are duplicate properties, the last version read (from the home directory) will be the version used. By default, there is an openmap.properties file located at the top level of the openmap.jar file. When the jar file is created, the openmap.properties file located in the top level openmap directory gets copied to the classes/openmap directory, and then included into the openmap.jar file. If you make modifications to the openmap.properties file, those changes will not be reflected in the application unless: 1. The top level openmap directory is included in the CLASSPATH of the OpenMap application. This can be done by modifying the openmap startup scripts located in the bin directory. 2. The openmap.properties file is copied into your home directory. For unix users, this directory is usually /home/<username>. For Mac OS X users, this directory is /Users/<username>. For Windows users, this directory is D:\Documents and Settings\<username>, where D: is the disk windows is installed on. If you are not sure where your home directory is, you can compile this code into a HomeDir.java file and run it: public class HomeDir { public static void main(String[] argv) { System.out.println("User home directory is " + System.getProperties().getProperty("user.home")); } } 3. You put the openmap.properties file in the top level of the openmap.jar file, either by a) recompiling the openmap code, or b) unpacking the jar file, replacing the openmap.properties file, and repacking the jar file. The second option is usually the easiest, but your needs may require one of the other options. External Dependencies --------------------- The source code has been broken out into separate directories for code that depends on other packages. - src/openmap and src/ext: This code should compile without any special packages. - src/corba: The missing classes can be generated by building with ant. The idl files are used to create the generated class files. - src/j3d: This code will compile if the Java 3D package is installed. - src/svg: This code will compile if Batik (v 1.7) is installed. If you check OpenMap out from svn (instructions on the download page on the website), these external packages are included. Bugs and Problems --------------------- If you need some help, contact the mailing list at: https://groups.google.com/forum/#!forum/openmap-users The old mailing list at BBN is still available here: http://openmap.bbn.com/mailArchives/openmap-users/ You can also submit issues at the OpenMap home on github at: https://github.com/OpenMap-java/openmap 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.