You are here: Manual / Library / Plugins / PropagationModel

---

Creating a propagation model plugin

Introduction

The SEAMCAT-3 has implemented a new means of programming the User-defined propagation models. The plugin concept was chosen to avoid the inherent format limitations of the original SEAMCAT-2 interface and make the user-defined model to work as fast as any in-built model. With the plugin propagation model, the user may define very complex propagation modelling using standard Java programming language.

The very detailed and illustrated description of programming and connecting plugins with user defined propagation model is provided below on this page.

Enviroment

Before you can start developing SEAMCAT post processing plugins you will need to ensure that your system has been correctly configured.

Information on how to do this is located in the Basic Enviroment Setup section.

Creating the plugin

To create the plugin you create a file called .java and place it in a directory of your choice, eg. C:/Seamcatsrc and then you open this file in your favorite texteditor.

In this file you paste the contents here below to create the skeleton of a plugin.

import org.seamcat.model.propagation.PluginModel;

public class implements PluginModel {

  public double evaluate( double frequency, double distance, double TxHeight, double RxHeight, int generalEnv, double param1, double param2, double param3) {
    //Your model implementation goes here...
  } 
}

This is the base skeleton you need to implement in order to create a Seamcat plugin. When creating the java-file, it is important to observe the java-code conventions, ie. the name of the class must match the name of the java-file, ie. the class MyPlugin must be defined in a file called MyPlugin.java, also it is recommended to start the classname with a capital letter.

Now you are ready to implement the evaluate method with your own mathematical functions.

Sample plugin

The following is a small sample plugin to show how to create the plugin and how to use System.out.println for debugging purposes.

This sample plugin is an implementation of the DualSlope Pathloss model and was developed as a demonstration during the SEAMCAT workshop at ERO in January 2005.

import org.seamcat.model.propagation.PluginModel;

public class DualSlope implements PluginModel {

public double evaluate( double frequency, double distance, double TxHeight, double RxHeight, int generalEnv, double REFERENCE_DISTANCE, double PATH_LOSS_COEFFICIENT, double param3) {
  double loss; //Convert distances into meters distance *= 1000; 
  REFERENCE_DISTANCE *= 1000; 
  double l = 300 / frequency; 
  if ((distance) < REFERENCE_DISTANCE) { 
    loss = 20 *Math.log10(l / (4* Math.PI * distance)); 
    System.out.println("Distance is below reference distance and loss is " + loss + " dB"); 
  } else { 
    loss = 20 *Math.log10(l / (4* Math.PI *REFERENCE_DISTANCE)) + 10* PATH_LOSS_COEFFICIENT* Math.log10(REFERENCE_DISTANCE / distance); 
    System.out.println("Distance is above reference distance and loss is " + loss + " dB"); 
  } 
  return loss; 
 } 
}

When running the above code 10 times, you will see something like the following in the Java console (depending on how you configured the run), which should give you an idea of how you can use System.out.println statements to debug your plugin if the plugin doesn't produce the results you were expecting.

Note: You should remove any "System.out" statements before using your plugin in actual simulation, as these will clutter logfiles and slow down simulation speed signifigantly.

How to compile the plugin

(In the following it is assumed you are using the same paths as described in Basic Enviroment Setup. If this is not the case, you need to change the paths in this section accordingly.)

Open a dos-prompt window and change to the C:/Seamcatsrc directory. Here you enter the command "javac -classpath ..libseamcat_needed_for_plugin.jar DualSlope.java". This will compile your plugin so that it is ready to be added to the Seamcat application.

Note:: Remember that the name of the file should be the same as the name of the class. I.e. the DualSlope class should be defined in DualSlope.java.

If the compiler complains about problems with your plugin, you need to fix these and try to compile again.

How to add your plugin to Seamcat

Once you have compiled your plugin successfully, you will find a .class file in the same directory as your java file. Copy this file to your Seamcat directory (%USER_HOME%seamcatplugins).

Remember that if you have chosen to use a package for your plugin, you must recreate the package structure under the plugins directory. If you dont know what that last meant, then you probably didnt use a package and can ignore it.

You can also package your class file in a jar file and place this in the plugins directory.

You also need a copy of the seamcat_needed_for_plugin.jar in this directory.

Next start up the Seamcat application and add the plugin. Under the menu item Library choose Propagation model plugins.

Click Add in the next window.

Next fill out the information about your plugin.

• Name is a name to identify your plugin.
• Description is a short description of your plugin (optional).
• Fully Qualified Classname is the fully qualified classname of your plugin, ie. MyPlugin or org.seamcat.user.model.example.MyPlugin if you are using a package.

Now click OK and Close and restart SEAMCAT. Your plugin should be ready for action.

How to test your plugin

Under the menu item Tools / Test Internal Functions is the menu item

Test Propagation Models.

Next choose Propagation Model.

Under Propagation Model Selection choose Plugin.

Choose your plugin under Library plugin-class and change parameters as needed by your plugin.

Finally click on Generate and show samples to view the results of your plugin. If no results are displayed, check the Java console for any error messages

Available Mathematical functions

Q: Which mathematical functions are available to plugin, and what are they called?
A: Any Java class has access to the functions defined by the java.lang.Math class, and these are called as static functions on the class. Example:

… //the following line calls the Log10 function from the java.lang.Math class double logValue = Math.log10(myInput); ...

The complete list of functions available from java.lang.Math can be found here. Besides giving access to the standard math functions a SEAMCAT plugin can access a series of SEAMCAT defined mathematical functions. These are all located in the org.seamcat.mathematics.Mathematics class. The use of this library of functions is similar to the use of the standard library, but there are a few differencies. First of all an additional import statement is needed at the top plugin class file. The following line must be included before SEAMCATs internal math functions can be used:

import org.seamcat.mathematics.Mathematics;

After adding import statement, functions can be called by using the Mathematics prefix.

Example:

… //the following line calls the decimal based tangens function from the org.seamcat.mathematics.Mathematics class \\
double tanDValue = Mathematics.tanD(myInput); ...

The list of SEAMCATs math functions can be found here and the actual implementation of these can be found here.

Problems ?

Q: Why do I get an error telling me the class file has a wrong version ?
A: If you get an error like the one below, it is because you are trying to compile the plugin using a java-version earlier than 1.5.0.

Check your PATH environment variable if there is a reference to a directory containing another javac.exe. Alternatively use full path to the javac compiler when compiling the plugin.

MyPlugin.java:1: cannot access org.seamcat.mathematics.Mathematics bad class file: 
..libseamcat_needed_for_plugin.jar org/seamcat/mathematics/Mathematics.class) 
class file has wrong version 49.0, should be 48.0

Q: Why do I get an "The specified class failed to load" when trying to add a new plugin?
A: Check your %HOME_DIR%seamcatseamcat.log file. If you see an "java.lang.NoClassDefFoundError: org/seamcat/model/propagation/PluginModel" error message, then you have forgotten to copy the seamcat_needed_for_plugins.jar file to the plugins dir. Copy this file and restart Seamcat.

Q: Why do I get an Unknown command error when trying to compile my plugin ?
A: You didn't add %JAVA_HOME%bin to your PATH environment variable.