02. Basic Principles - millsapjohn/qgis_civiltools GitHub Wiki

GIS vs. CAD

GIS and CAD have historically differed in the way they handle features. In most CAD programs, "layers" (or levels) are almost entirely concerned with display properties; any type of feature (circles, lines, or more complex types like TIN surfaces) can reside on any layer. In the world of GIS, however, a "layer" can be more accurately thought of as a "class" of feature; any particular layer has a declared feature type (points, polygons, etc) and only that type can reside on that layer.

This has made integrating CAD and GIS somewhat difficult. In practice, oftentimes CAD drawing layers (mostly) contain a single type of feature, but it's not uncommon for a drafter to draw all features on a "default" layer, and then move them to their permanent home; while in GIS, a layer must be selected (and unlocked for editing) prior to drawing features that fit that layer's feature type.

This plugin aims to bridge that gap in a somewhat opinionated way. Users must create a GeoPackage from a provided template, which contains default layers for all the main geometry types; any features created by the plugin are automatically created on the appropriate default layer. This approach allows the drafter to use, for example, the "Create Lines" tool, regardless of which GIS layer is currently active - the plugin simply sets the appropriate default layer as active before running the command. This provides the user with a much more seamless experience, allowing features to be created on the fly and placed in an appropriate temporary location until the user wants to move them elsewhere.

The QGIS Flavor

While this plugin pulls inspiration from existing CAD programs - notably in the concept of having the tool "always listening" for keyboard commands, rather than relying on tool buttons (or complex shortcuts involving modifier keys like CTRL or SHIFT) - it doesn't attempt to create a pixel-for-pixel recreation of an existing CAD interface. Instead, it reuses existing QGIS graphical widgets wherever possible. For example, when a command is active, prompts will be displayed in the familiar QGIS Message Bar at the top of the screen. Additionally, rather than making "drafting mode" the default active map tool, it must be activated prior to use. The plugin is designed to be available when needed, familiar when in use, and invisible when inactive.

A Note on Keyboard Shortcuts

Because CivilTools relies heavily on keyboard input, when Drafting Mode is active most existing keyboard shortcuts are disabled. This prevents unwanted interactions. For example, by default, QGIS sets the Backspace key to delete selected features - this won't work while Drafting Mode is active. Once Drafting Mode is deactivated, all existing shortcuts will once again work as normal.

Default Layers

In order to ease the use of CivilTools in a GIS context, the plugin requires that the user create a default GeoPackage (created from a template, saved in the plugin folder) that contains a number of default layers. This is known as "initializing the project" and must be completed before the various tools can be used.

Initializing a Project

An open QGIS project can be initialized by opening the Plugins -> CivilTools menu and clicking the "Initialize Project" button. This will launch a popup dialog where the user can select a name and location to save the default layers GeoPackage, which contains layers for the following feature types:

  • points
  • lines/polylines
  • polygons
  • TIN points
  • TIN triangles
  • grading points
  • grading breaklines
  • grading polygons
  • Grading Region lines/polylines
  • Grading Region polygons
  • pipes
  • pipe structures
  • dimension points
  • dimension lines

Once a file name and location have been specified, click OK to initialize the project. The GeoPackage will be added to the QGIS Browser panel, and the default layers for lines, points, and polygons will be added to the project's layers in a group labeled "CivilTools."

Running Commands

In the nomenclature of QGIS, CivilTools is a "map tool," in the same way that Pan, Zoom, and Select Features are map tools. Like the other map tools, it can be activated by either clicking the associated button (labeled "Drafting Mode") or by entering a keyboard shortcut. The default keyboard shortcut to enter Drafting Mode is CRTL+ENTER, but this can be changed in the Settings -> Options menu. When drafting mode is active, a colored border (red by default) will appear around the edges of the map canvas, and the cursor will change to a pick box with crosshairs.

CivilTools commands can be run in one of two ways: by navigating the CivilTools submenus under the main Plugins menu, or by using a keyboard shortcut. When in drafting mode, any of CivilTools' commands can be run by entering their 1 to 3 letter shortcut and pressing Enter. Commands can be exited early by pressing Escape. When in drafting mode, pressing Enter when no command is active will re-run the previous command.

Many commands have sub-commands available, each with their own keyboard shortcut - for example, options to create a circle based on a centerpoint and radius or a centerpoint and diameter. When a command is activated, any available sub-commands will be listed in a popup on the Message Bar at the top of the Map Canvas.

Snaps

One of the most useful tools when creating objects is the ability to snap to the geometry of another object - for example, being able to draw a line exactly perpendicular to another line. CivilTools comes with the following snapping options:

  • endpoint
  • midpoint
  • center
  • node (i.e., a point object)
  • intersection
  • perpendicular
  • tangent (to a circle or arc)
  • nearest (snaps to any geometry within the cursor search radius)

Each snap has a unique glyph that appears when a snap of that type is available within the cursor search radius, and the cursor itself will be automatically moved (thus the term "snap") to that location. Snaps can be turned on or off via the expandable Snaps toolbar, or in the right-click menu. Additionally, any layers in the drawing can be added to an "exclude list," meaning they will not be available for snapping. The "exclude list" is available in the Options menu. Finally, the cursor search radius (the distance from the cursor where snaps can appear) can be configured in the Options menu as well.

Grips

Grips are specific areas on a feature that can be selected and manipulated. For example, a feature vertex can be moved by hovering over, then clicking, on a vertex grip; a polygon can be moved with the center grip; etc. Each grip type has its own glyph, much like a snap; right-clicking on a grip will bring up a context menu allowing the user to select the desired operation.

Right Click Menu

The right click menu is highly context-dependent; many different options will be available depending on the type of feature selected, or whether a feature is selected at all.