Working with Subregions Using Region Manager

Some workflows shouldn't run against a whole map at once — a national land-use model might need different parameters per country, or a hydrology model might only make sense computed watershed by watershed. Region Manager is what makes that practical: define the regions once, from a categorical map whose class values are the boundaries, and everything downstream — reading metadata, narrowing to one region, splitting a map into pieces, and merging the pieces back — works against that single definition.

The running example through this page computes an accumulated-cost surface separately for each region, using Calc Cost Map, then reassembles the per-region results into one global cost map. It's a genuinely representative case: split, do real per-region work, collect, merge.

Region Manager is the container everything else on this page depends on.

A nonzero borderCells matters for anything that accumulates across neighboring cells — a cost surface, a neighborhood statistic — since without it, a region's edge cells would be computed as if the world stopped there.

Example — the shell everything else in this page builds on:

sourcesMap := LoadMap "c:/data/sources.tif";
frictionsMap := LoadMap "c:/data/frictions.tif";
regionsMap := LoadCategoricalMap "c:/data/regions.tif" .none .default 0;

RegionManager regionsMap 5 {{
    // everything below is added here, one section at a time
}};

Get All Regions Info returns boundary details for every region at once, as a table — the natural thing to feed a loop:

Get Region Info is the single-region equivalent, useful when you need more than a bounding box for one particular region — it also returns a mask isolating that region and its coordinate reference system:

Add the enumeration step to the running example:

RegionManager regionsMap 5 {{
    allRegions := GetAllRegionsInfo;
}};

Region narrows scope to a single region for whatever's nested inside it:

Visiting every region means reading Get All Regions Info's table and looping over it with For Each, nesting Region inside to re-expose the loop's current key under the name regionId — Regionalize Map and the rest of this page's functors auto-bind to a port by that exact name, not to For Each's own step.

It's tempting to reach for For Each Region instead, since it bundles “define regions” and “loop over them” into one container. Resist that here: it has its own required regions input and creates its own region manager internally, rather than sharing one from an enclosing Region Manager. That's fine if the loop is the entire task, but this page's example needs the *same* region manager instance still available after the loop, for the merge — which For Each Region can't provide, since its manager stops existing once its own block ends.

RegionManager regionsMap 5 {{
    allRegions := GetAllRegionsInfo;

    _ := ForEach allRegions {{
        Region step {{
            // regionId comes from step; regionManager auto-binds from the
            // enclosing RegionManager.
        }};
    }};
}};

Regionalize Map and Regionalize Categorical Map cut a global map down to one region's extent:

This is where the actual per-region computation happens — split the global inputs, run whatever the model needs against the region-sized pieces, in this case Calc Cost Map:

Region step {{
    regionalSources := RegionalizeMap sourcesMap;
    regionalFrictions := RegionalizeMap frictionsMap;

    { costs = regionalCost, directions = _ } :=
        CalcCostMap regionalSources regionalFrictions .no;
}};

Regional Map and Regional Categorical Map tag a per-region fragment under a shared name as it's produced — neither has an output; they're pure collectors, accumulating fragments as a side effect of the loop running:

Region step {{
    regionalSources := RegionalizeMap sourcesMap;
    regionalFrictions := RegionalizeMap frictionsMap;

    { costs = regionalCost, directions = _ } :=
        CalcCostMap regionalSources regionalFrictions .no;

    RegionalMap "cost_map" regionalCost;
}};

Merge Regional Maps and Merge Regional Categorical Maps reassemble everything stored under a shared name back into one global mosaic:

There's a trap here worth naming: neither merge functor has a sequenceInput of its own, and nothing about globalMapName — just a literal string — creates a data dependency on the loop that populated it. Left as-is, the engine has no reason to run the merge *after* the loop rather than before or during it. For Each does expose a sequenceOutput once the whole loop finishes, but with nowhere on the merge functor to plug it into, the fix is a Group wrapped around the merge, whose own sequenceInput the loop's sequenceOutput connects into.

A few more things worth knowing before relying on the merge:

• The merged map's format is inherited from the first fragment stored, not negotiated across all of them. Cell type, null value, and categorization all come from whichever Regional Map or Regional Categorical Map call registered first for that name — only the dimensions come from the regions map itself. If regions are processed in an order that isn't guaranteed, don't rely on which fragment “wins.”
• Mismatched null values fail the merge, not silently overwrite each other. When mergeNonRegionCells brings overlapping border cells from two different regions together, they can only combine if they agree, or one of them is null — two regions disagreeing on what a cell's value should be raises an error rather than picking one.
• A layer's sparse storage survives the merge, so long as every regional fragment for that layer used it too — the merged global layer comes out sparse rather than being densified. See Map Type's Storage section for what sparse storage means.
• Fragments are consumed, not just read. Once the merge for a given globalMapName runs, the manager no longer holds those fragments — there's no merging the same name twice, and nothing left to read back under it afterward.

Region Manager Value exists purely to pass a Region Manager value through — the same relay role Struct's carrier functor plays for structs. Its own input auto-binds to the enclosing container's regionManager by default and cannot be given as a constant.

sourcesMap := LoadMap "c:/data/sources.tif";
frictionsMap := LoadMap "c:/data/frictions.tif";
regionsMap := LoadCategoricalMap "c:/data/regions.tif" .none .default 0;

RegionManager regionsMap 5 {{
    allRegions := GetAllRegionsInfo;

    sequenceOut := ForEach allRegions {{
        Region step {{
            regionalSources := RegionalizeMap sourcesMap;
            regionalFrictions := RegionalizeMap frictionsMap;

            { costs = regionalCost, directions = _ } :=
                CalcCostMap regionalSources regionalFrictions .no;

            RegionalMap "cost_map" regionalCost;
        }};
    }};

    _ := Group sequenceOut {{
        costMap := MergeRegionalMaps "cost_map" .no;
        SaveMap costMap "c:/data/cost_map_merged.tif";
    }};
}};

One region manager, defined once at the top, is what threads the whole thing together: Get All Regions Info reads from it, Region narrows against it once per loop iteration, Regional Map stores fragments into it, and Merge Regional Maps — deliberately delayed until the loop's sequenceOutput fires — reads every one of those fragments back out of the same instance.