JMARS ›

Shape Layer

The Shape Layer allows users to create and view files containing points, lines, polygons, circles and ellipses. This tutorial will go over how to draw, load, and save shapes. It will also show how to use the scripts functionality in order to change one or more shapes at once using SQL-type commands.



Image:KaseiMappingV1crop.jpg
Example map created with JMARS shape layer. Credit: Sarah Gelman (MIT, Caltech SURF Program)

Open the Shape Layer

  1. Opening a Shape Layer: Click the 3 dots next "+" then click "Custom Shape Layer" to add the layer to your Layer Manager.
  2. Double click the Custom Shape Layer in the Layer Manager to open the Custom Shape Layer Options window.
  3. Load a Shape File: At the top of the Shape Layer focus panel, click "File" -> "Load File". Select the desired shape file and click "Open".

Loading a Shape File

JMARS supports several popular shapefile formats. The restrictions of these formats are described here.

ESRI shapefile

ESRI shapefiles consist of a .shp, .shx, and .dbf file. To load a shapefile in JMARS, go to the File menu in the shape layer, and choose Load, change the file type to Shapefile, and find the .shp file in your file system. Multiple shp files may be selected at one time.

JMARS does not currently support map projected coordinates, x/y/z coordinates, multi-polygons, or polygons with holes in them. Simple shapes with coordinates represented by east longitude and geocentric latitude are required.

CSV

A csv file is a simple comma-separated text file, typically exported from a spreadsheet program like Microsoft Excel. It can represent point data and any number of additional columns of metadata.

When loading a file, the csv reader in JMARS will look for a 'lon' or 'longitude' column, and a 'lat' or 'latitude' column. The usage of these columns is affected by optional header comments, but the default is to interpret the longitude values as degrees east of the prime meridian, and the latitude values as geocentric latitude north of the equator.

Header comments begin with a '#' symbol and should be placed at the top of the csv file. They allow customizing how to interpret the longitude and latitude values.

If the latitude values you are exporting are geographic, you must specify the radii of the datum for JMARS to understand their position on the map. To specify an ellipsoid, the radii must be provided as header keywords. The A/B/C radii keywords are accepted due to their similarity with PDS / ISIS images, but be certain A and B radii are equal. The polar and equatorial radii may also be specified directly as shown below. Both types of radii keywords should not be used. A typical example set of Mars radii:

# A_AXIS_RADIUS = 3396.1900000
# B_AXIS_RADIUS = 3396.1900000
# C_AXIS_RADIUS = 3376.2000000

OR 

# EQUAT_RADIUS = 3396.19
# POLAR_RADIUS = 3376.20

The default interpretation of longitude values is degrees east of the prime meridian. To specify degrees west of the prime meridian, a header keyword may be added, as shown here: 

# LONGITUDE_DIRECTION = WEST

OR 

# LON_DIR = W

JMARS will attempt to guess the types of all other columns. If a column contains only numbers, it will assume it is a numeric column. If a column contains only 'true' or 'false', it will assume it is a boolean column. All other columns will be loaded into the shape layer as string columns.

Creating a Shape File

  1. Change to Draw mode/em>: When you added the Custom Shape Layer, the Draw shapes panel should open. If not, select the second shape (square) in the toolbar, next to the select arrow.


  2. Add a Point: Select the "Point" in the Draw panel and then click the screen to draw a point. You can also right click your Main View --> Draw shape --> Point.
    • By default, the point will show up as a white square with a red center. This indicates that it's a stand-alone point and not a corner-point of a polygon.


  1. Adding a Polygon: Select the Polygon in the Draw panel or right-click your main screen and select Draw Shape --> Polygon. Click on a location in the Main View where you want one of the polygon corners located. Then move to the next corner location and click again. To finish the polygon, click on the first point to close the shape.
    • By default, the polygon will show up as a white outline will a red fill color.



  1. Adding a Polyline: Select the "Line" symbol in the draw panel or right-click your main screen and select Draw Shape --> Line. Click on a location in the Main View where you want to start the line, then move to the next point of the polyline (non-linear line) and single-click to add a new point. When you reach the end, double-click to create the last point.

  2. Saving the Shape File: There are two ways to save your Custom Shape Layer. 1) At the top of the Shape Layer focus panel, click "Feature" -> "Save All Features As". Specify a location, file name and file type and then click on "Save". (2) Right click the desire row under "Files" --> "Save Selected Files As" to open the save dialog. Then pick a name to save your file under, the file type you want to save it under and then "Save"
    • For new users, the ESRI file format is recommended.

Editting a Point/Polygon

  1. Change to Edit Mode: Select the arrow selection. This is the arrow in the toolbar above the Main View.
  2. Edit a Point: There are 2 ways to select a point. The first one is by clicking on it. (It should now be highlighted in yellow after you click on it). The second option is to select the desire point in the features table in the Custom Shape Layer Options window. After the point is selected, drag it to a new location.




  3. Edit a Polygon: After you have selected the desired polygon, select a corner point by clicking on it. (It should now be highlighted in yellow.) To move the corner point, left-click and drag it to a new location. To add a new corner point, left-click on a line, chose "Add Point" and then drag the new point to it's final position.
  4. Edit a Polyline: Similar to editing a polygon, select the line by clicking on it or selecting it in the table. (It should now be highlighted in yellow.) To move the point, left-click and drag it to a new location. To add a new point, left-click on a line, chose "Add Point" and then drag the new point to it's final position.
  5. Re-Save the Shape File: At the top of the Shape Layer focus panel, click "Features" -> "Save All Features As". Users can either create a new shape file or overwrite the existing shape file.

Editing the Shape Layer Columns

  • The properties of each object currently loaded in the Shape Layer (points, polylines and polygons) are shown in the "Features" table of the focus panel. By default, the only columns visible are the basic display parameters of each object.
  1. Open the Column Editor: In the "Shape Layer" focus panel (Double click your layer in the layer manager if it isn't open), click the "Feature" tab -> "Edit Columns"

  2. Delete Existing Columns: All of the existing columns in the focus panel table are displayed in the left-hand box.
      • Shape Layer field Name: This field allows users to change the name of the shape layer fields, which will be reflected in the Layer Manager.
      • Columns can be deleted or edited in this dialog as well.


Deleting Shapes

Deleting shapes is easy and there's a few ways to do it.

    1. Select the desired shape in the Main View, make sure it is selected in yellow and simply press the "Delete" key on your keyboard. NOTE: CTRL + Z to bring it back.


    Navigate to your Custom Shape Layer Options panel (double click your layer in the layer manager to re-open if it is closed). Find the the Feature in the feature table and select it. Then right-click --> "Delete Selected Features". NOTE: you can select more than one row and delete them at the same time with this feature.


Writing Shape Layer Scripts

Users can write simple scripts to automatically edit the parameters of the various features in a shape file, which is especially useful when a file has a large number of features in it. The command language is similar to SQL, but has many differences:

  • Color columns are specified by a color_spec (e.g. color(255,255,255) ). The order of the elements in a "color spec" are color( red, green, blue). The colors must be an integer between 0 and 255, inclusive.
  • Selecting anything other than the entire row is undefined. Therefore, selection must be preceeded by the string "select rows" or "select *".
  • An "update set" query changes the column to the specified value in all the rows selected by the predicate.
  • A "move rows" query will move all the rows specified in a where clause by the specified delta .

The following are some basic instructions for getting started. For more information on writing and applying shape layer scripts, read the Using the Shape Layer tutorial.

  1. Open a New Script: At the top of the Shape Layer focus panel, chose "Scripts" -> "Edit Script". A blank pop-up window will open.


  2. Write a Script: A script will have three components: an operation, an instruction and a set of rows where the operation will be applied.
    • Operations: An SQL-type command such as "update", "select" or "move".
    • Instructions: An SQL-type command such as "set[field1]=XXX"
    • Set of Rows: An SQL-type specification such as "where field2 like 'XXXXX'"


    When you're ready, press the "Run" tab --> Run. You will see in the Script Results table, that the rows will be updated.



Examples:
  1. update set [Fill Color]= color( 255,255,0) where Label like 'Crater'
    • changes the fill color to yellow in every row that has a label which consists of the single word "Crater"
  2. update set PERIMETER = AREA + 100
    • sets the value of the perimeter column to that of the area column plus 100 in all rows
  3. select rows where AREA > 50.00
    • turns selection on in all the rows where the Area column has a value greater than 50
  4. move rows (0.0, 1.0) where lon > 0
    • moves all the rows with center longitudes greater than zero 1 degree up