Reference

fastfuels_sdk.domains

domains.py

Domain

Bases: Domain

Domain resource for the FastFuels API.

Represents a spatial container that defines geographic boundaries for fire behavior modeling and analysis. A Domain includes metadata like name and description along with geometric data defining its spatial extent. Domains must specify a valid area between 0 and 16 square kilometers.

The Domain handles coordinate system transformations automatically: 1. Geographic coordinates (e.g. EPSG:4326) are projected to appropriate UTM zone 2. Projected coordinates are preserved in their original CRS 3. Local coordinates are treated as non-georeferenced 4. Geometries are padded to align with specified grid resolution

Attributes:

Name	Type	Description
id	str	Unique identifier for the domain
name	str	Human-readable name for the domain
description	str	Detailed description of the domain
type	str	Always "FeatureCollection"
features	List[dict]	GeoJSON features defining domain extent and input geometry
horizontal_resolution	float	Grid cell size in meters for x/y dimensions
vertical_resolution	float	Grid cell size in meters for z dimension
crs	dict	Coordinate reference system specification
tags	(List[str], optional)	User-defined tags for organization

Examples:

Create domain from GeoJSON:

>>> with open("area.geojson") as f:
...     geojson = json.load(f)
>>> domain = Domain.from_geojson(
...     geojson,
...     name="Test Domain",
...     horizontal_resolution=2.0
... )

Get domain by ID:

>>> domain = Domain.from_id("abc123")
>>> print(domain.name)
'Test Domain'

See Also

Domain.from_geojson : Create domain from GeoJSON data Domain.from_geodataframe : Create domain from GeoPandas GeoDataFrame list_domains : List available domains

from_id classmethod

from_id(domain_id: str) -> Domain

Retrieve an existing Domain resource by its ID.

Fetches a Domain from the FastFuels API using its unique identifier. Raises NotFoundException if no domain exists with the given ID.

Parameters:

Name	Type	Description	Default
domain_id	str	The unique identifier of the domain to retrieve	required

Returns:

Type	Description
Domain	The requested Domain object

Examples:

>>> domain = Domain.from_domain_id("abc123")
>>> domain.id
'abc123'

from_geojson classmethod

from_geojson(geojson: dict, name: str = '', description: str = '', horizontal_resolution: float = 2.0, vertical_resolution: float = 1.0) -> Domain

Create a new Domain resource from GeoJSON data.

Creates and stores a spatial Domain in the FastFuels API that serves as a geographic container for other system resources. The Domain is defined by GeoJSON geometry which must specify a valid area between 0 and 16 square kilometers.

The system processes the input geometry in several ways: 1. If geographic coordinates (e.g. EPSG:4326) are provided, they are automatically projected to the appropriate UTM zone for accurate spatial operations 2. If already in a projected coordinate system, the input CRS is preserved 3. If specified as 'local', the coordinates are treated as non-georeferenced 4. The geometry's bounding box is calculated and padded to align with the specified grid resolution

Parameters:

Name	Type	Description	Default
geojson	dict	A GeoJSON dictionary containing either a Feature or FeatureCollection. Must include a valid geometry defining the spatial location of the domain.	required
name	str	Name for the domain resource, default ""	''
description	str	Description of the domain resource, default ""	''
horizontal_resolution	float	Horizontal resolution in meters for grid representation, default 2.0	2.0
vertical_resolution	float	Vertical resolution in meters for grid representation, default 1.0	1.0

Returns:

Type	Description
Domain	The newly created Domain object.

Examples:

>>> with open("my_file.geojson") as f:
...     my_geojson = json.load(f)
>>> domain = Domain.from_geojson(
...     geojson=my_geojson,
...     name="my domain",
...     description="A domain for testing",
...     horizontal_resolution=2.0,
...     vertical_resolution=1.0
... )
>>> domain.id
'abc123...'

from_geodataframe classmethod

from_geodataframe(geodataframe, name: str = '', description: str = '', horizontal_resolution: float = 2.0, vertical_resolution: float = 1.0)

Create a new Domain resource from a GeoDataFrame.

The Domain acts as a spatial container in the FastFuels API, defining the geographic boundaries for fire behavior modeling and analysis. This method provides a convenient way to create a Domain from existing geospatial data loaded in a GeoDataFrame.

The GeoDataFrame's geometry undergoes several processing steps: 1. For data in geographic coordinates (e.g. EPSG:4326), the system automatically projects to the appropriate UTM zone based on the geometry's centroid. This ensures accurate distance and area calculations. 2. If the data is already in a projected coordinate system (e.g. NAD83 / UTM or State Plane), that CRS is preserved to maintain consistency with existing data. 3. For local coordinate systems, the geometry is treated as non-georeferenced and no projection is performed. 4. The system calculates a bounding box around the geometry and pads it to align with the specified resolution, ensuring proper grid alignment for analysis.

One key advantage of using GeoDataFrames is the ability to read from multiple file formats. The same Domain creation process works whether your data comes from Shapefiles, KML, GeoJSON, or other formats supported by geopandas.

Input geometry must define a valid area between 0 and 16 square kilometers to ensure efficient processing and analysis.

Parameters:

Name	Type	Description	Default
geodataframe	GeoDataFrame	Geopandas GeoDataFrame object containing the geometry defining the domain.	required
name	str	Name for the domain resource, default ""	''
description	str	Description of the domain resource, default ""	''
horizontal_resolution	float	Horizontal resolution in meters for grid representation, default 2.0	2.0
vertical_resolution	float	Vertical resolution in meters for grid representation, default 1.0	1.0

Returns:

Type	Description
Domain	The newly created Domain object.

Examples:

>>> import geopandas as gpd
>>> gdf = gpd.read_file("blue_mtn.shp")  # Can read shp, geojson, kml, etc.
>>> domain = Domain.from_geodataframe(
...     gdf,
...     name="test_domain",
...     description="Domain from shapefile",
...     horizontal_resolution=2.0,
...     vertical_resolution=1.0
... )
>>> domain.name
'test_domain'

get

get(in_place: bool = False) -> Domain

Retrieve the latest domain data from the API.

This method fetches the most recent data for this domain from the API. It can either update the current Domain instance in-place or return a new instance with the fresh data.

Parameters:

Name	Type	Description	Default
in_place	bool	If True, updates the current Domain instance with the new data and returns self. If False, returns a new Domain instance with the latest data, leaving the current instance unchanged. Default is False.	False

Returns:

Type	Description
Domain	Either the current Domain instance (if in_place=True) or a new Domain instance (if in_place=False) containing the latest data from the API.

Examples:

Create new instance with latest data:

>>> domain = Domain.get_domain("123")
>>> updated_domain = domain.get()  # domain remains unchanged
>>> updated_domain is domain
False

Update existing instance in-place:

>>> domain = Domain.get_domain("123")
>>> domain.get(in_place=True)  # domain is updated
>>> # Any references to domain now see the updated data

Notes

The default behavior (in_place=False) ensures immutability by returning a new instance. This is safer for concurrent operations but requires reassignment if you want to retain the updated data. Use in_place=True when you want to ensure all references to this Domain instance see the updated data.

update

update(name: Optional[str] = None, description: Optional[str] = None, tags: Optional[List[str]] = None, in_place: bool = False) -> Domain

Update the domain's mutable properties.

This method allows updating the name, description, and tags of a domain. Other properties cannot be modified - a new domain must be created instead.

Parameters:

Name	Type	Description	Default
name	str	New name for the domain	None
description	str	New description for the domain	None
tags	List[str]	New list of tags for the domain	None
in_place	bool	If True, updates the current Domain instance with the new data and returns self. If False, returns a new Domain instance with the updated data, leaving the current instance unchanged. Default is False.	False

Returns:

Type	Description
Domain	Either the current Domain instance (if in_place=True) or a new Domain instance (if in_place=False) containing the updated data.

Examples:

Update and get new instance:

>>> domain = Domain.get_domain("123")
>>> updated = domain.update(name="New Name")  # domain remains unchanged
>>> updated.name
'New Name'

Update in-place:

>>> domain = Domain.get_domain("123")
>>> domain.update(name="New Name", in_place=True)  # domain is modified
>>> domain.name
'New Name'

Notes

Only name, description, and tags can be updated. Other properties like horizontal_resolution, vertical_resolution, features, etc. cannot be modified - you must create a new domain instead.

delete

delete() -> None

Delete an existing domain resource based on the domain ID.

The Domain object becomes invalid after deletion and should not be used for further operations. Doing so will raise a NotFoundException.

Returns:

Type	Description
None	Returns None on successful deletion

Examples:

>>> domain = Domain.from_id("abc123")
>>> domain.delete()  # Domain resource is permanently deleted

Perform operations on a deleted domain:

>>> domain.get()
# Raises NotFoundException

list_domains

list_domains(page: Optional[int] = None, size: Optional[int] = None, sort_by: Optional[str] = None, sort_order: Optional[str] = None) -> ListDomainResponse

Retrieve a paginated list of all domains accessible to the authenticated user.

Parameters:

Name	Type	Description	Default
page	int	The page number to retrieve (zero-indexed). Default is 0.	None
size	int	Number of domains to return per page. Must be between 1 and 1000. Default is 100.	None
sort_by	str	Field to sort the domains by. Valid values are: - "createdOn" - "modifiedOn" - "name" Default is "createdOn".	None
sort_order	str	Order in which to sort the results. Valid values are: - "ascending" - "descending" Default is "ascending".	None

Returns:

Type	Description
ListDomainResponse	A response object containing: - domains: List of Domain objects - currentPage: Current page number - pageSize: Number of domains per page - totalItems: Total number of domains available

Examples:

Get first page with default settings:

>>> response = list_domains()
>>> print(f"Found {len(response.domains)} domains")

Get specific page with custom size:

>>> response = list_domains(page=2, size=50)
>>> for domain in response.domains:
...     print(f"Domain {domain.id}: {domain.name}")

Sort domains by name:

>>> response = list_domains(sort_by="name", sort_order="ascending")

Notes

• Page numbers are zero-indexed, meaning the first page is 0.
• If no pagination parameters are provided, defaults to page 0 with 100 items.
• The maximum page size is 1000 items.
• When calculating total pages, use: ceil(response.totalItems / response.pageSize)

fastfuels_sdk.inventories

inventories.py

Inventories

Bases: Inventories

This class serves as an interface for interacting with the inventory data associated with a particular domain. It provides methods to fetch, update, and initialize inventory data from the API.

Attributes:

Name	Type	Description
domain_id	str	The ID of the domain associated with the inventory.
tree	(TreeInventory, optional)	The tree inventory data associated with the domain. By default, this attribute is None.

from_domain_id classmethod

from_domain_id(domain_id: str) -> Inventories

Constructs an Inventories instance from a given Domain object.

This class method interacts with the API to fetch the inventory data associated with the provided domain ID. The fetched data is then used to initialize and return an Inventories object.

Parameters:

Name	Type	Description	Default
domain_id	str	The ID of the domain to fetch inventory data for.	required

Returns:

Type	Description
Inventories	An instance of Inventories initialized with inventory data fetched using the domain ID.

Examples:

>>> from fastfuels_sdk import Inventories
>>> inventories = Inventories.from_domain_id("abc123")

get

get(in_place: bool = False)

Fetches the inventory data associated with the domain ID.

This method interacts with the API to fetch the inventory data associated with the domain ID. The fetched data is then used to update the Inventories object.

Parameters:

Name	Type	Description	Default
in_place	bool	If True, the method updates the current object with the fetched data. If False, the method returns a new object with the fetched data. Default is False.	False

Returns:

Type	Description
Inventories	An instance of Inventories updated with the fetched inventory data.

Examples:

>>> from fastfuels_sdk import Inventories
>>> inventories = Inventories.from_domain_id("abc123")
>>> # Fetch and update the inventory data
>>> updated_inventories = inventories.get()
>>> # Fetch and update the inventory data in place
>>> inventories.get(in_place=True)

create_tree_inventory

create_tree_inventory(sources: str | list[str] | TreeInventorySource | list[TreeInventorySource], tree_map: Optional[TreeMapSource | dict] = None, modifications: Optional[dict | list[dict]] = None, treatments: Optional[dict | list[dict]] = None, feature_masks: Optional[str | list[str]] = None, in_place: bool = False) -> TreeInventory

Create a tree inventory for the current domain.

This method generates a tree inventory using specified data sources and configurations. A tree inventory represents a complete forest inventory within the spatial context of your domain. Currently, TreeMap is the primary supported data source, providing nationwide coverage of tree data.

Parameters:

Name	Type	Description	Default
sources	str or list[str] or TreeInventorySource	Data source(s) to use for the tree inventory. Currently supports: - "TreeMap": Uses the TreeMap raster product for nationwide coverage	required
tree_map	TreeMapSource or dict	Configuration for TreeMap source if being used. Can be provided as a dict with: - version: "2014" or "2016" (default: "2016") - seed: Integer for reproducible generation (optional)	None
modifications	dict or list[dict]	List of modifications to apply. Each modification has: - conditions: List of conditions that must be met - actions: List of actions to apply when conditions are met Example: { "conditions": [{"field": "HT", "operator": "gt", "value": 20}], "actions": [{"field": "HT", "modifier": "multiply", "value": 0.9}] }	None
treatments	dict or list[dict]	List of silvicultural treatments to apply. Supports: Proportional Thinning: { "method": "proportionalThinning", "targetMetric": "basalArea", "targetValue": 25.0 # in m²/ha } Directional Thinning: { "method": "directionalThinning", "direction": "below", # or "above" "targetMetric": "diameter", # or "basalArea" "targetValue": 30.0 # cm for diameter, m²/ha for basalArea }	None
feature_masks	str or list[str]	Features to mask out from the inventory. Supported values: ["road", "water"]	None
in_place	bool	If True, updates this object's tree inventory (self.tree). If False (default), leaves this object unchanged.	False

Returns:

Type	Description
TreeInventory	The newly created tree inventory object.

Notes

• The inventory generation happens asynchronously. The returned inventory will initially have a "pending" status.
• Using the same seed value will generate the same trees when all other parameters are identical.

Examples:

>>> from fastfuels_sdk import Inventories
>>> inventories = Inventories.from_domain_id("abc123")

Basic usage with TreeMap:

>>> inventory = inventories.create_tree_inventory(sources="TreeMap")

Specify TreeMap version and seed:

>>> inventory = inventories.create_tree_inventory(
...     sources="TreeMap",
...     tree_map={"version": "2014", "seed": 42}
... )

Add height modification:

>>> inventory = inventories.create_tree_inventory(
...     sources="TreeMap",
...     modifications={
...         "conditions": [{"field": "HT", "operator": "gt", "value": 20}],
...         "actions": [{"field": "HT", "modifier": "multiply", "value": 0.9}]
...     }
... )

Add proportional thinning treatment:

>>> inventory = inventories.create_tree_inventory(
...     sources="TreeMap",
...     treatments={
...         "method": "proportionalThinning",
...         "targetMetric": "basalArea",
...         "targetValue": 25.0
...     }
... )

Mask out roads and water:

>>> inventory = inventories.create_tree_inventory(
...     sources="TreeMap",
...     feature_masks=["road", "water"]
... )

create_tree_inventory_from_treemap

create_tree_inventory_from_treemap(version: str = '2016', seed: int = None, canopy_height_map_source: Optional[str] = None, modifications: Optional[dict | list[dict]] = None, treatments: Optional[dict | list[dict]] = None, feature_masks: Optional[str | list[str]] = None, in_place: bool = False) -> TreeInventory

Create a tree inventory using TreeMap data for the current domain.

This is a convenience method that provides a simplified interface for creating tree inventories specifically from TreeMap data. While create_tree_inventory() offers a more general interface supporting multiple data sources, this method is optimized for the common case of using TreeMap data with a focus on the most relevant parameters.

Use this method when: - You want to create an inventory using TreeMap data (most common case) - You prefer a simpler interface focused on TreeMap-specific parameters - You want clearer defaults and documentation for TreeMap usage

Use create_tree_inventory() instead when: - You need to use data sources other than TreeMap - You prefer more explicit control over source configuration - You need to specify multiple data sources

Parameters:

Name	Type	Description	Default
version	str	The TreeMap version to use. Available versions: - "2016" (default) - More recent dataset, recommended for most use cases - "2014" - Earlier dataset, use if you need historical comparison	'2016'
seed	int	Random seed for reproducible tree generation. When provided, generates identical trees for the same domain and parameters. If omitted, generates different trees each time.	None
modifications	dict or list[dict]	Rules for modifying tree attributes. Each modification includes: - conditions: List of criteria that trees must meet - actions: Changes to apply to matching trees Example - Reduce height of tall trees: { "conditions": [{"field": "HT", "operator": "gt", "value": 20}], "actions": [{"field": "HT", "modifier": "multiply", "value": 0.9}] } Available fields: - HT: Height (meters) - DIA: Diameter at breast height (centimeters) - CR: Crown ratio (0-1) - SPCD: Species code (integer)	None
treatments	dict or list[dict]	Silvicultural treatments to apply. Supports: Proportional Thinning - Reduces stand density to target basal area: { "method": "proportionalThinning", "targetMetric": "basalArea", "targetValue": 25.0 # Target basal area in m²/ha } Directional Thinning - Removes trees based on size: { "method": "directionalThinning", "direction": "below", # "below" or "above" "targetMetric": "diameter", # "diameter" or "basalArea" "targetValue": 30.0 # cm for diameter, m²/ha for basalArea }	None
feature_masks	str or list[str]	Features to exclude from the inventory by removing trees that intersect with them. Available masks: - "road": Removes trees on roads - "water": Removes trees in water bodies	None
in_place	bool	Controls whether to update the current Inventories object: - If True, updates this object's tree inventory (self.tree) - If False (default), returns new inventory without modifying current object	False

Returns:

Type	Description
TreeInventory	The newly created tree inventory object.

Notes

• Generation is asynchronous - the inventory starts in "pending" status
• Final generation can take several minutes depending on domain size
• Check inventory.status for current state: "pending", "running", "completed"
• TreeMap accuracy varies by region and forest type
• Use same seed value to reproduce exact tree patterns

Examples:

>>> from fastfuels_sdk import Inventories
>>> inventories = Inventories.from_domain_id("abc123")

Basic inventory creation:

>>> tree_inventory = inventories.create_tree_inventory_from_treemap()

Reproducible inventory with specific version:

>>> tree_inventory = inventories.create_tree_inventory_from_treemap(
...     version="2014",
...     seed=42
... )

Reduce height of tall trees:

>>> tree_inventory = inventories.create_tree_inventory_from_treemap(
...     modifications={
...         "conditions": [{"field": "HT", "operator": "gt", "value": 20}],
...         "actions": [{"field": "HT", "modifier": "multiply", "value": 0.9}]
...     }
... )

Thin to target basal area:

>>> tree_inventory = inventories.create_tree_inventory_from_treemap(
...     treatments={
...         "method": "proportionalThinning",
...         "targetMetric": "basalArea",
...         "targetValue": 25.0
...     }
... )

Remove trees from roads and water:

>>> tree_inventory = inventories.create_tree_inventory_from_treemap(
...     feature_masks=["road", "water"]
... )

Combined modifications, thinning, and masks:

>>> tree_inventory = inventories.create_tree_inventory_from_treemap(
...     seed=42,
...     modifications={
...         "conditions": [{"field": "HT", "operator": "gt", "value": 20}],
...         "actions": [{"field": "HT", "modifier": "multiply", "value": 0.9}]
...     },
...     treatments={
...         "method": "proportionalThinning",
...         "targetMetric": "basalArea",
...         "targetValue": 25.0
...     },
...     feature_masks=["road", "water"]
... )

Apply a high resolution canopy height map data fusion:

>>> tree_inventory = inventories.create_tree_inventory_from_treemap(
...     canopy_height_map_source="Meta2024"
... )

create_tree_inventory_from_file_upload

create_tree_inventory_from_file_upload(file_path: Path | str) -> TreeInventory

Create a tree inventory using a file upload for the current domain.

This method uploads a CSV file containing tree inventory data and creates a new tree inventory for the domain. The file must follow specific format requirements and contain required columns with appropriate data types.

Parameters:

Name	Type	Description	Default
file_path	Path or str	Path to the CSV file containing the tree inventory data. The file must include the following columns: - TREE_ID (Integer): Unique identifier for each tree - SPCD (Integer): FIA species code - STATUSCD (Integer): Tree status code (0: No status, 1: Live, 2: Dead, 3: Missing) - DIA (Float): Diameter at breast height in cm (0-1200 cm, nullable) - HT (Float): Tree height in meters (0-116 m, nullable) - CR (Float): Crown ratio (0-1, nullable) - X (Float): X coordinate in projected coordinate system (nullable) - Y (Float): Y coordinate in projected coordinate system (nullable)	required

Returns:

Type	Description
TreeInventory	A TreeInventory object representing the newly created inventory. The inventory starts in "pending" status and is processed asynchronously. Use wait_until_completed() to wait for processing to finish.

Raises:

Type	Description
FileNotFoundError	If the specified file_path does not exist.
ValueError	If the file size exceeds 500MB or if the file is not a CSV.
ApiException	If there is an error communicating with the API.

Examples:

>>> from fastfuels_sdk import Inventories
>>> from pathlib import Path
>>> inventories = Inventories.from_domain_id("abc123")
>>> file_path = Path("my_trees.csv")
>>> # Create and wait for inventory
>>> inventory = inventories.create_tree_inventory_from_file_upload(file_path)
>>> inventory = inventory.wait_until_completed()
>>> print(inventory.status)
'completed'

Notes

File Format Requirements: - Maximum file size: 500MB - File type: CSV - Must include all required columns with correct data types - TREE_ID must be unique integers - Values must be within specified ranges - Trees must fall within domain bounds

TreeInventory

Bases: TreeInventory

A class representing a forest inventory within a spatial domain.

The TreeInventory class provides access to tree inventory data and operations for a specific domain. It supports creating inventories from various data sources (primarily TreeMap), monitoring inventory processing status, applying modifications and treatments, and exporting data in multiple formats.

Attributes:

Name	Type	Description
domain_id	str	The unique identifier of the domain this inventory belongs to.
status	str	Current processing status of the inventory: - "pending": Initial state after creation - "running": Being processed - "completed": Ready for use - "failed": Processing encountered an error
created_on	datetime	When the inventory was created.
modified_on	datetime	When the inventory was last modified.
checksum	str	Unique identifier for this version of the inventory.
sources	list[str]	Data sources used to generate the inventory (e.g. ["TreeMap"]).
tree_map	(TreeMapSource, optional)	Configuration used for TreeMap source, if applicable.
modifications	(list[TreeInventoryModification], optional)	Applied modifications to tree attributes.
treatments	(list[TreeInventoryTreatment], optional)	Applied silvicultural treatments.
feature_masks	(list[str], optional)	Applied feature masks (e.g. ["road", "water"]).

Methods:

Name	Description
from_domain	Retrieve an existing inventory for a domain.
get	Fetch the latest inventory data.
wait_until_completed	Wait for inventory processing to finish.
delete	Permanently remove this inventory.
create_export	Create an export of the inventory data.
get_export	Check status of an existing export.

Notes

• Tree inventories are created using Inventories.create_tree_inventory() or Inventories.create_tree_inventory_from_treemap()
• Processing is asynchronous - use wait_until_completed() to wait for the "completed" status
• Processing time varies with domain size, modifications, and treatments
• Once completed, inventories can be exported to CSV, Parquet, or GeoJSON formats
• A domain can only have one tree inventory at a time

See Also

Domain : Spatial container for inventory data Inventories : Container for domain inventory resources Export : Handles exporting inventory data

from_domain_id classmethod

from_domain_id(domain_id: str) -> TreeInventory

Retrieve an existing tree inventory for a domain.

This method fetches the tree inventory data associated with the provided domain. The tree inventory represents a complete forest inventory within the spatial context of your domain.

Parameters:

Name	Type	Description	Default
domain_id	str	The ID of the domain to retrieve the tree inventory for.	required

Returns:

Type	Description
TreeInventory	A TreeInventory object containing the retrieved inventory data.

Raises:

Type	Description
NotFoundException	If no tree inventory exists for the given domain or if the domain itself does not exist.
ApiException	If there is an error communicating with the API.

Examples:

>>> from fastfuels_sdk import TreeInventory
>>> inventory = TreeInventory.from_domain_id("abc123")
>>> print(inventory.status)
'completed'

Notes

• Tree inventories are typically created using Domain.create_tree_inventory() or Domain.create_tree_inventory_from_treemap()
• A domain can only have one tree inventory at a time
• Use get() to refresh the inventory data and wait_until_completed() to wait for processing to finish

get

get(in_place: bool = False)

Fetch the latest tree inventory data from the API.

This method retrieves the most recent tree inventory data for the domain, allowing you to check the current status and access updated information. You can either update the current TreeInventory instance in-place or get a new instance with the fresh data.

Parameters:

Name	Type	Description	Default
in_place	bool	If True, updates the current TreeInventory instance with the new data and returns self. If False (default), returns a new TreeInventory instance with the latest data, leaving the current instance unchanged.	False

Returns:

Type

Description

TreeInventory

Either the current TreeInventory instance (if in_place=True) or a new TreeInventory instance (if in_place=False) containing the latest data. Key attributes that may be updated include: - status: Current processing status - modified_on: Last modification timestamp - checksum: Unique identifier for this version - sources: Data sources used - tree_map: TreeMap configuration - modifications: Applied modifications - treatments: Applied treatments - feature_masks: Applied masks

Raises:

Type	Description
NotFoundException	If the tree inventory or domain no longer exists
ApiException	If there is an error communicating with the API

Examples:

>>> from fastfuels_sdk import TreeInventory
>>> inventory = TreeInventory.from_domain_id("abc123")

Create new instance with latest data:

>>> updated = inventory.get()  # inventory remains unchanged
>>> updated is inventory
False

Update existing instance in-place:

>>> inventory.get(in_place=True)  # inventory is updated
>>> # Any references to inventory now see the updated data

Notes

• The default behavior (in_place=False) ensures immutability by returning a new instance. This is safer for concurrent operations but requires reassignment if you want to retain the updated data.
• Use in_place=True when you want to ensure all references to this TreeInventory instance see the updated data.
• This method is often used in conjunction with wait_until_completed() to monitor the progress of tree inventory processing.

wait_until_completed

wait_until_completed(step: float = 5, timeout: float = 600, in_place: bool = True, verbose: bool = False) -> TreeInventory

Wait for the tree inventory processing to complete.

Tree inventories are processed asynchronously and may take between several seconds to minutes to complete depending on domain size and complexity. This method polls the API at regular intervals until the inventory reaches a 'completed' status or the timeout is reached.

Parameters:

Name	Type	Description	Default
step	float	Number of seconds to wait between status checks. Default is 5 seconds. Use larger values to reduce API calls, smaller values for more frequent updates.	5
timeout	float	Maximum number of seconds to wait for completion. Default is 600 seconds (10 minutes). If the timeout is reached before completion, raises a TimeoutError.	600
in_place	bool	If True (default), updates the current TreeInventory instance with new data at each check. If False, leaves the current instance unchanged and returns a new instance when complete.	True
verbose	bool	If True, prints status updates at each check. Default is False.	False

Returns:

Type	Description
TreeInventory	Either the current TreeInventory instance (if in_place=True) or a new TreeInventory instance (if in_place=False) with the completed inventory data.

Raises:

Type	Description
TimeoutError	If the tree inventory does not complete within the specified timeout.
NotFoundException	If the tree inventory or domain no longer exists.
ApiException	If there is an error communicating with the API.

Examples:

>>> from fastfuels_sdk import TreeInventory
>>> inventory = TreeInventory.from_domain_id("abc123")

Basic usage with default parameters:

>>> completed = inventory.wait_until_completed()
>>> print(completed.status)
'completed'

With progress updates:

>>> completed = inventory.wait_until_completed(
...     step=10,
...     timeout=1200,
...     verbose=True
... )
Tree inventory has status `pending` (10.00s)
Tree inventory has status `running` (20.00s)
Tree inventory has status `completed` (30.00s)

Without in-place updates:

>>> completed = inventory.wait_until_completed(in_place=False)
>>> completed is inventory
False

Notes

• Processing time varies based on domain size, data sources, modifications, and treatments
• The method polls by calling get() at each interval, which counts against API rate limits
• Consider longer step intervals for large domains or when making many API calls
• For very large domains, you may need to increase the timeout beyond the default 10 minutes

delete

delete() -> None

Delete this tree inventory.

Permanently removes the tree inventory from the domain. This action: - Deletes the tree inventory data from the database - Cancels any ongoing processing jobs - Removes associated data from cache and cloud storage - Cannot be undone

Returns:

Type	Description
None

Raises:

Type	Description
NotFoundException	If the tree inventory or domain no longer exists.
ApiException	If there is an error communicating with the API.

Examples:

>>> from fastfuels_sdk import TreeInventory
>>> tree_inventory = TreeInventory.from_domain_id("abc123")
>>> tree_inventory.delete()
>>> # The inventory is now permanently deleted
>>> tree_inventory.get()  # This will raise NotFoundException

Notes

• After deletion, any subsequent operations on this TreeInventory instance will raise NotFoundException
• A new tree inventory can be created for the domain after deletion using Domain.create_tree_inventory() or Domain.create_tree_inventory_from_treemap()
• Consider creating an export of important inventory data before deletion using create_export()

create_export

create_export(export_format: str) -> Export

Create an export of the tree inventory data.

Initiates an asynchronous process to export the tree inventory data into a specified file format. The export process runs in the background and generates a downloadable file once complete. Returns an Export object that provides methods for monitoring progress and downloading the result.

Parameters:

Name	Type	Description	Default
export_format	str	The desired format for the exported data. Must be one of: - "csv": Comma-separated values format - "parquet": Apache Parquet format (efficient for large datasets) - "geojson": GeoJSON format (includes spatial information)	required

Returns:

Type	Description
Export	An Export object for managing the export process.

Raises:

Type	Description
ApiException	If the tree inventory is not in "completed" status or if there is an error communicating with the API.

Examples:

>>> from fastfuels_sdk import TreeInventory
>>> tree_inventory = TreeInventory.from_domain_id("abc123")

Basic export with automatic filename:

>>> tree_inventory.wait_until_completed()
>>> # Create and wait for export
>>> export = tree_inventory.create_export("csv")
>>> export = export.wait_until_completed()
>>> # Download to current directory
>>> export.to_file("my/directory")  # Creates 'inventories_tree.csv' in 'my/directory'

Export with custom filename and progress monitoring:

>>> export = tree_inventory.create_export("parquet")
>>> export = export.wait_until_completed(
...     step=5,          # Check every 5 seconds
...     timeout=300,     # Wait up to 5 minutes
... )
>>> export.to_file("my_trees.parquet")

Create multiple format exports:

>>> # Create exports
>>> csv_export = tree_inventory.create_export("csv")
>>> parquet_export = tree_inventory.create_export("parquet")
>>> geojson_export = tree_inventory.create_export("geojson")
>>> # Wait for all to complete
>>> for export in [csv_export, parquet_export, geojson_export]:
...     export.wait_until_completed(in_place=True)
>>> # Download to a specific directory
>>> from pathlib import Path
>>> output_dir = Path("exports")
>>> output_dir.mkdir(exist_ok=True)
>>> for export in [csv_export, parquet_export, geojson_export]:
...     export.to_file(output_dir)

Notes

• The tree inventory must be in "completed" status before creating an export
• Export generation is asynchronous and may take several seconds or minutes depending on the data size
• Each format has specific advantages:
• CSV: Human-readable, compatible with most software
• Parquet: Efficient storage and querying for large datasets
• GeoJSON: Preserves spatial information, works with GIS software
• The Export object provides methods for monitoring and managing the export process - use get() to check status, wait_until_completed() to wait for completion, and to_file() to download

get_export

get_export(export_format: str) -> Export

Retrieve the status of an existing export.

Fetches the current state of a previously created export in the specified format. This method is commonly used to check if an export has completed and to get the download URL once it's ready.

Parameters:

Name	Type	Description	Default
export_format	str	The format of the export to retrieve. Must be one of: - "csv": Comma-separated values format - "parquet": Apache Parquet format - "geojson": GeoJSON format	required

Returns:

Type	Description
Export	An Export object representing the current state of the export.

Raises:

Type	Description
NotFoundException	If no export exists for the specified format.
ApiException	If there is an error communicating with the API.

Examples:

>>> from fastfuels_sdk import TreeInventory
>>> tree_inventory = TreeInventory.from_domain_id("abc123")

Check export status:

>>> export = tree_inventory.create_export("csv")

>>> # Check status later
>>> print(export.status)
'completed'
>>> if export.status == "completed":
...     export.to_file("trees.csv")

Monitor export until complete:

>>> from time import sleep
>>> export = tree_inventory.create_export("parquet")
>>> export.wait_until_completed(in_place=True)
>>> export.to_file("trees.parquet")

Notes

• This method only retrieves status; use create_export() to initiate a new export
• Export URLs expire after 7 days - you'll need to create a new export after expiration
• The Export object's wait_until_completed() method provides a more convenient way to wait for completion
• If you don't need the intermediate status checks, using create_export().wait_until_completed() is simpler
• Always check the export's status before attempting to download using to_file()

fastfuels_sdk.features

fastfuels_sdk/features.py

Features

Bases: Features

Geographic features (roads and water bodies) associated with a domain.

Attributes:

Name	Type	Description
domain_id	str	ID of the domain these features belong to
road	(RoadFeature, optional)	Road network data
water	(WaterFeature, optional)	Water body data

Examples:

>>> from fastfuels_sdk import Features
>>> features = Features.from_domain_id("abc123")

>>> # Access road data
>>> if features.road:
...     roads = features.road

>>> # Access water data
>>> if features.water:
...     water = features.water

>>> # Get updated feature data
>>> features = features.get()

See Also

Domain : Container for features RoadFeature : Road network structure WaterFeature : Water body structure

from_domain_id classmethod

from_domain_id(domain_id: str) -> Features

Retrieve the features (roads and water bodies) associated with a domain.

Parameters:

Name	Type	Description	Default
domain_id	str	The ID of the domain to retrieve features for	required

Returns:

Type	Description
Features	A Features object containing: - road : RoadFeature, optional Road network data within the domain - water : WaterFeature, optional Water bodies within the domain

Examples:

>>> from fastfuels_sdk import Features
>>> features = Features.from_domain_id("abc123")

>>> # Check for specific features. These will be None until created.
>>> if features.road:
...     print("Domain has road features")
>>> if features.water:
...     print("Domain has water features")

See Also

Features.get : Refresh feature data

get

get(in_place: bool = False) -> Features

Get the latest feature data for this domain.

Parameters:

Name	Type	Description	Default
in_place	bool	If True, updates this Features instance with new data. If False (default), returns a new Features instance.	False

Returns:

Type	Description
Features	The updated Features object

Examples:

>>> from fastfuels_sdk import Features
>>> features = Features.from_domain_id("abc123")
>>> # Get fresh data in a new instance
>>> updated_features = features.get()
>>>
>>> # Or update the existing instance
>>> features.get(in_place=True)

See Also

Features.from_domain : Get features for a specific domain

create_road_feature

create_road_feature(sources: str | List[str] | RoadFeatureSource | List[RoadFeatureSource], in_place: bool = False) -> RoadFeature

Create road features for this domain using specified data sources.

Parameters:

Name	Type	Description	Default
sources	str or list[str] or RoadFeatureSource or list[RoadFeatureSource]	Data sources to use. Currently, supports: - "OSM": OpenStreetMap data	required
in_place	bool	If True, updates this Features instance with new data. If False (default), leaves this instance unchanged.	False

Returns:

Type	Description
RoadFeature	The newly created road feature object

Examples:

>>> from fastfuels_sdk import Features
>>> features = Features.from_domain_id("abc123")
>>> # Create from OpenStreetMap
>>> road = features.create_road_feature("OSM")
>>>
>>> # Update Features instance
>>> features.create_road_feature("OSM", in_place=True)
>>> features.road.status
"pending"

See Also

Features.create_road_feature_from_osm : Simpler method for OSM data

create_road_feature_from_osm

create_road_feature_from_osm(in_place: bool = False) -> RoadFeature

Create road features for this domain using OpenStreetMap data.

This is a convenience method that provides a simpler interface for the common case of using OpenStreetMap as the data source.

Parameters:

Name	Type	Description	Default
in_place	bool	If True, updates this Features instance with new data. If False (default), leaves this instance unchanged.	False

Returns:

Type	Description
RoadFeature	The newly created road feature object

Examples:

>>> from fastfuels_sdk import Features
>>> features = Features.from_domain_id("abc123")
>>> # Create new road features
>>> road = features.create_road_feature_from_osm()
>>>
>>> # Update Features instance
>>> features.create_road_feature_from_osm(in_place=True)
>>> features.road.status
"pending"

See Also

Features.create_road_feature : More general method supporting multiple sources

create_water_feature

create_water_feature(sources: str | List[str] | WaterFeatureSource | List[WaterFeatureSource], in_place: bool = False) -> WaterFeature

Create water features for this domain using specified data sources.

Parameters:

Name	Type	Description	Default
sources	str or list[str] or WaterFeatureSource or list[WaterFeatureSource]	Data sources to use. Currently, supports: - "OSM": OpenStreetMap data	required
in_place	bool	If True, updates this Features instance with new data. If False (default), leaves this instance unchanged.	False

Returns:

Type	Description
WaterFeature	The newly created water feature object

Examples:

>>> from fastfuels_sdk import Features
>>> features = Features.from_domain_id("abc123")
>>>
>>> # Create from OpenStreetMap
>>> water = features.create_water_feature("OSM")
>>>
>>> # Update Features instance
>>> features.create_water_feature("OSM", in_place=True)
>>> features.water.status
"pending"

See Also

Features.create_water_feature_from_osm : Simpler method for OSM data

create_water_feature_from_osm

create_water_feature_from_osm(in_place: bool = False) -> WaterFeature

Create water features for this domain using OpenStreetMap data.

This is a convenience method that provides a simpler interface for the common case of using OpenStreetMap as the data source.

Parameters:

Name	Type	Description	Default
in_place	bool	If True, updates this Features instance with new data. If False (default), leaves this instance unchanged.	False

Returns:

Type	Description
WaterFeature	The newly created water feature object

Examples:

>>> from fastfuels_sdk import Features
>>> features = Features.from_domain_id("abc123")
>>>
>>> # Create new water features
>>> water = features.create_water_feature_from_osm()
>>>
>>> # Update Features instance with new water feature
>>> features.create_water_feature_from_osm(in_place=True)
>>> features.water.status
"pending"

See Also

Features.create_water_feature : More general method supporting multiple sources

RoadFeature

Bases: RoadFeature

Road network features within a domain's spatial boundaries.

Represents road features extracted from various data sources (like OpenStreetMap) within a domain. Road features include information about road locations, types, and attributes.

Attributes:

Name	Type	Description
domain_id	str	ID of the domain these roads belong to
sources	list[RoadFeatureSource]	Data sources used to create these features
status	(str, optional)	Current processing status ("pending", "running", "completed")
created_on	(datetime, optional)	When these features were created
modified_on	(datetime, optional)	When these features were last modified
checksum	(str, optional)	Unique identifier for this version of the features

Examples:

>>> from fastfuels_sdk.features import Features
Get existing road features:
>>> features = Features.from_domain_id("abc123")
>>> if features.road:
...     road_features = features.road

Create new road features:

>>> road_features = features.create_road_feature("OSM")
>>> print(road_features.status)
'pending'

get

get(in_place: bool = False) -> RoadFeature

Get the latest road feature data.

Parameters:

Name	Type	Description	Default
in_place	bool	If True, updates this RoadFeature instance with new data. If False (default), returns a new RoadFeature instance.	False

Returns:

Type	Description
RoadFeature	The updated road feature object

Examples:

>>> from fastfuels_sdk import Features
>>> features = Features.from_domain_id("abc123")
>>> road = features.create_road_feature("OSM")
>>> # Get fresh data in a new instance
>>> updated_road = road.get()
>>>
>>> # Or update the existing instance
>>> road.get(in_place=True)

wait_until_completed

wait_until_completed(step: float = 5, timeout: float = 600, in_place: bool = True, verbose: bool = False) -> RoadFeature

Wait for road feature processing to complete.

Road features are processed asynchronously and may take several seconds to minutes to complete depending on domain size and data sources.

Parameters:

Name	Type	Description	Default
step	float	Seconds between status checks (default: 5)	5
timeout	float	Maximum seconds to wait (default: 600)	600
in_place	bool	If True (default), updates this instance with completed data. If False, returns a new instance.	True
verbose	bool	If True, prints status updates (default: False)	False

Returns:

Type	Description
RoadFeature	The completed road feature object

Examples:

>>> from fastfuels_sdk import Features
>>> features = Features.from_domain_id("abc123")
>>> road = features.create_road_feature("OSM")
>>> road.wait_until_completed(verbose=True)
Road features have status `pending` (5.00s)
Road features have status `completed` (10.00s)

delete

delete() -> None

Delete these road features.

Permanently removes road feature data from the domain. This also cancels any ongoing processing jobs.

Returns:

Type	Description
None

Examples:

>>> from fastfuels_sdk import Features
>>> features = Features.from_domain_id("abc123")
>>> road = features.create_road_feature("OSM")
>>> # Remove road features when no longer needed
>>> road.delete()
>>> # Subsequent operations will raise NotFoundException
>>> road.get()  # raises NotFoundException

WaterFeature

Bases: WaterFeature

Water body features within a domain's spatial boundaries.

Represents water features extracted from various data sources (like OpenStreetMap) within a domain. Water features include information about water body locations, types, and attributes.

Attributes:

Name	Type	Description
domain_id	str	ID of the domain these water bodies belong to
sources	list[WaterFeatureSource]	Data sources used to create these features
status	(str, optional)	Current processing status ("pending", "running", "completed")
created_on	(datetime, optional)	When these features were created
modified_on	(datetime, optional)	When these features were last modified
checksum	(str, optional)	Unique identifier for this version of the features

Examples:

Get existing water features:

>>> from fastfuels_sdk import Features
>>> features = Features.from_domain_id("abc123")
>>> if features.water:
...     water_features = features.water

Create new water features:

>>> water_features = features.create_water_feature("OSM")
>>> print(water_features.status)
'pending'

get

get(in_place: bool = False) -> WaterFeature

Get the latest water feature data.

Parameters:

Name	Type	Description	Default
in_place	bool	If True, updates this WaterFeature instance with new data. If False (default), returns a new WaterFeature instance.	False

Returns:

Type	Description
WaterFeature	The updated water feature object

Examples:

>>> from fastfuels_sdk import Features
>>> features = Features.from_domain_id("abc123")
>>> water = features.create_water_feature("OSM")
>>> # Get fresh data in a new instance
>>> updated_water = water.get()
>>>
>>> # Or update the existing instance
>>> water.get(in_place=True)

wait_until_completed

wait_until_completed(step: float = 5, timeout: float = 600, in_place: bool = True, verbose: bool = False) -> WaterFeature

Wait for water feature processing to complete.

Water features are processed asynchronously and may take several seconds to minutes to complete depending on domain size and data sources.

Parameters:

Name	Type	Description	Default
step	float	Seconds between status checks (default: 5)	5
timeout	float	Maximum seconds to wait (default: 600)	600
in_place	bool	If True (default), updates this instance with completed data. If False, returns a new instance.	True
verbose	bool	If True, prints status updates (default: False)	False

Returns:

Type	Description
WaterFeature	The completed water feature object

Examples:

>>> from fastfuels_sdk import Features
>>> features = Features.from_domain_id("abc123")
>>> water = features.create_water_feature("OSM")
>>> water.wait_until_completed(verbose=True)
Water features have status `pending` (5.00s)
Water features have status `completed` (10.00s)

delete

delete() -> None

Delete these water features.

Permanently removes water feature data from the domain. This also cancels any ongoing processing jobs.

Returns:

Type	Description
None

Examples:

>>> from fastfuels_sdk import Features
>>> features = Features.from_domain_id("abc123")
>>> water = features.create_water_feature("OSM")
>>> # Remove water features when no longer needed
>>> water.delete()
>>> # Subsequent operations will raise NotFoundException
>>> water.get()  # raises NotFoundException

fastfuels_sdk.grids

Grids

Bases: Grids

Container for different types of gridded data within a domain's spatial boundaries.

A Grids object provides access to various types of gridded data (tree, surface, topography, and feature) associated with a specific domain. Each grid type represents different aspects of the landscape and can be exported in different formats for use in fire behavior modeling.

Attributes:

Name	Type	Description
domain_id	str	ID of the domain these grids belong to
tree	(TreeGrid, optional)	3D tree canopy data
surface	(SurfaceGrid, optional)	Surface fuel data
topography	(TopographyGrid, optional)	Elevation and terrain data
feature	(FeatureGrid, optional)	Road, water, and other geographic features

Examples:

>>> from fastfuels_sdk import Grids
>>> grids = Grids.from_domain_id("abc123")

>>> # Access specific grid types
>>> if grids.tree:
...     print("Domain has tree grid data")
>>> if grids.surface:
...     print("Domain has surface fuel data")

>>> # Export grids to QUIC-Fire format
>>> export = grids.create_export("QUIC-Fire")
>>> export.wait_until_completed()
>>> export.to_file("grid_data.zip")

See Also

Domain : Spatial container for grids TreeGrid : 3D canopy structure SurfaceGrid : Surface fuel properties TopographyGrid : Elevation data FeatureGrid : Geographic features

from_domain_id classmethod

from_domain_id(domain_id: str) -> Grids

Retrieve the grids associated with a domain.

Parameters:

Name	Type	Description	Default
domain_id	str	The ID of the domain to retrieve grids for	required

Returns:

Type	Description
Grids	The grid data for the domain

Examples:

>>> grids = Grids.from_domain_id("abc123")

>>> # Check for specific grid types
>>> if grids.tree:
...     print("Domain has tree grid data")
>>> if grids.surface:
...     print("Domain has surface grid data")

get

get(in_place: bool = False) -> Grids

Get the latest grid data for this domain.

Parameters:

Name	Type	Description	Default
in_place	bool	If True, updates this Grids instance with new data. If False (default), returns a new Grids instance.	False

Returns:

Type	Description
Grids	The updated Grids object

Examples:

>>> grids = Grids.from_domain_id("abc123")

>>> # Get fresh data in a new instance
>>> updated_grids = grids.get()

>>> # Or update the existing instance
>>> grids.get(in_place=True)

create_surface_grid

create_surface_grid(attributes: List[str], fuel_load: Optional[dict] = None, fuel_depth: Optional[dict] = None, fuel_moisture: Optional[dict] = None, savr: Optional[dict] = None, fbfm: Optional[dict] = None, modifications: Optional[dict | list[dict]] = None, in_place: bool = False) -> SurfaceGrid

Create a surface grid for the current domain.

Creates a surface grid containing various fuel and vegetation attributes within the spatial context of your domain. While this method provides direct creation capability, consider using SurfaceGridBuilder for more complex configurations and better parameter validation.

Parameters:

Name	Type	Description	Default
attributes	List[str]	List of attributes to include in the grid. Available attributes: - "fuelLoad": Surface fuel loading - "fuelDepth": Depth of surface fuels - "fuelMoisture": Moisture content of fuels - "SAVR": Surface area to volume ratio - "FBFM": Fire Behavior Fuel Model	required
fuel_load	dict	Configuration for fuel load attribute. See SurfaceGridBuilder for details.	None
fuel_depth	dict	Configuration for fuel depth attribute. See SurfaceGridBuilder for details.	None
fuel_moisture	dict	Configuration for fuel moisture content. See SurfaceGridBuilder for details.	None
savr	dict	Configuration for surface area to volume ratio. See SurfaceGridBuilder for details.	None
fbfm	dict	Configuration for Fire Behavior Fuel Model. See SurfaceGridBuilder for details.	None
modifications	dict or list[dict]	Rules for modifying grid attributes. See SurfaceGridBuilder for details.	None
in_place	bool	If True, updates this object's surface grid (self.surface). If False (default), leaves this object unchanged.	False

Returns:

Type	Description
SurfaceGrid	The newly created surface grid object.

Notes

Grid generation happens asynchronously. The returned grid will initially have a "pending" status.

Examples:

>>> from fastfuels_sdk import Grids
>>> grids = Grids.from_domain_id("abc123")

Simple usage with uniform values:

>>> grid = grids.create_surface_grid(
...     attributes=["fuelLoad", "fuelMoisture"],
...     fuel_load={"source": "uniform", "value": 0.5},
...     fuel_moisture={"source": "uniform", "value": 0.1}
... )

See Also

SurfaceGridBuilder : Helper class for creating complex surface grid configurations with parameter validation and a fluent interface.

create_topography_grid

create_topography_grid(attributes: List[str], elevation: Optional[dict] = None, slope: Optional[dict] = None, aspect: Optional[dict] = None, in_place: bool = False) -> TopographyGrid

Create a topography grid for the current domain.

Creates a topography grid containing elevation, slope, and/or aspect data within the spatial context of your domain.

Parameters:

Name	Type	Description	Default
attributes	List[str]	List of attributes to include in the grid. Available attributes: - "elevation": Terrain elevation above sea level - "slope": Slope of terrain surface - "aspect": Direction the slope faces	required
elevation	dict	Configuration for elevation attribute. Sources available: - 3DEP (default): { "source": "3DEP", "interpolationMethod": "cubic" # or "nearest", "linear" } - LANDFIRE: { "source": "LANDFIRE", "version": "2020", "interpolationMethod": "cubic" # or "nearest", "linear", "zipper" } - Uniform: { "source": "uniform", "value": float # elevation in meters }	None
slope	dict	Configuration for slope attribute. Sources available: - 3DEP (default): { "source": "3DEP", "interpolationMethod": "cubic" # or "nearest", "linear" } - LANDFIRE: { "source": "LANDFIRE", "version": "2020", "interpolationMethod": "cubic" # or "nearest", "linear", "zipper" }	None
aspect	dict	Configuration for aspect attribute. Sources available: - 3DEP (default): { "source": "3DEP", "interpolationMethod": "nearest" } - LANDFIRE: { "source": "LANDFIRE", "version": "2020", "interpolationMethod": "nearest" }	None
in_place	bool	If True, updates this object's topography grid (self.topography). If False (default), leaves this object unchanged.	False

Returns:

Type	Description
TopographyGrid	The newly created topography grid object.

Notes

Grid generation happens asynchronously. The returned grid will initially have a "pending" status.

Examples:

>>> from fastfuels_sdk import Grids
>>> grids = Grids.from_domain_id("abc123")

Simple usage with default 3DEP source:

>>> grid = grids.create_topography_grid(
...     attributes=["elevation", "slope"]
... )

Using multiple data sources:

>>> grid = grids.create_topography_grid(
...     attributes=["elevation", "slope", "aspect"],
...     elevation={
...         "source": "LANDFIRE",
...         "version": "2020",
...         "interpolationMethod": "cubic"
...     },
...     slope={
...         "source": "3DEP",
...         "interpolationMethod": "cubic"
...     }
... )

create_tree_grid

create_tree_grid(attributes: List[str], bulk_density: Optional[dict] = None, spcd: Optional[dict] = None, fuel_moisture: Optional[dict] = None, in_place: bool = False) -> TreeGrid

Create a tree grid for the current domain.

Creates a tree grid containing canopy bulk density, species codes, and/or fuel moisture data within the spatial context of your domain. While this method provides direct creation capability, consider using TreeGridBuilder for more complex configurations and better parameter validation.

Parameters:

Name	Type	Description	Default
attributes	List[str]	List of attributes to include in the grid. Available attributes: - "bulkDensity": Canopy bulk density - "SPCD": Species code - "fuelMoisture": Moisture content	required
bulk_density	dict	Configuration for bulk density attribute. Sources available: - Inventory: { "source": "inventory" } - Uniform: { "source": "uniform", "value": float # bulk density in kg/m³ }	None
spcd	dict	Configuration for species code attribute. Sources available: - Inventory: { "source": "inventory" } - Uniform: { "source": "uniform", "value": str # species code }	None
fuel_moisture	dict	Configuration for fuel moisture content. Only supports uniform values: { "source": "uniform", "value": float # moisture content in % }	None
in_place	bool	If True, updates this object's tree grid (self.tree). If False (default), leaves this object unchanged.	False

Returns:

Type	Description
TreeGrid	The newly created tree grid object.

Notes

Grid generation happens asynchronously. The returned grid will initially have a "pending" status.

Examples:

>>> from fastfuels_sdk import Grids
>>> grids = Grids.from_domain_id("abc123")

Simple usage with uniform values:

>>> grid = grids.create_tree_grid(
...     attributes=["bulkDensity", "fuelMoisture"],
...     bulk_density={"source": "uniform", "value": 0.5},
...     fuel_moisture={"source": "uniform", "value": 15.0}
... )

Using inventory data:

>>> grid = grids.create_tree_grid(
...     attributes=["bulkDensity", "SPCD"],
...     bulk_density={"source": "inventory"},
...     spcd={"source": "inventory"}
... )

See Also

TreeGridBuilder : Helper class for creating complex tree grid configurations with parameter validation and a fluent interface.

create_feature_grid

create_feature_grid(attributes: List[str], in_place: bool = False) -> FeatureGrid

Create a feature grid for the current domain.

Creates a feature grid containing various geographic features within the spatial context of your domain. Feature grids represent spatial data related to various features such as roads, water bodies, and other geographic elements.

Feature resources must have a "completed" status before they can be included as attributes to a feature grid.

Parameters:

Name	Type	Description	Default
attributes	List[str]	List of feature types to rasterize in the grid. Available attributes depend on the specific geographic features in your domain area.	required
in_place	bool	If True, updates this object's feature grid (self.feature). If False (default), leaves this object unchanged.	False

Returns:

Type	Description
FeatureGrid	The newly created feature grid object.

Notes

Grid generation happens asynchronously. The returned grid will initially have a "pending" status.

Examples:

>>> from fastfuels_sdk import Grids
>>> grids = Grids.from_domain_id("abc123")

Simple usage with specific feature types:

>>> grid = grids.create_feature_grid(
...     attributes=["road", "water"]
... )

Create and wait for completion:

>>> grid = grids.create_feature_grid(
...     attributes=["road", "water"],
...     in_place=True
... )
>>> grid.wait_until_completed()

create_export

create_export(export_format: str) -> Export

Create an export of the grid data.

Parameters:

Name	Type	Description	Default
export_format	str	Format to export the data in. Must be one of: - "zarr": Compressed array format - "QUIC-Fire": Input files for QUIC-Fire model	required

Returns:

Type	Description
Export	An Export object for managing the export process.

Notes

The QUIC-Fire format creates a zip file with: - treesrhof.dat: Bulk density data - treesmoist.dat: Moisture content data - treesdepth.dat: Canopy depth data - topo.dat: Topography data (if available)

Examples:

>>> grids = Grids.from_domain_id("abc123")

>>> export = grids.create_export("QUIC-Fire")
>>> export.wait_until_completed()
>>> export.to_file("grid_data.zip")

get_export

get_export(export_format: str) -> Export

Get the status of an existing export.

Parameters:

Name	Type	Description	Default
export_format	str	Format of the export to check. Must be one of: - "zarr": Compressed array format - "QUIC-Fire": Input files for QUIC-Fire model	required

Returns:

Type	Description
Export	An Export object containing current status.

Examples:

>>> from fastfuels_sdk import Grids
>>> grids = Grids.from_domain_id("abc123")
>>> export = grids.create_export("zarr")
>>> # Check status later
>>> updated_export = grids.get_export("zarr")
>>> if export.status == "completed":
...     export.to_file("grid_data.zarr")

TreeGrid

Bases: TreeGrid

Tree grid data within a domain's spatial boundaries.

from_domain_id classmethod

from_domain_id(domain_id: str) -> TreeGrid

Retrieve an existing tree grid for a domain.

Parameters:

Name	Type	Description	Default
domain_id	str	ID of the domain to retrieve tree grid for	required

Returns:

Type	Description
TreeGrid	The tree grid object

Examples:

>>> tree_grid = TreeGrid.from_domain_id("abc123")
>>> tree_grid.status
'completed'

get

get(in_place: bool = False) -> TreeGrid

Get the latest tree grid data.

Parameters:

Name	Type	Description	Default
in_place	bool	If True, updates this TreeGrid instance with new data. If False (default), returns a new TreeGrid instance.	False

Returns:

Type	Description
TreeGrid	The updated tree grid object

Examples:

>>> from fastfuels_sdk import TreeGrid
>>> tree_grid = TreeGrid.from_domain_id("abc123")
>>>
>>> # Get fresh data in a new instance
>>> updated_grid = tree_grid.get()
>>>
>>> # Or update the existing instance
>>> tree_grid.get(in_place=True)

wait_until_completed

wait_until_completed(step: float = 5, timeout: float = 600, in_place: bool = True, verbose: bool = False) -> 'TreeGrid'

Wait for the tree grid processing to complete.

Tree grids are processed asynchronously and may take between several seconds to minutes to complete depending on domain size and complexity. This method polls the API at regular intervals until the grid reaches a 'completed' status or the timeout is reached.

Parameters:

Name	Type	Description	Default
step	float	Number of seconds to wait between status checks. Default is 5 seconds. Use larger values to reduce API calls, smaller values for more frequent updates.	5
timeout	float	Maximum number of seconds to wait for completion. Default is 600 seconds (10 minutes). If the timeout is reached before completion, raises a TimeoutError.	600
in_place	bool	If True (default), updates the current TreeGrid instance with new data at each check. If False, leaves the current instance unchanged and returns a new instance when complete.	True
verbose	bool	If True, prints status updates at each check. Default is False.	False

Returns:

Type	Description
TreeGrid	Either the current TreeGrid instance (if in_place=True) or a new TreeGrid instance (if in_place=False) with the completed grid data.

Raises:

Type	Description
TimeoutError	If the tree grid does not complete within the specified timeout.
NotFoundException	If the tree grid or domain no longer exists.
ApiException	If there is an error communicating with the API.

Examples:

Basic usage with default parameters: from fastfuels_sdk import TreeGrid

>>> grid = TreeGrid.from_domain_id("abc123")
>>> completed = grid.wait_until_completed()
>>> print(completed.status)
'completed'

With progress updates:

>>> completed = grid.wait_until_completed(
...     step=10,
...     timeout=1200,
...     verbose=True
... )
Tree grid has status `pending` (10.00s)
Tree grid has status `running` (20.00s)
Tree grid has status `completed` (30.00s)

get_attributes

get_attributes() -> GridAttributeMetadataResponse

Get metadata about grid attributes.

Returns metadata about the structure of the tree grid and its attributes, including dimensions, chunking, and attribute details.

Returns:

Type	Description
GridAttributeMetadataResponse	Metadata about grid structure and attributes including: - shape: Dimensions of the grid data - dimensions: Names of each dimension - chunks: Number of chunks in each dimension - chunk_shape: Shape of each chunk - attributes: Detailed information about each attribute

Examples:

>>> from fastfuels_sdk import TreeGrid
>>> tree_grid = TreeGrid.from_domain_id("abc123")
>>> metadata = tree_grid.get_attributes()
>>> print(metadata.shape)
[100, 100, 50]

create_export

create_export(export_format: str) -> Export

Create an export of the tree grid data.

Parameters:

Name	Type	Description	Default
export_format	str	Format for the export. Must be one of: - "zarr": Compressed array format	required

Returns:

Type	Description
Export	An Export object for managing the export process

Examples:

>>> from fastfuels_sdk import TreeGrid
>>> tree_grid = TreeGrid.from_domain_id("abc123")
>>> export = tree_grid.create_export("zarr")
>>> export.wait_until_completed()
>>> export.to_file("grid_data.zarr")

get_export

get_export(export_format: str) -> Export

Get the status of an existing export.

Parameters:

Name	Type	Description	Default
export_format	str	Format of the export to check. Must be one of: - "zarr": Compressed array format	required

Returns:

Type	Description
Export	An Export object containing current status

Examples:

>>> from fastfuels_sdk import TreeGrid
>>> tree_grid = TreeGrid.from_domain_id("abc123")
>>> export = tree_grid.create_export("zarr")
>>> export.wait_until_completed()
>>> export.to_file("grid_data.zarr")

delete

delete() -> None

Delete this tree grid.

Permanently removes tree grid data from the domain. This also cancels any ongoing processing jobs.

Returns:

Type	Description
None

Examples:

>>> from fastfuels_sdk import TreeGrid
>>> tree_grid = TreeGrid.from_domain_id("abc123")
>>> # Remove grid when no longer needed
>>> tree_grid.delete()
>>> # Subsequent operations will raise NotFoundException
>>> tree_grid.get()  # raises NotFoundException

FeatureGrid

Bases: FeatureGrid

Feature grid data within a domain's spatial boundaries.

from_domain_id classmethod

from_domain_id(domain_id: str) -> 'FeatureGrid'

Retrieve an existing feature grid for a domain.

Parameters:

Name	Type	Description	Default
domain_id	str	ID of the domain to retrieve feature grid for	required

Returns:

Type	Description
FeatureGrid	The feature grid object

Examples:

>>> grid = FeatureGrid.from_domain_id("abc123")
>>> print(grid.status)
'completed'

get

get(in_place: bool = False) -> 'FeatureGrid'

Get the latest feature grid data.

Parameters:

Name	Type	Description	Default
in_place	bool	If True, updates this FeatureGrid instance with new data. If False (default), returns a new FeatureGrid instance.	False

Returns:

Type	Description
FeatureGrid	The updated feature grid object

Examples:

>>> from fastfuels_sdk import FeatureGrid
>>> grid = FeatureGrid.from_domain_id("abc123")

>>> # Get fresh data in a new instance
>>> updated_grid = grid.get()

>>> # Or update the existing instance
>>> grid.get(in_place=True)

wait_until_completed

wait_until_completed(step: float = 5, timeout: float = 600, in_place: bool = True, verbose: bool = False) -> 'FeatureGrid'

Wait for the feature grid processing to complete.

Feature grids are processed asynchronously and may take between several seconds to minutes to complete depending on domain size and complexity. This method polls the API at regular intervals until the grid reaches a 'completed' status or the timeout is reached.

Parameters:

Name	Type	Description	Default
step	float	Number of seconds to wait between status checks. Default is 5 seconds. Use larger values to reduce API calls, smaller values for more frequent updates.	5
timeout	float	Maximum number of seconds to wait for completion. Default is 600 seconds (10 minutes). If the timeout is reached before completion, raises a TimeoutError.	600
in_place	bool	If True (default), updates the current FeatureGrid instance with new data at each check. If False, leaves the current instance unchanged and returns a new instance when complete.	True
verbose	bool	If True, prints status updates at each check. Default is False.	False

Returns:

Type	Description
FeatureGrid	Either the current FeatureGrid instance (if in_place=True) or a new FeatureGrid instance (if in_place=False) with the completed grid data.

Raises:

Type	Description
TimeoutError	If the feature grid does not complete within the specified timeout.
NotFoundException	If the feature grid or domain no longer exists.
ApiException	If there is an error communicating with the API.

Examples:

>>> from fastfuels_sdk import FeatureGrid
>>> grid = FeatureGrid.from_domain_id("abc123")

Basic usage with default parameters:

>>> completed = grid.wait_until_completed()
>>> print(completed.status)
'completed'

With progress updates:

>>> completed = grid.wait_until_completed(
...     step=10,
...     timeout=1200,
...     verbose=True
... )
Feature grid has status `pending` (10.00s)
Feature grid has status `running` (20.00s)
Feature grid has status `completed` (30.00s)

Without in-place updates:

>>> completed = grid.wait_until_completed(in_place=False)
>>> completed is grid
False

Notes

• Processing time varies based on domain size and grid configuration
• The method polls by calling get() at each interval, which counts against API rate limits
• Consider longer step intervals for large domains or when making many API calls
• For very large domains, you may need to increase the timeout beyond the default 10 minutes

get_attributes

get_attributes() -> GridAttributeMetadataResponse

Get metadata about grid attributes.

Returns metadata about the structure of the feature grid and its attributes, including dimensions, chunking, and attribute details.

Returns:

Type	Description
GridAttributeMetadataResponse	Metadata about grid structure and attributes including: - shape: Dimensions of the grid data - dimensions: Names of each dimension - chunks: Number of chunks in each dimension - chunk_shape: Shape of each chunk - attributes: Detailed information about each attribute

Examples:

>>> from fastfuels_sdk import FeatureGrid
>>> grid = FeatureGrid.from_domain_id("abc123")
>>> metadata = grid.get_attributes()
>>> print(metadata.shape)
[100, 100, 50]

delete

delete() -> None

Delete this feature grid.

Permanently removes feature grid data from the domain. This also cancels any ongoing processing jobs.

Returns:

Type	Description
None

Examples:

>>> from fastfuels_sdk import FeatureGrid
>>> grid = FeatureGrid.from_domain_id("abc123")
>>> # Remove grid when no longer needed
>>> grid.delete()
>>> # Subsequent operations will raise NotFoundException
>>> grid.get()  # raises NotFoundException

SurfaceGrid

Bases: SurfaceGrid

Surface grid data within a domain's spatial boundaries.

from_domain_id classmethod

from_domain_id(domain_id: str) -> 'SurfaceGrid'

Retrieve an existing surface grid for a domain.

Parameters:

Name	Type	Description	Default
domain_id	str	ID of the domain to retrieve surface grid for	required

Returns:

Type	Description
SurfaceGrid	The surface grid object

Examples:

>>> grid = SurfaceGrid.from_domain_id("abc123")
>>> print(grid.status)
'completed'

get

get(in_place: bool = False) -> 'SurfaceGrid'

Get the latest surface grid data.

Parameters:

Name	Type	Description	Default
in_place	bool	If True, updates this SurfaceGrid instance with new data. If False (default), returns a new SurfaceGrid instance.	False

Returns:

Type	Description
SurfaceGrid	The updated surface grid object

Examples:

>>> from fastfuels_sdk import SurfaceGrid
>>> grid = SurfaceGrid.from_domain_id("abc123")

>>> # Get fresh data in a new instance
>>> updated_grid = grid.get()

>>> # Or update the existing instance
>>> grid.get(in_place=True)

wait_until_completed

wait_until_completed(step: float = 5, timeout: float = 600, in_place: bool = True, verbose: bool = False) -> 'SurfaceGrid'

Wait for the surface grid processing to complete.

Surface grids are processed asynchronously and may take between several seconds to minutes to complete depending on domain size and complexity. This method polls the API at regular intervals until the grid reaches a 'completed' status or the timeout is reached.

Parameters:

Name	Type	Description	Default
step	float	Number of seconds to wait between status checks. Default is 5 seconds. Use larger values to reduce API calls, smaller values for more frequent updates.	5
timeout	float	Maximum number of seconds to wait for completion. Default is 600 seconds (10 minutes). If the timeout is reached before completion, raises a TimeoutError.	600
in_place	bool	If True (default), updates the current SurfaceGrid instance with new data at each check. If False, leaves the current instance unchanged and returns a new instance when complete.	True
verbose	bool	If True, prints status updates at each check. Default is False.	False

Returns:

Type	Description
SurfaceGrid	Either the current SurfaceGrid instance (if in_place=True) or a new SurfaceGrid instance (if in_place=False) with the completed grid data.

Raises:

Type	Description
TimeoutError	If the surface grid does not complete within the specified timeout.
NotFoundException	If the surface grid or domain no longer exists.
ApiException	If there is an error communicating with the API.

Examples:

>>> from fastfuels_sdk import SurfaceGrid
>>> grid = SurfaceGrid.from_domain_id("abc123")

Basic usage with default parameters:

>>> completed = grid.wait_until_completed()
>>> print(completed.status)
'completed'

With progress updates:

>>> completed = grid.wait_until_completed(
...     step=10,
...     timeout=1200,
...     verbose=True
... )
Surface grid has status `pending` (10.00s)
Surface grid has status `running` (20.00s)
Surface grid has status `completed` (30.00s)

Without in-place updates:

>>> completed = grid.wait_until_completed(in_place=False)
>>> completed is grid
False

Notes

• Processing time varies based on domain size and grid configuration
• The method polls by calling get() at each interval, which counts against API rate limits
• Consider longer step intervals for large domains or when making many API calls
• For very large domains, you may need to increase the timeout beyond the default 10 minutes

get_attributes

get_attributes() -> GridAttributeMetadataResponse

Get metadata about grid attributes.

Returns metadata about the structure of the surface grid and its attributes, including dimensions, chunking, and attribute details.

Returns:

Type	Description
GridAttributeMetadataResponse	Metadata about grid structure and attributes including: - shape: Dimensions of the grid data - dimensions: Names of each dimension - chunks: Number of chunks in each dimension - chunk_shape: Shape of each chunk - attributes: Detailed information about each attribute

Examples:

>>> from fastfuels_sdk import SurfaceGrid
>>> grid = SurfaceGrid.from_domain_id("abc123")
>>> metadata = grid.get_attributes()
>>> print(metadata.shape)
[100, 100, 50]

create_export

create_export(export_format: str) -> Export

Create an export of the surface grid data.

Parameters:

Name	Type	Description	Default
export_format	str	Format for the export. Must be one of: - "zarr": Compressed array format - "geotiff": GeoTIFF format	required

Returns:

Type	Description
Export	An Export object for managing the export process

Examples:

>>> from fastfuels_sdk import SurfaceGrid
>>> grid = SurfaceGrid.from_domain_id("abc123")
>>> export = grid.create_export("zarr")
>>> export.wait_until_completed()
>>> export.to_file("grid_data.zarr")

get_export

get_export(export_format: str) -> Export

Get the status of an existing export.

Parameters:

Name	Type	Description	Default
export_format	str	Format of the export to check. Must be one of: - "zarr": Compressed array format - "geotiff": GeoTIFF format	required

Returns:

Type	Description
Export	An Export object containing current status

Examples:

>>> from fastfuels_sdk import SurfaceGrid
>>> grid = SurfaceGrid.from_domain_id("abc123")
>>> export = grid.create_export("zarr")
>>> export.wait_until_completed()
>>> export.to_file("grid_data.zarr")

delete

delete() -> None

Delete this surface grid.

Permanently removes surface grid data from the domain. This also cancels any ongoing processing jobs.

Returns:

Type	Description
None

Examples:

>>> from fastfuels_sdk import SurfaceGrid
>>> grid = SurfaceGrid.from_domain_id("abc123")
>>> # Remove grid when no longer needed
>>> grid.delete()
>>> # Subsequent operations will raise NotFoundException
>>> grid.get()  # raises NotFoundException

TopographyGrid

Bases: TopographyGrid

Topography grid data within a domain's spatial boundaries.

from_domain_id classmethod

from_domain_id(domain_id: str) -> 'TopographyGrid'

Retrieve an existing topography grid for a domain.

Parameters:

Name	Type	Description	Default
domain_id	str	ID of the domain to retrieve topography grid for	required

Returns:

Type	Description
TopographyGrid	The topography grid object

Examples:

>>> grid = TopographyGrid.from_domain_id("abc123")
>>> print(grid.status)
'completed'

get

get(in_place: bool = False) -> 'TopographyGrid'

Get the latest topography grid data.

Parameters:

Name	Type	Description	Default
in_place	bool	If True, updates this TopographyGrid instance with new data. If False (default), returns a new TopographyGrid instance.	False

Returns:

Type	Description
TopographyGrid	The updated topography grid object

Examples:

>>> from fastfuels_sdk import TopographyGrid
>>> grid = TopographyGrid.from_domain_id("abc123")

>>> # Get fresh data in a new instance
>>> updated_grid = grid.get()

>>> # Or update the existing instance
>>> grid.get(in_place=True)

wait_until_completed

wait_until_completed(step: float = 5, timeout: float = 600, in_place: bool = True, verbose: bool = False) -> 'TopographyGrid'

Wait for the topography grid processing to complete.

Topography grids are processed asynchronously and may take between several seconds to minutes to complete depending on domain size and complexity. This method polls the API at regular intervals until the grid reaches a 'completed' status or the timeout is reached.

Parameters:

Name	Type	Description	Default
step	float	Number of seconds to wait between status checks. Default is 5 seconds. Use larger values to reduce API calls, smaller values for more frequent updates.	5
timeout	float	Maximum number of seconds to wait for completion. Default is 600 seconds (10 minutes). If the timeout is reached before completion, raises a TimeoutError.	600
in_place	bool	If True (default), updates the current TopographyGrid instance with new data at each check. If False, leaves the current instance unchanged and returns a new instance when complete.	True
verbose	bool	If True, prints status updates at each check. Default is False.	False

Returns:

Type	Description
TopographyGrid	Either the current TopographyGrid instance (if in_place=True) or a new TopographyGrid instance (if in_place=False) with the completed grid data.

Raises:

Type	Description
TimeoutError	If the topography grid does not complete within the specified timeout.
NotFoundException	If the topography grid or domain no longer exists.
ApiException	If there is an error communicating with the API.

Examples:

>>> from fastfuels_sdk import TopographyGrid
>>> grid = TopographyGrid.from_domain_id("abc123")

Basic usage with default parameters:

>>> completed = grid.wait_until_completed()
>>> print(completed.status)
'completed'

With progress updates:

>>> completed = grid.wait_until_completed(
...     step=10,
...     timeout=1200,
...     verbose=True
... )
Topography grid has status `pending` (10.00s)
Topography grid has status `running` (20.00s)
Topography grid has status `completed` (30.00s)

Without in-place updates:

>>> completed = grid.wait_until_completed(in_place=False)
>>> completed is grid
False

Notes

• Processing time varies based on domain size and grid configuration
• The method polls by calling get() at each interval, which counts against API rate limits
• Consider longer step intervals for large domains or when making many API calls
• For very large domains, you may need to increase the timeout beyond the default 10 minutes

get_attributes

get_attributes() -> GridAttributeMetadataResponse

Get metadata about grid attributes.

Returns metadata about the structure of the topography grid and its attributes, including dimensions, chunking, and attribute details.

Returns:

Type	Description
GridAttributeMetadataResponse	Metadata about grid structure and attributes including: - shape: Dimensions of the grid data - dimensions: Names of each dimension - chunks: Number of chunks in each dimension - chunk_shape: Shape of each chunk - attributes: Detailed information about each attribute

Examples:

>>> from fastfuels_sdk import TopographyGrid
>>> grid = TopographyGrid.from_domain_id("abc123")
>>> metadata = grid.get_attributes()
>>> print(metadata.shape)
[100, 100, 50]

create_export

create_export(export_format: str) -> Export

Create an export of the topography grid data.

Parameters:

Name	Type	Description	Default
export_format	str	Format for the export. Must be one of: - "zarr": Compressed array format - "geotiff": GeoTIFF format	required

Returns:

Type	Description
Export	An Export object for managing the export process

Examples:

>>> from fastfuels_sdk import TopographyGrid
>>> grid = TopographyGrid.from_domain_id("abc123")
>>> export = grid.create_export("zarr")
>>> export.wait_until_completed()
>>> export.to_file("grid_data.zarr")

get_export

get_export(export_format: str) -> Export

Get the status of an existing export.

Parameters:

Name	Type	Description	Default
export_format	str	Format of the export to check. Must be one of: - "zarr": Compressed array format - "geotiff": GeoTIFF format	required

Returns:

Type	Description
Export	An Export object containing current status

Examples:

>>> from fastfuels_sdk import TopographyGrid
>>> grid = TopographyGrid.from_domain_id("abc123")
>>> export = grid.create_export("zarr")
>>> export.wait_until_completed()
>>> export.to_file("grid_data.zarr")

delete

delete() -> None

Delete this topography grid.

Permanently removes topography grid data from the domain. This also cancels any ongoing processing jobs.

Returns:

Type	Description
None

Examples:

>>> from fastfuels_sdk import TopographyGrid
>>> grid = TopographyGrid.from_domain_id("abc123")
>>> # Remove grid when no longer needed
>>> grid.delete()
>>> # Subsequent operations will raise NotFoundException
>>> grid.get()  # raises NotFoundException

TreeGridBuilder

Builder for creating tree grids with complex attribute configurations.

with_bulk_density_from_tree_inventory

with_bulk_density_from_tree_inventory() -> 'TreeGridBuilder'

Add bulk density attribute from tree inventory data.

Examples:

>>> builder = TreeGridBuilder("abc123")
>>> builder.with_bulk_density_from_tree_inventory()

with_uniform_bulk_density

with_uniform_bulk_density(value: float) -> 'TreeGridBuilder'

Set uniform bulk density value.

Parameters:

Name	Type	Description	Default
value	float	Bulk density value in kg/m³	required

Examples:

>>> builder = TreeGridBuilder("abc123")
>>> builder.with_uniform_bulk_density(0.5)

with_spcd_from_tree_inventory

with_spcd_from_tree_inventory() -> 'TreeGridBuilder'

Add species code (SPCD) attribute from tree inventory data.

Examples:

>>> builder = TreeGridBuilder("abc123")
>>> builder.with_spcd_from_tree_inventory()

with_uniform_fuel_moisture

with_uniform_fuel_moisture(value: float) -> 'TreeGridBuilder'

Set uniform fuel moisture value.

Parameters:

Name	Type	Description	Default
value	float	Fuel moisture value (%)	required

Examples:

>>> builder = TreeGridBuilder("abc123")
>>> builder.with_uniform_fuel_moisture(15.0)  # 15%

build

build() -> 'TreeGrid'

Create the tree grid with configured attributes.

Examples:

>>> tree_grid = (TreeGridBuilder("abc123")
...     .with_bulk_density_from_tree_inventory()
...     .with_spcd_from_tree_inventory()
...     .with_uniform_fuel_moisture(15.0)
...     .build())

clear

clear() -> 'TreeGridBuilder'

Clear all configured attributes.

to_dict

to_dict() -> dict

Return the dictionary representation of the builder configuration.

SurfaceGridBuilder

Builder for creating surface grids with complex attribute configurations.

with_uniform_fuel_load

with_uniform_fuel_load(value: float, feature_masks: list[str] = None) -> 'SurfaceGridBuilder'

Set uniform fuel load value.

Parameters:

Name	Type	Description	Default
value	float	Fuel load value in kg/m²	required
feature_masks	list[str]	List of feature masks to apply to the surface grid attribute. Can be "road" or "water". Note that including these masks requires a feature grid with the appropriate attributes to have a "completed" status.	None

Examples:

>>> builder = SurfaceGridBuilder("abc123")
>>> builder.with_uniform_fuel_load(value=0.5, feature_masks=["road", "water"])

with_uniform_fuel_load_by_size_class

with_uniform_fuel_load_by_size_class(one_hour: float = None, ten_hour: float = None, hundred_hour: float = None, live_herbaceous: float = None, live_woody: float = None, feature_masks: list[str] = None) -> 'SurfaceGridBuilder'

Set uniform fuel load values by size class.

Parameters:

Name	Type	Description	Default
one_hour	float	1-hour fuel load value in kg/m².	None
ten_hour	float	10-hour fuel load value in kg/m².	None
hundred_hour	float	100-hour fuel load value in kg/m².	None
live_herbaceous	float	Live herbaceous fuel load value in kg/m².	None
live_woody	float	Live woody fuel load value in kg/m².	None
feature_masks	list[str]	List of feature masks to apply to the surface grid attribute. Can be "road" or "water". Note that including these masks requires a feature grid with the appropriate attributes to have a "completed" status.	None

Examples:

>>> builder = SurfaceGridBuilder("abc123")
>>> builder.with_uniform_fuel_load_by_size_class(
...     one_hour=0.5,
...     ten_hour=1.0,
...     hundred_hour=2.0,
...     feature_masks=["road", "water"]
... )

Notes

Only size classes with provided values will be included in the configuration.

with_fuel_load_from_landfire

with_fuel_load_from_landfire(product: str, version: str = '2022', interpolation_method: str = 'nearest', curing_live_herbaceous: float = 0.0, curing_live_woody: float = 0.0, groups: List[str] = None, feature_masks: list[str] = None, remove_non_burnable: list[str] = None) -> 'SurfaceGridBuilder'

Configure fuel load from LANDFIRE source.

Parameters:

Name	Type	Description	Default
product	str	LANDFIRE product name ("FBFM40" or "FBFM13")	required
version	str	LANDFIRE version, default "2022"	'2022'
interpolation_method	str	Method for interpolation, default "nearest"	'nearest'
curing_live_herbaceous	float	Proportion of live herbaceous fuel that is cured, defaults to 0.	0.0
curing_live_woody	float	Proportion of live woody fuel that is cured, defaults to 0.	0.0
groups	list[str]	List of fuel load groups to include. Can be: "oneHour", "tenHour", "hundredHour", "liveHerbaceous", "liveWoody"	None
feature_masks	list[str]	List of feature masks to apply to the surface grid attribute. Can be "road" or "water". Note that including these masks requires a feature grid with the appropriate attributes to have a "completed" status.	None
remove_non_burnable	list[str]	List of non-burnable fuel models to remove. This option is often used in conjunction with feature_masks to improve the resolution of landscape features. Can be: "NB1", "NB2", "NB3", "NB8", "NB9"	None

Examples:

>>> builder = SurfaceGridBuilder("abc123")
>>> builder.with_fuel_load_from_landfire(
...     product="FBFM40",
...     version="2022",
...     interpolation_method="nearest",
...     curing_live_herbaceous=0.25,
...     curing_live_woody=0.1,
...     groups=["oneHour", "tenHour", "hundredHour"],
...     feature_masks=["road", "water"],
...     remove_non_burnable=["NB1", "NB2"]
... )

with_uniform_fuel_depth

with_uniform_fuel_depth(value: float, feature_masks: list[str] = None) -> 'SurfaceGridBuilder'

Set uniform fuel depth value.

Parameters:

Name	Type	Description	Default
value	float	Fuel depth in meters	required
feature_masks	list[str]	List of feature masks to apply to the surface grid attribute. Can be "road" or "water". Note that including these masks requires a feature grid with the appropriate attributes to have a "completed" status.	None

Examples:

>>> builder = SurfaceGridBuilder("abc123")
>>> builder.with_uniform_fuel_depth(value=0.3, feature_masks=["road", "water"])

with_fuel_depth_from_landfire

with_fuel_depth_from_landfire(product: str, version: str = '2022', interpolation_method: str = 'nearest', feature_masks: list[str] = None, remove_non_burnable: list[str] = None) -> 'SurfaceGridBuilder'

Configure fuel depth from LANDFIRE source.

Parameters:

Name	Type	Description	Default
product	str	LANDFIRE product name ("FBFM40" or "FBFM13")	required
version	str	LANDFIRE version, default "2022"	'2022'
interpolation_method	str	Method for interpolation, default "nearest"	'nearest'
feature_masks	list[str]	List of feature masks to apply to the surface grid attribute. Can be "road" or "water". Note that including these masks requires a feature grid with the appropriate attributes to have a "completed" status.	None
remove_non_burnable	list[str]	List of non-burnable fuel models to remove. This option is often used in conjunction with feature_masks to improve the resolution of landscape features. Can be: "NB1", "NB2", "NB3", "NB8", "NB9"	None

Examples:

>>> builder = SurfaceGridBuilder("abc123")
>>> builder.with_fuel_depth_from_landfire(
...     product="FBFM40",
...     version="2022",
...     interpolation_method="nearest",
...     feature_masks=["road", "water"],
...     remove_non_burnable=["NB1", "NB2"]
... )

with_uniform_fuel_moisture

with_uniform_fuel_moisture(value: float, feature_masks: list[str] = None) -> 'SurfaceGridBuilder'

Set uniform fuel moisture value.

Parameters:

Name	Type	Description	Default
value	float	Fuel moisture value (%).	required
feature_masks	list[str]	List of feature masks to apply to the surface grid attribute. Can be "road" or "water". Note that including these masks requires a feature grid with the appropriate attributes to have a "completed" status.	None

Examples:

>>> builder = SurfaceGridBuilder("abc123")
>>> builder.with_uniform_fuel_moisture(
...     value=15.0,  # 15%
...     feature_masks=["road", "water"]
... )

with_uniform_fuel_moisture_by_size_class

with_uniform_fuel_moisture_by_size_class(one_hour: float = None, ten_hour: float = None, hundred_hour: float = None, live_herbaceous: float = None, live_woody: float = None, feature_masks: list[str] = None) -> 'SurfaceGridBuilder'

Set uniform fuel moisture values by size class.

Parameters:

Name	Type	Description	Default
one_hour	float	1-hour fuel moisture content (%).	None
ten_hour	float	10-hour fuel moisture content (%).	None
hundred_hour	float	100-hour fuel moisture content (%).	None
live_herbaceous	float	Live herbaceous fuel moisture content (%).	None
live_woody	float	Live woody fuel moisture content (%).	None
feature_masks	list[str]	List of feature masks to apply to the surface grid attribute. Can be "road" or "water". Note that including these masks requires a feature grid with the appropriate attributes to have a "completed" status.	None

Examples:

>>> builder = SurfaceGridBuilder("abc123")
>>> builder.with_uniform_fuel_moisture_by_size_class(
...     one_hour=10.0,
...     ten_hour=15.0,
...     hundred_hour=20.0,
...     live_herbaceous=75.0,
...     live_woody=90.0,
...     feature_masks=["road", "water"]
... )

with_uniform_fbfm

with_uniform_fbfm(value: str, feature_masks: list[str] = None) -> 'SurfaceGridBuilder'

Set uniform Fire Behavior Fuel Model.

Parameters:

Name	Type	Description	Default
value	str	FBFM value (e.g. "9", "GR2")	required
feature_masks	list[str]	List of feature masks to apply to the surface grid attribute. Can be "road" or "water". Note that including these masks requires a feature grid with the appropriate attributes to have a "completed" status.	None

Examples:

>>> builder = SurfaceGridBuilder("abc123")
>>> builder.with_uniform_fbfm("GR2")

with_fbfm_from_landfire

with_fbfm_from_landfire(product: str, version: str = '2022', interpolation_method: str = 'nearest', feature_masks: list[str] = None, remove_non_burnable: list[str] = None) -> 'SurfaceGridBuilder'

Configure FBFM from LANDFIRE source.

Parameters:

Name	Type	Description	Default
product	str	LANDFIRE product to use ("FBFM40" or "FBFM13")	required
version	str	LANDFIRE version, default "2022"	'2022'
interpolation_method	str	Method for interpolation, default "nearest"	'nearest'
feature_masks	list[str]	List of feature masks to apply to the surface grid attribute. Can be "road" or "water". Note that including these masks requires a feature grid with the appropriate attributes to have a "completed" status.	None
remove_non_burnable	list[str]	List of non-burnable fuel models to remove. This option is often used in conjunction with feature_masks to improve the resolution of landscape features. Can be: "NB1", "NB2", "NB3", "NB8", "NB9"	None

Examples:

>>> builder = SurfaceGridBuilder("abc123")
>>> builder.with_fbfm_from_landfire(
...     product="FBFM40",
...     version="2022",
...     interpolation_method="nearest",
...     feature_masks=["road", "water"],
...     remove_non_burnable=["NB1", "NB2"]
... )

with_uniform_savr

with_uniform_savr(value: float, feature_masks: list[str] = None) -> 'SurfaceGridBuilder'

Set uniform Surface Area to Volume Ratio (SAVR).

Parameters:

Name	Type	Description	Default
value	float	SAVR value in m²/m³	required
feature_masks	list[str]	List of feature masks to apply to the surface grid attribute. Can be "road" or "water". Note that including these masks requires a feature grid with the appropriate attributes to have a "completed" status.	None

Examples:

>>> builder = SurfaceGridBuilder("abc123")
>>> builder.with_uniform_savr(
...     value=9000, # m²/m³
...     feature_masks=["road", "water"]
... )

with_savr_from_landfire

with_savr_from_landfire(product: str, version: str = '2022', interpolation_method: str = 'nearest', groups: List[str] = None, feature_masks: list[str] = None, remove_non_burnable: list[str] = None) -> 'SurfaceGridBuilder'

Configure SAVR from LANDFIRE source.

Parameters:

Name	Type	Description	Default
product	str	LANDFIRE product to use ("FBFM40" or "FBFM13")	required
version	str	LANDFIRE version, default "2022"	'2022'
interpolation_method	str	Method for interpolation, default "nearest"	'nearest'
groups	list[str]	List of SAVR groups to include. Can be: "oneHour", "tenHour", "hundredHour", "liveHerbaceous", "liveWoody"	None
feature_masks	list[str]	List of feature masks to apply to the surface grid attribute. Can be "road" or "water". Note that including these masks requires a feature grid with the appropriate attributes to have a "completed" status.	None
remove_non_burnable	list[str]	List of non-burnable fuel models to remove. This option is often used in conjunction with feature_masks to improve the resolution of landscape features. Can be: "NB1", "NB2", "NB3", "NB8", "NB9"	None

Examples:

>>> builder = SurfaceGridBuilder("abc123")
>>> builder.with_savr_from_landfire(
...     product="FBFM40",
...     version="2022",
...     interpolation_method="nearest",
...     groups=["oneHour", "tenHour", "hundredHour"],
...     feature_masks=["road", "water"],
...     remove_non_burnable=["NB1", "NB2"]
... )

with_modification

with_modification(actions: dict | list[dict] | SurfaceGridModificationAction | list[SurfaceGridModificationAction], conditions: dict | list[dict] | SurfaceGridModificationCondition | list[SurfaceGridModificationCondition] = None) -> 'SurfaceGridBuilder'

Add a modification to the surface grid.

Parameters:

Name	Type	Description	Default
actions	dict or list[dict] or SurfaceGridModificationAction or list[SurfaceGridModificationAction]	Action to apply to the surface grid. Can be a single action or a list of actions.	required
conditions	dict or list[dict] or SurfaceGridModificationCondition or list[SurfaceGridModificationCondition]	Condition(s) to apply the action. Can be a single condition or a list of conditions.	None

Examples:

>>> builder = SurfaceGridBuilder("abc123")
>>> builder.with_modification(
...     actions={"attribute": "FBFM", "modifier": "replace", "value": "GR2"},
...     conditions={"attribute": "FBFM", "operator": "eq", "value": "GR1"}
... )  # Replace all FBFM values that are GR1 with GR2

build

build() -> 'SurfaceGrid'

Create the surface grid with configured attributes.

Examples:

>>> surface_grid = (SurfaceGridBuilder("abc123")
...     .with_uniform_fuel_load(0.5)
...     .with_uniform_fuel_moisture(15.0)
...     .with_fbfm_from_landfire("FBFM40")
...     .build())

clear

clear() -> 'SurfaceGridBuilder'

Clear all configured attributes.

TopographyGridBuilder

Builder for creating topography grids with complex attribute configurations.

with_elevation_from_3dep

with_elevation_from_3dep(interpolation_method: str = 'cubic') -> 'TopographyGridBuilder'

Add elevation attribute from 3DEP data.

with_elevation_from_landfire

with_elevation_from_landfire(interpolation_method: str = 'cubic') -> 'TopographyGridBuilder'

Add elevation attribute from LANDFIRE data.

with_elevation_from_uniform_value

with_elevation_from_uniform_value(value: float) -> 'TopographyGridBuilder'

Add elevation attribute with uniform value.

with_aspect_from_3dep

with_aspect_from_3dep() -> 'TopographyGridBuilder'

Add aspect attribute from 3DEP data.

with_aspect_from_landfire

with_aspect_from_landfire() -> 'TopographyGridBuilder'

Add aspect attribute from LANDFIRE data.

with_slope_from_3dep

with_slope_from_3dep(interpolation_method: str = 'cubic') -> 'TopographyGridBuilder'

Add slope attribute from 3DEP data.

with_slope_from_landfire

with_slope_from_landfire(interpolation_method: str = 'cubic') -> 'TopographyGridBuilder'

Add slope attribute from LANDFIRE data.

build

build() -> 'TopographyGrid'

Create the surface grid with configured attributes.

Examples:

>>> topography_grid = (TopographyGridBuilder(domain_id="abc123")
...     .with_elevation_from_3dep()
...     .with_slope_from_3dep()
...     .with_aspect_from_landfire()
...     .build())

clear

clear() -> 'TopographyGridBuilder'

Clear all configured attributes.

fastfuels_sdk.exports

exports.py

Export

Bases: Export

Class for handling exports of various resources from the FastFuels API. Inherits from the base ExportModel and adds functionality for fetching, waiting for completion, and downloading exports.

Attributes:

Name	Type	Description
domain_id	str	The ID of the domain associated with the export
resource	str	The type of resource being exported (e.g. "inventories")
sub_resource	str	The specific sub-resource being exported (e.g. "tree")
format	str	The format of the export (e.g. "csv", "parquet", "geojson")
status	str	Current status of the export ("pending", "running", "completed")
signed_url	(str, optional)	URL for downloading the completed export
_api_get_method	Callable	The API method to use for getting the export status

__init__

__init__(**data: Any)

Initialize the Export object and set up the appropriate API method based on the resource and sub_resource.

Parameters:

Name	Type	Description	Default
**data	Any	Keyword arguments that match the ExportModel fields	{}

Raises:

Type	Description
NotImplementedError	If the resource and sub_resource combination is not supported

get

get(in_place: bool = False) -> Export

Fetches the current state of the export from the API.

Parameters:

Name	Type	Description	Default
in_place	bool	If True, updates the current object with fetched data. If False, returns a new Export object. Default is False.	False

Returns:

Type	Description
Export	Either the current object updated with fresh data (in_place=True) or a new Export object with the fetched data (in_place=False)

wait_until_completed

wait_until_completed(step: float = 5, timeout: float = 600, in_place: bool = True, verbose: bool = False) -> Export

Waits for the export to complete, polling at regular intervals.

Parameters:

Name	Type	Description	Default
step	float	Time in seconds between status checks. Default is 5.	5
timeout	float	Maximum time in seconds to wait for completion. Default is 600.	600
in_place	bool	If True, updates the current object with the completed export data. If False, returns a new Export object. Default is True.	True
verbose	bool	If True, prints status updates during the wait. Default is False.	False

Returns:

Type	Description
Export	The completed export object

Raises:

Type	Description
TimeoutError	If the export does not complete within the specified timeout period.

to_file

to_file(path: Path | str) -> None

Downloads the export to a local file once it's completed.

Parameters:

Name	Type	Description	Default
path	Path or str	The path where the export should be saved. If a directory is provided, the file will be saved as "{resource}_{sub_resource}.{format}" in that directory.	required

Raises:

Type	Description
ValueError	If the export is not yet completed or if the signed URL is missing

fastfuels_sdk.convenience

fastfuels_sdk/convenience.py

export_roi_to_quicfire

export_roi_to_quicfire(roi: GeoDataFrame, export_path: Path | str, verbose: bool = False, **kwargs) -> Export

Convenience function to export a region of interest (ROI) to QuicFire.