PlatGroup

Use this class to plat land across any number of townships, with each township on its own image / page. (But can optionally be saved to a single PDF or TIFF file, with each plat on its own page.)

The three methods for adding lands to the PlatGroup are:

  • .add_description(), for adding the text of a description directly.

  • .add_tract(), for adding a pytrs.Tract (already parsed).

  • .add_tracts(), for adding multiple pytrs.Tract objects (already parsed),

    such as pytrs.PLSSDesc or pytrs.TractList objects, which contain tracts.

See LotDefiner for how to work with the .lot_definer attribute.

See Settings for how to work with the .settings attribute.

See this discussion on working with multiple layers for using multiple colors for different tracts.

Example Images

(Resized from original output. Click to see full size.)

Page 1:

../_images/platgroup_153n96w.png

Page 2:

../_images/platgroup_154n97w.png

Example Code

This results in the images above.

import pytrs
import pytrsplat

# Choose a settings preset.
letter_preset = pytrsplat.Settings.preset('letter')
# Adjust settings as desired.
letter_preset.set_font('footer', typeface='Sans-Serif', size=48)
letter_preset.write_lot_numbers = True

multipage_plat = pytrsplat.PlatGroup(settings=letter_preset)
# If we've written lot definitions to .csv, we load them here.
multipage_plat.lot_definer.read_csv('some_lot_definitions.csv')
# Otherwise / additionally, we can assume 'default' lots.
multipage_plat.lot_definer.allow_defaults = True
multipage_plat.lot_definer.standard_lot_size = 40

# Add lands with `.add_description(), `.add_tract()`, or `.add_tracts()`.

land_desc = """T154N-R97W
Sec 14: NE/4
T153N-R96W
Sec 1: Lots 1 - 3
Sec 18: ALL"""
# `config` gets passed to pytrs for parsing.
multipage_plat.add_description(
    land_desc,
    config='n,w'    # Optional, control parsing of description.
)

tract = pytrs.Tract(
    desc='SW/4',
    trs='154n97w15',
    parse_qq=True,  # parse_qq=True is REQUIRED
    config='n,w'    # Optional, control parsing of description.
)
multipage_plat.add_tract(tract)

plss_desc = pytrs.PLSSDesc(
    'T154N-R97W Sec 16: ALL',
    parse_qq=True,  # parse_qq=True is REQUIRED
    config='n,w'    # Optional, control parsing of description.
)
multipage_plat.add_tracts(plss_desc)

# Executing the queue will fill in the plats.
multipage_plat.execute_queue()

# Save to PNG. In this case, one PNG for each page.
multipage_plat.output(fp=r'some\path\platgroup.png')
# Saving to PDF or TIFF allows all pages to be included in the same file.
multipage_plat.output(fp=r'some\path\platgroup_153n96w,154n97w.pdf')
# Or save as multiple PNG images (or other format) inside a ZIP file.
multipage_plat.output(fp=r'some\path\platgroup.zip', image_format='png')

Methods and Attributes

class pytrsplat.PlatGroup(settings: Settings = None, lot_definer: LotDefiner = None)

A collection of Plats that can span multiple Twp/Rge. Access the plats in .plats (keyed by a twprge string in the pytrs format, e.g., '154n97w').

__init__(settings: Settings = None, lot_definer: LotDefiner = None)
Parameters:

  • settings – The Settings object to control the behavior and appearance of the subordinate plats.

  • lot_definer – A LotDefiner object to use for defining lots in tracts that are added to the queue. (Can also be modified or replaced in the .lot_definer attribute later.)

add_description(txt: str, config: str = None, layer: str = None) → TractList

Parse the land description and add the resulting tracts to the plat group. If one or more Twp/Rge’s are newly identified, plats will be created as needed.

Parameters:

  • txt – The land description.

  • config – The config parameters for parsing, to be passed through to the pytrs library. (See pyTRS documentation for details.)

  • layer – Name of the layer to add this description to.

Returns:

A pytrs.TractList containing the tracts in which the parser could not identify any lots or aliquots.

add_tract(tract: Tract, layer: str = None) → None

Add a tract to the queue. If no plat yet exists for the Twp/Rge of this tract, one will be created.

Note

The tract must already be parsed for lots/QQs. (See pyTRS documentation for details.)

Parameters:

  • tract – A pytrs.Tract that has been parsed into Lots and QQ’s.

  • layer – Name of the layer to add this tract to.

add_tracts(tracts: list[Tract] | TractList | PLSSDesc, layer=None) → None

Add multiple tracts to the queue.

Note

The tracts must already be parsed for lots/QQs. (See pyTRS documentation for details.)

Parameters:

  • tracts – A collection of pytrs.Tract objects, such as a pytrs.PLSSDesc, pytrs.TractList, or any other iterable object that contains exclusively pytrs.Tract.

  • layer – Name of the layer to add these tracts to.

carve_description(txt: str, config: str = None, layer: str = None) → TractList

Parse the land description and carve out the resulting tracts from the queue, so that they do not appear on the resulting plat.

(Affects only which lands get filled in on the plat. This carve-out will NOT prevent tracts from being written to the footer, if so configured.)

Note

All carve-outs override the queue for a given layer. In other words, when the queue is executed, all added lands will be platted for that layer, then all carved-out lands will be removed from that layer. This means that carved-out lands cannot be re-added to the queue for that same layer. They can be added to the queue for a different layer.

Carve-outs for any given layer can be cleared with .clear_layer_carveouts(layer=<name>).

Warning

Any lots or aliquots identified in this description will be removed from the layer. Be careful to use a ‘clean’ description that will not remove lands that should be kept.

Parameters:

  • txt – The land description.

  • config – The config parameters for parsing, to be passed through to the pytrs library. (See pyTRS documentation for details.)

  • layer – Name of the layer to carve this description from.

Returns:

A pytrs.TractList containing the tracts in which the parser could NOT identify any lots or aliquots.

carve_tract(tract: Tract, layer: str = None) → None

Carve out lands (single tract) from the queue, so that they do not appear on the resulting plat.

(Affects only which lands get filled in on the plat. This carve-out will NOT prevent tracts from being written to the footer, if so configured.)

Note

The tract must already be parsed for lots/QQs. (See pyTRS documentation for details.)

Note

All carve-outs override the queue for a given layer. In other words, when the queue is executed, all added lands will be platted for that layer, then all carved-out lands will be removed from that layer. This means that carved-out lands cannot be re-added to the queue for that same layer. They can be added to the queue for a different layer.

Carve-outs for any given layer can be cleared with .clear_layer_carveouts(layer=<name>).

Warning

Any lots or aliquots identified in this tract will be removed from the layer. Be careful to use a ‘clean’ description that will not remove lands that should be kept.

Parameters:

  • tract – A pytrs.Tract that has been parsed into Lots and QQ’s. (Its Twp/Rge must match what is already in the queue.)

  • layer – Name of the layer to carve this tract from.

carve_tracts(tracts: list[Tract] | TractList | PLSSDesc, layer: str = None) → None

Carve out lands (multiple tracts) from the plat, so that they do not appear on the resulting plat.

(Affects only which lands get filled in on the plat. This carve-out will NOT prevent tracts from being written to the footer, if so configured.)

Note

The tracts must already be parsed for lots/QQs. (See pyTRS documentation for details.)

Note

All carve-outs override the queue for a given layer. In other words, when the queue is executed, all added lands will be platted for that layer, then all carved-out lands will be removed from that layer. This means that carved-out lands cannot be re-added to the queue for that same layer. They can be added to the queue for a different layer.

Carve-outs for any given layer can be cleared with .clear_layer_carveouts(layer=<name>).

Warning

Any lots or aliquots identified in these tracts will be removed from the layer. Be careful to use ‘clean’ descriptions that will not remove lands that should be kept.

Parameters:

  • tracts – A collection of pytrs.Tract objects, such as a pytrs.PLSSDesc, pytrs.TractList, or any other iterable object that contains exclusively pytrs.Tract.

  • layer – Name of the layer to carve these tracts from.

clear_layer_carveouts(layer: str = None)

Clear the carve-outs for the specified 'layer'.

Parameters:

layer – Name of the layer to clear the carve-outs for.

clear_layer_queue(layer: str = None, include_carveouts=False)

Clear the contents of the queue for the specified 'layer'.

Parameters:

  • layer – Name of the layer to clear the queue for.

  • include_carveouts – (Optional) Also clear any carve-outs for this layer.

execute_queue(subset_twprges: list[str] = None, prompt_define=False) → TractList

Execute the queue of tracts to fill in the plats.

Parameters:

  • subset_twprges – (Optional) Limit the generated image to this list of Twp/Rges (in the pyTRS format – e.g., ['154n97w', '155n97w']).

  • prompt_define – (Optional) If True, first check for undefined lots, and prompt the user in console to define them.

Returns:

A pytrs.TractList containing all tracts that could not be platted (no lots or aliquots identified).

find_undefined_lots(allow_defaults: bool = None, fp: str | Path = None, **headers) → dict[str, list[str]]

Find all tracts in the queue that have one or more lots that have not been defined. Optionally write them to a .csv file at path fp, to facilitate defining them externally.

Warning

If passing fp, any file at that path will be overwritten without warning.

Parameters:

  • allow_defaults – Whether to assume that all sections are ‘standard’, with typical lots (if any) in sections along the north and west township boundaries. If not specified here, will use whatever is configured in the lot_definer.allow_defaults attribute.

  • fp – (Optional) A filepath at which to create a .csv file containing the undefined lots.

  • headers – (Optional) If saving the undefined lots to a .csv file, pass keyword arguments to specify the desired headers. (Reference the docs for LotDefiner.save_to_csv() for the appropriate parameters.)

Returns:

A dict, keyed by Twp/Rge/Sec ('154n97w01'), whose values are a sorted list of lots for that Twp/Rge/Sec.

find_unplattable_tracts(allow_defaults: bool = None) → TractList

Get a pytrs.TractList containing all tracts that cannot be platted with the currently provided lot definitions (optionally accounting for default lots, if so configured).

Note

If a tract has any aliquots and/or any lots that have been defined, it will be considered plattable, even if some of its lots have NOT been defined. To check for undefined lots, use the .find_undefined_lots() method.

Parameters:

allow_defaults – Whether to assume that all sections are ‘standard’, with typical lots (if any) in sections along the north and west township boundaries. If not specified here, will use whatever is configured in the lot_definer.allow_defaults attribute.

output(fp: str | Path = None, image_format: str = None, stack: bool = None, subset_twprges: list[str] = None, layers: list[str] = None, image_mode: str = 'RGB') → list[Image]

Compile and return the merged image of the plats. Optionally save the results to disk, either as one or more images, or as a .zip file containing the image(s).

Note

Most image file formats are acceptable. If saving to a .pdf or .tiff file extension, this will assume the user wants a single file – but separate files can be forced with stack=False.

If multiple files must be created (e.g., if the image format is 'png'), then the respective Twp/Rge will be added to each filename, before the file extension. For example, with fp='some_file.png', it might create some_file 154n97w.png, some_file 155n97w.png, etc.

Parameters:

  • fp – (Optional) If provided, save the output to the specified filepath. If the path has a .zip extension, the results will be put into a .zip file at that path. In that case, you may want to specify the image_format.

  • image_format – (Optional) Override the file format of the file specified in fp. If not provided, will defer to the file extension in fp. (Only relevant if saving to file.)

  • stack – (Optional) Whether to save the images to a single file (assuming an appropriate image format is used). If the file extension or specified image_format are 'tiff' or 'pdf', then the resulting image will be stacked by default (but can be overridden with stack=False). Any other format will result in separate images.

  • subset_twprges – (Optional) Output the plats only for the selected Twp/Rges (formatted as ['154n97w', '12s58e']).

  • layers – (Optional) Choose which image layers (in bottom-up order) to include in the output. (See Plat.DEFAULT_LAYER_NAMES for the standard layer names.) Nonexistent or empty layers will be ignored.

  • image_mode – Specify which image mode to convert the merged output to. Defaults to 'RGB'. (Reference PIL.Image.Image.convert() for further details.)

Returns:

The resulting plat image(s) as a list of images.

prompt_define(allow_defaults: bool = None)

Prompt the user in console to define all lots that have not yet been defined for tracts in the queue. Any new lot definitions will be added to the .lot_definer.

(You may wish to save the results with .lot_definer.save_to_csv() so that they can be loaded and reused later.)

Parameters:

allow_defaults – Whether to assume that this section is ‘standard’, with typical lots (if any) in sections along the north and west township boundaries. If not specified here, will use whatever is configured in the .lot_definer.allow_defaults attribute.

write_lot_numbers(at_depth=2, only_for_queue: bool = None)

Write the lot numbers to the plats.

Parameters:

  • at_depth – Depth at which to write the lots. Default is 2 (i.e., quarter-quarters).

  • only_for_queue – (Optional) If True, only write section numbers for those sections that appear in the queue.