Frequently Asked Questions
- General
-
Installation and configuration
- How do I add datasets to my ncWMS server?
- I have a set of OPeNDAP URLs that I'd like to view as a single dataset in …
- How is the default colour scale range set for each variable?
- Where is the ncWMS configuration information held?
- How can I run more than one ncWMS instance on the same server?
- How can I measure the performance of my ncWMS server?
- Client tools
- Data issues
- Technical points
General
Where can I find out more about the Web Map Service?
Going straight to the specification could be a little daunting, but DEMIS has a nice concise introduction to WMS here: http://www.demis.nl/home/pages/wms/docs/OpenGISWMS.htm.
Why do we need another WMS implementation?
Most existing open-source WMS implementations do not support four-dimensional gridded NetCDF data. ncWMS is designed to support interactive browsing of data over the Web and therefore needs to be able to generate images quickly to allow for slick usage. See http://www.reading.ac.uk/godiva2 to see the speed of ncWMS in action.
However, we are aware that there are existing popular pieces of software that can be adapted to deliver the same capabilities as ncWMS and that this is beneficial to the sustainability of the ncWMS software and to the community as a whole. Therefore we are working with the THREDDS and GeoServer? teams to transfer some of the ncWMS technology into these systems in the context of the SHAVER project.
Which versions of WMS are supported?
The latest release (1.0RC1) supports WMS 1.3.0 and 1.1.1.
Is ncWMS fully compliant with the WMS specification?
ncWMS extends WMS slightly to support features that are useful for scientific data, such as the selection of colour scales. However, ncWMS is fully backward-compatible with the WMS spec. See WmsExtensions for more details.
Will ncWMS be compatible with my server setup?
ncWMS is a standard Java web application, built using the Spring framework. It is known to work on Tomcat 6.0, and will probably work with other application servers too.
I hear that ncWMS is now integrated with THREDDS?
Yes - you can either use THREDDS v4 ( http://www.unidata.ucar.edu/projects/THREDDS/tech/TDS.html) and get WMS support built-in or you can continue to use ncWMS as a separate web application. The behaviour of the systems is very similar. If you already run a THREDDS server and plan to upgrade you may well find it easier to run the integrated system. However, if you do not run THREDDS already, you may prefer to use ncWMS on its own as this will give you access to the latest features and is (arguably) easier to set up.
Installation and configuration
How do I add datasets to my ncWMS server?
The administrative web pages allow new datasets to be added. A "dataset" is a single NetCDF file, a single OPeNDAP endpoint, an NcML file or a glob aggregation (in other words, something like "/path/to/*.nc").
I have a set of OPeNDAP URLs that I'd like to view as a single dataset in ncWMS
Sometimes an OPeNDAP provider will provide each timestep of a model output (for example) as a set of individual datasets, rather than a single aggregated dataset. In this case you probably won't want to create a new dataset in ncWMS for each timestep. There are three possible solutions:
- Construct an NcML file to aggregate the remote URLs.
- Persuade your data provider to aggregate the timesteps or run an aggregation server.
- Run an OPeNDAP aggregation server yourself.
How is the default colour scale range set for each variable?
When a dataset is first loaded the default colour scale range is "guessed" by ncWMS using the following scheme: a "test extraction" of a low-resolution field from the first vertical level and first timestep from each variable in the first NetCDF file in the dataset is performed. ncWMS then finds the lowest and highest values in this field, then adds a small margin of error (10%) at each end. So if this first file isn't representative of the dataset as a whole, the guess will not be perfect. You can always edit the guess through the administrative web page or by editing config.xml. (See the "Controlling the default style for variables" section of the installation instructions.)
Where is the ncWMS configuration information held?
By default, this information is stored in $HOME/.ncWMS. The location of $HOME is system-dependent. The table below shows some examples, although your system setup may vary.
| Windows 7 | C:\Users\username |
| Windows XP | C:\Documents and Settings\username |
| Linux/Unix? | /home/username, /users/username |
| Mac OSX | /private/var/username |
The location of the configuration information can be changed by editing WEB-INF/WMS-servlet.xml and changing the workingDirectory property of the ncwmsContext bean, e.g.:
<bean id="ncwmsContext" class="uk.ac.rdg.resc.ncwms.config.NcwmsContext" init-method="init">
<property name="workingDirectory" value="/path/to/new/location"/>
</bean>
How can I run more than one ncWMS instance on the same server?
Install two copies of the WAR file in your application server: you'll need to rename one of them to ensure that the two instances are accessed under different URLs. Initially both instances will try to use the default working directory. You'll need to change the working directory of one or both instances (see "Where is the ncWMS configuration information held?" above).
How can I measure the performance of my ncWMS server?
Client tools
How do I use the Godiva2 web client?
See GodivaTwoUserGuide for a user guide.
How can I customize the Godiva2 web client for my own needs?
See CustomizingGodivaTwo.
How can print out a view of a Godiva2 site?
There is a "Screenshot" link under the map on Godiva2. This will generate a static image representation of the current view, which can be printed or embedded in, say, Powerpoint.
How do I change the default base map on my Godiva2 site?
Sometimes the system-supplied base map (NASA Blue Marble) is not what you want, and sometimes the map service that serves this base map is off-line. You can change the default base map by editing godiva2.js and changing the line:
map.setBaseLayer(bluemarble_wms);
to
map.setBaseLayer(demis_wms); // or another map service
Is there support for visualization in Google Earth?
Yes, ncWMS can generate KML for visualization in Google Earth. Set the output format of a GetMap operation to application/vnd.google-earth.kmz.
My WMS client uses latitude-longitude axis order
There has been much confusion over lat-lon axis order in the EPSG:4326 coordinate reference system (WGS:84 latitude-longitude projection). The "correct" behaviour seems to be to use lon-lat axis order in WMS 1.1.1 but lat-lon axis order in WMS 1.3.0. Unfortunately ncWMS currently uses lon-lat axis order for all versions. This is because until recently, the vast majority of clients were 1.1.1-compatible (including OpenLayers?) and produced requests in lon-lat order.
If you have a client that (correctly) uses lat-lon axis order in EPSG:4326 for WMS 1.3.0 we recommend you do one of the following:
- Use WMS 1.1.1 (which uses lon-lat ordering for EPSG:4326)
- Use WMS 1.3.0 with the CRS:84 coordinate reference system (this is explicitly defined to use lon-lat axis order)
- If your client is based on OpenLayers, you can set LAYER.yx = [] on the layer in question to force lon-lat axis order (thanks to Charlton Galvarino for this workaround).
A ticket has been raised for this (#187), but the fix might not be painless, since it might break existing clients.
Data issues
How is data read from NetCDF files?
ncWMS relies heavily on the Java NetCDF libraries to read data and metadata. In particular we make use of the high-level code (the GridDatatypes?, etc). See DefaultDataReader.java.
My data don't appear as I expected (e.g. variables are missing)
ncWMS uses the Unidata Common Data Model (implemented in the Java NetCDF libraries) to detect when a variable is georeferenced. If a variable does not appear correctly georeferenced through ncWMS, or if a variable does not appear at all, usually there is a problem with the CF metadata. Use the CDM validity checker to check that the Common Data Model recognizes the gridded data sets in your data: only the variables in the "Grid variables" section of the validity checker's report will be recognized by ncWMS.
In particular, please note the following common points:
- Make sure that longitude axes have the units degrees_east and that latitude axes have the units degrees_north.
- Make sure that vertical axes have a "positive" attribute (with a value of "up" or "down") or units of pressure. This is how CF defines a vertical axis, and failure to follow this is perhaps the most common reason for variables not appearing in ncWMS.
The CF compliance checker may also be of some use in checking the syntax of your metadata, although this cannot in general check that your metadata correctly conveys your intent.
If you find you need to modify or add attributes, you can either edit the data files directly (perhaps using the NetCDF operators) or use an NcML wrapper.
What types of data grids (e.g. lat-lon, Lambert equal-area, polar stereographic etc) are supported by ncWMS?
ncWMS can read data in any projection that is supported by the Java NetCDF libraries, including "curvilinear" grids: see this presentation for more details. It can produce images in any projection that is supported by the GeoTools? library.
I get "filename does not match any files" but my data definitely exist!
Make sure you have used the correct case when specifying the dataset path: ncWMS is case-sensitive, even under Windows.
Technical points
How is imagery generated so quickly?
We need to generate map images very quickly in order to support interactive browsing on the web. The slow step in the generation of images is actually the reading of data from disk. Therefore we've spent a bit of time finding fast algorithms for reading data from a Variable and projecting it onto the grid that the user has selected through the WMS GetMap? function. The key class here is DataReadingStrategy.java; read the Javadoc for more details.
I get "out of memory" errors
Memory management in Java is tricky - users can find that they get out-of-memory errors one day but not the next, even with the same ncWMS version and machine. The DownloadPage suggests that you allow your application server (e.g. Tomcat) to use 512MB of memory. You may need to increase this for large data holdings (you need to set certain options in the Java virtual machine to achieve this: Java won't automatically use all available memory like C or FORTRAN will - see the DownloadPage).
We haven't done any formal tests to figure out how much memory is required for a certain size of data holdings. There are too many variables to make this an easy job.
PermGen space errors can occur if ncWMS is redeployed many times in a Tomcat server without shutting it down. We recommend that if you see these errors, restart Tomcat every time you redeploy or upgrade ncWMS on a production server. Search the mailing list archives for "PermGen" for more details, or see ticket #165.
