SWMM5 Delphi GUI Umap.pas Summary

 Extended and Expanded Summary of the Umap.pas Unit

This unit, Umap.pas, forms a central part of EPA SWMM’s map-drawing architecture. It manages drawing the Study Area Map on a memory bitmap and handles details like re-scaling, positioning, labeling, and optionally rendering a backdrop image.

Below is a thorough guide to:

1. Purpose and Scope
2. Core Data Structures
3. Key Constants & Defaults
4. Principal Routines
5. Workflow
6. Integration With Other Units

---

1. Purpose and Scope

The Umap.pas unit covers:

• Rendering (drawing) the SWMM project’s elements onto an in-memory bitmap, then onto the main display canvas.
• Backdrops, including reading an image from a file, placing it behind the foreground objects, and optionally modifying it (watermark, grayscale).
• Re-scaling and zooming the map, ensuring that the coordinate transformations (World ↔ Screen) are correct.
• Legendary map operations:
  • Identifying bounding rectangles for objects.
  • Drawing objects (subcatchments, nodes, links, and labels) at the correct size and color.
  • Handling shape-specific symbols (outfalls, dividers, inlets, etc.).
• Coordinate conversion methods, allowing SWMM’s internal world coordinates to map onto device (pixel) coordinates.

---

2. Core Data Structures

2.1 TMap Class

TMap = class(TObject)
  Canvas    : TCanvas;      
  Bitmap    : TBitmap;      
  BackBM    : TBitmap;      
  GageBM    : TBitmap;      
  InletBM   : TBitmap;      
  Window    : TMapWindow;   
  Dimensions: TMapDimensions;
  Options   : TMapOptions;  
  Backdrop  : TMapBackdrop; 
  Sfactor   : Extended;     
  ZoomState : array [0..10] of TMapZoomState;
  ZoomIndex : Integer;      
  ZoomRatio : Integer;
  ...
end;

The TMap class encapsulates all map-centric data:

• Canvas: The main TCanvas used for drawing.
• Bitmap, BackBM: TBitmap objects for the overall map and the backdrop.
• GageBM, InletBM: Bitmaps for specialized symbols (raingages, inlets).
• Window: A TMapWindow record describing the mapping from world to pixel coordinates.
• Dimensions: A TMapDimensions record with physical extents, unit conversions, etc.
• Options: A TMapOptions record (e.g., whether to show node IDs, subcatchment fill style, arrow sizes, etc.).
• Backdrop: A TMapBackdrop record with backdrop image info (filename, source, corners, etc.).
• Sfactor: A factor for adjusting scale at zero-zoom.
• ZoomState[]: Up to 10 zoom states can be stored, each with a center and zoom factor.

2.2 Supporting Records

• TMapDimensions: Contains the real-world bounding box, length/area conversion factors, map units, etc.
• TMapWindow: Captures the pixel-based map rectangle, world→pixel offset, and scaling ratio.
• TMapBackdrop: For controlling the source/visibility of the backdrop image.
• TMapOptions: For toggling visibility of subcatchments, nodes, etc., plus annotation styles and coloring.

---

3. Key Constants & Defaults

1. MAX_INT_COORD = 32767 (the maximum pixel coordinate for safe GDI operations).
2. MAX_POINTS = 1000 (the max vertices in a polygon array).
3. Default TMapDimensions (DefMapDimensions) with 0..10000 bounding box, 3 decimal digits, conversion factors, etc.
4. Default TMapBackdrop (DefMapBackdrop) with none source, empty file, etc.
5. Default TMapOptions (DefMapOptions) with things like show subcatchments, node IDs off, link IDs off, etc.

---

4. Principal Routines

4.1 Map Construction and Lifecycle

• constructor TMap.Create

  • Allocates memory bitmaps (Bitmap, BackBM, GageBM, InletBM) and sets them to 24-bit color.
  • Applies default map/backdrop options and zero-level zoom state.

• destructor TMap.Destroy

  • Frees the TBitmap objects.

4.2 Drawing Methods

1. DrawMap

   • Clears map background, optionally draws the backdrop, then calls DrawForeground.

2. DrawForeground

   • Sets pen & brush colors, draws subcatchments, links, nodes, gages, and labels.

3. Object-Specific:

   • DrawSubcatchments, DrawSubcatch(Index):
     • Retrieves vertex points, sets a color from the subcatch’s color index, draws the polygon, subcatch centroid marker, etc.
   • DrawNodes, plus subroutines for each node type (DrawOutfall, DrawDivider, DrawStorage, etc.).
   • DrawLinks, DrawLink(...):
     • Draws polylines for each link, possibly with an arrow or pump/valve symbol.
   • DrawLabels:
     • Draws map labels (TMapLabel) with user-defined fonts.

4. Symbol Drawing:

   • DrawArrowHead(...): for link flow direction.
   • DrawPumpSymbol(...): for pumps.
   • DrawInletSymbol(...): for inlets.

4.3 Backdrop Handling

• DrawBackdrop(...)

  • Loads a TPicture from file, calculates a rectangle, then stretches the image onto the BackBM canvas.
  • Handles grayscale or watermark transformations if set.

• RedrawBackdrop

  • Convenience method that calls DrawBackdrop if backdrop is visible.

4.4 Rescaling, Zooming, Coordinate Conversions

• Rescale

  • Recomputes the current window scale (WperP) based on the main bounding rectangle and the current ZoomIndex.

• Pixel ↔ World:

  • GetXpix, GetYpix convert from world to pixel.
  • GetX, GetY convert from pixel back to world.

• ZoomState[] array keeps track of center coordinates and scale factors at different zoom levels.

4.5 Utility Methods

• GetBoundingRect(...)

  • Returns the bounding rectangle in pixel space for a given SWMM object (subcatch, node, link, or label).

• GetNodeRect(...), GetLinkRect(...), GetSubcatchRect(...)

  • Specialized bounding rectangle logic for each category.

• SnapSubcatch(...)

  • Example of snapping subcatchment vertices if user drags them close to another polygon.

• GetSubcatchAreaStr(...), GetLinkLengthStr(...)

  • For computing lengths in consistent project units.

---

5. Workflow

1. Initialization

   • A TMap instance is created, bitmaps are allocated, default dimension and options are assigned.
   • The “full extents” of the map are determined from the project bounding box (see Rescale logic).

2. Backdrop

   • If the user sets a backdrop file, RedrawBackdrop is called.
   • DrawBackdrop loads the file into a TPicture, positions it, and draws it onto BackBM.

3. Drawing the Foreground

   • DrawMap is invoked, which erases the background, then copies the backdrop image (if visible) onto the main Bitmap.
   • Then DrawForeground systematically draws subcatchments, links, nodes, rain gages, labels, etc.
   • SWMM color-coded styling is determined via calls to SetNodeColor, SetSubcatchColor, etc.

4. Zooming

   • The user might choose Zoom In/Out in the UI.
   • SWMM updates ZoomIndex or modifies ZoomState[ZoomIndex].
   • Rescale is called, then DrawMap re-renders at the new scale.

5. Coordinate Tools

   • Clicking on the map or retrieving an object’s bounding rectangle uses the coordinate transformations in GetXpix, GetYpix, etc.

---

6. Integration With Other Units

• Uglobals.pas

  • Defines CurrentNodeVar, CurrentLinkVar, etc., plus color arrays like MapSubcatchColor, MapNodeColor, MapLinkColor.

• Uproject.pas

  • Houses the main Project object with subcatchments, nodes, links, etc.
  • Umap frequently queries Project to get coordinates, color indexes, etc.

• Uoutput.pas

  • Provides Uoutput.GetNodeValStr, Uoutput.GetSubcatchValStr, etc. used for labeling.

• Uinlet.pas

  • Some specialized logic for drawing inlets on conduits (DrawInletSymbol).

• Jpeg

  • The code references loading TJPegImage if the user’s backdrop is a JPEG.

• System.UITypes

  • For color and coordinate definitions in newer Delphi versions.

---

Concluding Remarks

In summary:

• Umap.pas orchestrates the entire graphic representation of SWMM objects.
• It does so by layering a backdrop image behind user-defined and computed shapes.
• It manages the correlation between real-world coordinates (including lat-long if the user chooses) and the screen’s pixel coordinates.
• It uses custom coloring, line widths, symbol drawing, text labels, and handling of user options to produce a clear, zoomable map representation.