Module 10, Starting your own project

learning objective: set up a new GeoDMS project from scratch, with a clean folder structure and a configuration skeleton that can grow with your project

introduction

In all previous modules you worked inside ready-made exercise projects: the folders existed, the configuration files were prepared, and the data was in place. In this module you leave that safety net behind and set up your own project, starting from an empty folder.

The good news: a GeoDMS project is nothing more than a folder with plain text files. There is no project wizard and no hidden state. If you get the folder layout and a few placeholders right, everything else is the configuration language you already know.

the project skeleton

A GeoDMS project separates three kinds of content, each with its own location:

  1. Configuration: the .dms files describing your model. These live inside your project folder and belong in version control.
  2. Source data: read-only input files (shapefiles, GeoTiffs, CSVs). These are usually large, shared between projects, and kept outside the project folder.
  3. Results: everything the model writes (intermediate files, exports). These are reproducible and kept on a fast local drive, outside the project folder.

A typical project folder looks like this:

C:/prj/MyProject/
├── cfg/
│   ├── MyProject.dms      the root configuration file
│   └── MyProject/         included .dms files, as the project grows
└── doc/                   project documentation (optional)

The root configuration file is the file you open in the GeoDMS GUI (File > Open Configuration). The GeoDMS derives the project locations from it using placeholders:

placeholder meaning default
%ProjDir% the project folder: the parent of the folder containing the root configuration file derived from the opened file
%SourceDataDir% base folder for read-only source data C:/SourceData
%LocalDataDir% base folder for (intermediate) results and exports C:/LocalData
%LocalDataProjDir% project-specific subfolder of LocalDataDir %LocalDataDir%/%projName%

Any %placeholder% in a StorageName is expanded to a physical path, so your configuration stays portable between machines. You already set %SourceDataDir% and %LocalDataDir% in Module 0, Install GeoDMS GUI and setup a configuration under Settings > Local machine Options in the GeoDMS GUI. See Folders and Placeholders for the full list.

Project-specific placeholders

You can also define your own placeholders, as string parameters in a container /ConfigSettings/Overridable:

container ConfigSettings
{
   container Overridable
   {
      parameter<string> MyDataDir := '%SourceDataDir%/MyProject';
   }
}

With this in place, %MyDataDir% can be used in every StorageName of your project. Each user can override the default value under Settings > Config Options in the GeoDMS GUI, which stores a machine-specific value in the Windows Registry. This is how projects with multiple users keep one shared configuration while everyone’s data sits in different locations.

a minimal configuration

Below is a complete, working root configuration for a first project. It follows the standard container setup used throughout this Academy and in most production models (see Naming conventions): Units for values units, Geography for the coordinate system, SourceData for reading data, and Results for calculations.

Save it as C:/prj/MyProject/cfg/MyProject.dms:

container MyProject
{
   container Units
   {
      unit<float32> nr_inh  := baseunit('inhabitants', float32);
      unit<float32> m       := baseunit('meter', float32);
      unit<float32> m2      := m * m;
      unit<float32> km2     := 1000000.0 * m2;
      unit<float32> inh_km2 := nr_inh / km2;
   }

   container Geography
   {
      unit<fpoint> rdc_base : SpatialReference = "EPSG:28992";
      unit<fpoint> rdc      := range(rdc_base, point_xy(0f, 300000f), point_xy(280000f, 625000f));
   }

   container SourceData : Using = "Units"
   {
      unit<uint32> province
      :  StorageName     = "%SourceDataDir%/MyProject/provincie.shp"
      ,  StorageType     = "gdal.vect"
      ,  StorageReadOnly = "True"
      {
         attribute<Geography/rdc> geometry (poly);
         attribute<string>        naam;
         attribute<string>        label := naam;
         attribute<nr_inh>        inwoners;
      }
   }

   container Results : Using = "Units"
   {
      attribute<m2>      surface     (SourceData/province) := area(SourceData/province/geometry, m2);
      attribute<km2>     surface_km2 (SourceData/province) := surface[km2];
      attribute<inh_km2> density     (SourceData/province) := SourceData/province/inwoners / surface_km2;
   }
}

Walking through it:

  • Units defines the base units and derived units with a metric, exactly as in Module 1b. Because density is declared as inh_km2, the GeoDMS checks that the expression actually produces inhabitants per square kilometre. Configure your units with metrics from day one; it costs one line per unit and catches calculation errors for free.
  • Geography configures the Dutch RD coordinate system (EPSG:28992) with its base unit and coordinate range, as explained in How to configure a coordinate system. If your data uses another coordinate system, adjust the EPSG code and the range coordinates to the extent of your data.
  • SourceData reads one ESRI Shapefile with gdal.vect, following the pattern from Module 2A. The domain unit province gets its number of rows from the file.
  • Results calculates the surface of each polygon with the area function, converts it to km², and derives a population density.

To test it before using your own data, copy provincie.shp, provincie.dbf and provincie.shx from one of the Academy data folders (for example GeoDMS_Academy/basics_understanding_units/data) into %SourceDataDir%/MyProject/. Then open MyProject.dms in the GUI, double-click geometry for a map view, and double-click density for a table view.

adding a background layer

The map view works without it, but a background layer makes maps much more readable. The Academy exercises use a WMTS layer for this. To add it to your own project, use the same pattern you saw in the exercise configurations:

  1. Copy wmts_layer.dms from an Academy exercise (for example GeoDMS_Academy/basics_classify_and_visualise/cfg/result/wmts_layer.dms) into the subfolder named after your root configuration file: cfg/MyProject/wmts_layer.dms.
  2. Add #include<wmts_layer.dms> inside the Geography container.
  3. Add DialogData = "wmts_layer" to the rdc_base unit:
container Geography
{
   unit<fpoint> rdc_base : SpatialReference = "EPSG:28992", DialogData = "wmts_layer";
   unit<fpoint> rdc      := range(rdc_base, point_xy(0f, 300000f), point_xy(280000f, 625000f));

   #include<wmts_layer.dms>
}

growing habits

The skeleton above fits in one file. Real projects grow, and a few habits keep them manageable:

  • Keep SourceData reads separate from calculations. Everything that reads a file goes in SourceData; everything derived goes in Results (or Analyses). It stays immediately clear which items are inputs and which are model output, and you can swap a data source without touching the model logic.
  • Split the configuration into thematic files. When the root file gets long, move branches like Units, Geography and SourceData to their own .dms files and pull them in with #include <Units.dms>. Included files go in the subfolder named after the including configuration file, so files included from cfg/MyProject.dms live in cfg/MyProject/. See Include.
  • Put the configuration under version control from day one. Configuration files are plain text, so git handles them perfectly. Initialise a repository in your project folder and commit the cfg folder. Keep source data and %LocalDataDir% out of the repository; they are large, and results are reproducible from the configuration.
  • Decouple stable intermediates when runs get slow. Once part of your model is stable (source data integration, base layers), write its results to disk with the native formats from Module 2C and let the rest of the model read from there. Which items are decoupled is declared in the configuration itself, so it is visible and versioned. See Strategic decoupling for when and how.
  • Follow the naming conventions. Lowercase keywords, singular object names, _rel suffix for relations, meaningful item names. See Naming conventions and Good scripting practices.

try it yourself!

Time to build your own project, with your own data.

  1. Pick a polygon shapefile you want to work with: municipalities of your country, neighbourhoods of your city, or any other area dataset you have access to. Note its coordinate system (EPSG code).
  2. Create the folder skeleton: a project folder with a cfg subfolder, and a MyProject subfolder inside %SourceDataDir% for the shapefile.
  3. Copy the minimal configuration from this module into cfg/MyProject.dms and adapt it: the EPSG code and range in Geography, the StorageName, and the attribute declarations to match the columns of your file.
  4. Open the configuration in the GeoDMS GUI and make a map of the geometry. Fix errors one at a time; the detail pages tell you what is wrong.
  5. Add one calculation of your own in Results, with a values unit that has a proper metric.
  6. Add the WMTS background layer following the steps above and admire your map in context.
  7. Finish like a professional: run git init in your project folder and commit your cfg folder.

From here on, every module you completed is a pattern library: reading more formats (Module 2), templates and for_each for repetitive structures (Module 3), vector and grid analyses (Modules 4 and 5). Your project, your questions, same building blocks.

Go to previous module: 9, Final exercise TNO