CCWFGM_Scenario Class Reference

Primary simulation scenario object. More...

#include <CWFGM_Scenario.h>

Collaboration diagram for CCWFGM_Scenario:

Public Member Functions
STDMETHOD()	Clone (ICWFGM_Scenario **scenario)
STDMETHOD()	GetGridEngine (LONGLONG *layerThread, ICWFGM_GridEngine **pVal)
STDMETHOD()	PutGridEngine (LONGLONG layerThread, ICWFGM_GridEngine *newVal)
STDMETHOD()	GetIgnitionCount (ULONG *count)
STDMETHOD()	AddIgnition (ICWFGM_Ignition *fire)
STDMETHOD()	RemoveIgnition (ICWFGM_Ignition *fire)
STDMETHOD()	IndexOfIgnition (ICWFGM_Ignition *fire, ULONG *index)
STDMETHOD()	IgnitionAtIndex (ULONG index, ICWFGM_Ignition **fire)
STDMETHOD()	GetVectorEngineCount (ULONG *count)
STDMETHOD()	AddVectorEngine (ICWFGM_VectorEngine *vectorEngine)
STDMETHOD()	RemoveVectorEngine (ICWFGM_VectorEngine *vectorEngine)
STDMETHOD()	IndexOfVectorEngine (ICWFGM_VectorEngine *vectorEngine, ULONG *index)
STDMETHOD()	VectorEngineAtIndex (ULONG index, ICWFGM_VectorEngine **vectorEngine)
STDMETHOD()	Simulation_State ()
STDMETHOD()	Simulation_Reset ()
STDMETHOD()	Simulation_Step ()
STDMETHOD()	Simulation_Clear ()
STDMETHOD()	GetAttribute (USHORT option, VARIANT *value)
STDMETHOD()	SetAttribute (USHORT option, VARIANT value)
STDMETHOD()	get_UserData (VARIANT *pVal)
STDMETHOD()	put_UserData (VARIANT newVal)
STDMETHOD()	GetBurnedBox (ULONGLONG time, double *left, double *right, double *bottom, double *top)
STDMETHOD()	IsXYBurned (double X, double Y, ULONGLONG time, short *burned)
STDMETHOD()	Simulation_StepBack ()
STDMETHOD()	GetDefaultBurnCondition (VARIANT_BOOL *bEffective, USHORT *StartHour, USHORT *EndHour, double *MaxWS, double *MinRH, double *MinFWI)
STDMETHOD()	GetBurnConditionDays (USHORT *days)
STDMETHOD()	GetDayBurnCondition (SHORT day, VARIANT_BOOL *bEffective, USHORT *StartHour, USHORT *EndHour, double *MaxWS, double *MinRH, double *MinFWI)
STDMETHOD()	AdjustBurnCondition ()
STDMETHOD()	SetDefaultBurnCondition (VARIANT_BOOL bEffective, USHORT StartHour, USHORT EndHour, double MaxWS, double MinRH, double MinFWI)
STDMETHOD()	SetDayBurnCondition (SHORT day, VARIANT_BOOL bEffective, USHORT StartHour, USHORT EndHour, double MaxWS, double MinRH, double MinFWI)
STDMETHOD()	GetNumberSteps (ULONG *steps)
STDMETHOD()	GetStepsArray (ULONG *size, SAFEARRAY **times)
STDMETHOD()	GetNumberFires (ULONGLONG *time, ULONG *count)
STDMETHOD()	IgnitionAtFireIndex (ULONG index, ULONGLONG *time, ICWFGM_Ignition **fire)
STDMETHOD()	GetVectorSize (ULONG fire, ULONGLONG *time, ULONG *size)
STDMETHOD()	GetVectorArray (ULONG fire, ULONGLONG *time, ULONG *size, SAFEARRAY **xy_pairs)
STDMETHOD()	GetStatsArray (ULONG fire, ULONGLONG *time, USHORT stat, ULONG *size, SAFEARRAY **stats)
STDMETHOD()	GetStats (ULONG fire, ULONGLONG *time, USHORT stat, VARIANT *stats)
STDMETHOD()	GetXYStats (double x, double y, ULONGLONG *time, USHORT stat, USHORT interp_method, VARIANT *stats)
STDMETHOD()	GetStatsPercentage (ULONG fire, ULONGLONG *time, USHORT stat, double greater_equal, double less_than, double *stats)
STDMETHOD()	ExportFires (ICWFGM_Ignition *set, ULONGLONG *start_time, ULONGLONG *end_time, USHORT stat, const BSTR driver_name, const BSTR projection, const BSTR file_path, SAFEARRAY *rules)
Public Member Functions inherited from ICWFGM_Scenario
HRESULT	Clone ([out, retval]ICWFGM_Scenario **scenario)
HRESULT	GetGridEngine ([out] __int64 *layerThread, [out] ICWFGM_GridEngine **pVal)
HRESULT	PutGridEngine ([in] __int64 layerThread, [in] ICWFGM_GridEngine *newVal)
HRESULT	GetAttribute ([in]unsigned short option, [out, retval]VARIANT *value)
HRESULT	SetAttribute ([in]unsigned short option, [in]VARIANT value)
HRESULT	GetIgnitionCount ([out, retval]unsigned long *count)
HRESULT	AddIgnition ([in]ICWFGM_Ignition *fire)
HRESULT	RemoveIgnition ([in]ICWFGM_Ignition *fire)
HRESULT	IgnitionAtIndex ([in]unsigned long index, [out, retval]ICWFGM_Ignition **fire)
HRESULT	IndexOfIgnition ([in]ICWFGM_Ignition *fire, [out, retval]unsigned long *index)
HRESULT	GetVectorEngineCount ([out, retval]unsigned long *count)
HRESULT	AddVectorEngine ([in]ICWFGM_VectorEngine *vectorEngine)
HRESULT	RemoveVectorEngine ([in]ICWFGM_VectorEngine *vectorEngine)
HRESULT	VectorEngineAtIndex ([in]unsigned long index, [out, retval]ICWFGM_VectorEngine **vectorEngine)
HRESULT	IndexOfVectorEngine ([in]ICWFGM_VectorEngine *vectorEngine, [out, retval]unsigned long *index)
HRESULT	Simulation_State ()
HRESULT	Simulation_Reset ()
HRESULT	Simulation_Step ()
HRESULT	Simulation_StepBack ()
HRESULT	Simulation_Clear ()
HRESULT	SetDayBurnCondition ([in]short day, [in]VARIANT_BOOL bEffective,[in]unsigned short StartHour, [in]unsigned short EndHour, [in]double MaxWS, [in]double MinRH, [in]double MinFWI)
HRESULT	SetDefaultBurnCondition ([in]VARIANT_BOOL bEffective,[in]unsigned short StartHour, [in]unsigned short EndHour, [in]double MaxWS, [in]double MinRH, [in]double MinFWI)
HRESULT	AdjustBurnCondition ()
HRESULT	GetDayBurnCondition ([in]short day,[out]VARIANT_BOOL *bEffective,[out]unsigned short *StartHour,[out]unsigned short *EndHour,[out]double *MaxWS,[out]double *MinRH, [out]double *MinFWI)
HRESULT	GetBurnConditionDays ([out]unsigned short *days)
HRESULT	GetDefaultBurnCondition ([out]VARIANT_BOOL *bEffective,[out]unsigned short *StartHour,[out]unsigned short *EndHour,[out]double *MaxWS,[out]double *MinRH, [out]double *MinFWI)
HRESULT	IsXYBurned ([in]double X, [in]double Y, [in]unsigned __int64 time, [out, retval]short *burned)
HRESULT	GetBurnedBox ([in]unsigned __int64 time, [out]double *left, [out]double *right, [out]double *bottom, [out]double *top)
HRESULT	GetNumberSteps ([out, retval]unsigned long *steps)
HRESULT	GetStepsArray ([in, out]unsigned long *size, [in, out]SAFEARRAY(unsigned __int64)*times)
HRESULT	GetNumberFires ([in, out]unsigned __int64 *time, [out, retval]unsigned long *size)
HRESULT	IgnitionAtFireIndex ([in]unsigned long index, [in, out]unsigned __int64 *time, [out, retval]ICWFGM_Ignition **fire)
HRESULT	GetVectorSize ([in]unsigned long fire, [in, out]unsigned __int64 *time, [out, retval]unsigned long *size)
HRESULT	GetVectorArray ([in]unsigned long fire, [in, out]unsigned __int64 *time, [in, out]unsigned long *size, [in, out]SAFEARRAY(double)*xy_pairs)
HRESULT	GetStatsArray ([in]unsigned long fire, [in, out]unsigned __int64 *time, [in]unsigned short stat, [in, out]unsigned long *size, [in, out]SAFEARRAY(double)*stats)
HRESULT	GetStats ([in]unsigned long fire, [in, out]unsigned __int64 *time, [in]unsigned short stat, [out, retval]VARIANT *stats)
HRESULT	GetXYStats ([in]double X, [in]double Y, [in, out]unsigned __int64 *time, [in]unsigned short stat, [in]unsigned short interp_method, [out, retval]VARIANT *stats)
HRESULT	GetStatsPercentage ([in]ULONG fire, [in, out]unsigned __int64 *time, [in]unsigned short stat, [in]double greater_equal, [in]double less_than, [out, retval]double *stats)
HRESULT	ExportFires ([in] ICWFGM_Ignition *set, [in, out] unsigned __int64 *start_time, [in, out] unsigned __int64 *end_time, [in] unsigned short flags, [in] const BSTR driver_name, [in] const BSTR projection, [in] const BSTR file_path, [in] SAFEARRAY(SExportRule) rules)

Additional Inherited Members
Properties inherited from ICWFGM_Scenario
VARIANT	UserData [get, set]

Detailed Description

Primary simulation scenario object.

The simulation engine implements and exposes a large scenario COM interface for CWFGM and other client applications to use. The purposes of this object are as follows:

• to provide mechanisms to model a fire (statistical information can be retrieved as well);
• to provide the client appication (such as Prometheus) with a means to examine and set various parameters that affect the fire growth, such as acceleration on or off, etc.; and
• to provide the client application with mechanisms to manipulate the objects that participate in the fire simulation, such as ignition points.

This object also implements the standard COM IPersistStream, IPersistStreamInit, and IPersistStorage interfaces, for use for loading and saving. Serialization methods save scenario settings such as start time, duration, etc., but do not save any other associated objects, such as the grid engine, vector engines, or fire objects attached to it. The client application is responsible for maintaining these settings. This rule is imposed since the client object is responsible for maintaining collections of ignition objects, and objects exporting the ICWFGM_GridEngine interface.

Presently, this interface defines synchronous access to simplify the simulation engine and the client application. The client application makes a request Step() and will wait until the simulation engine is finished completing the request. This model will provide sufficient control over the engine for this application.

Member Function Documentation

STDMETHODIMP CCWFGM_Scenario::AddIgnition

(

ICWFGM_Ignition *

fire

)

Adds an ignition to this scenario object.

Parameters

fire	An ignition object

See Also

ICWFGM_Scenario::AddIgnition

Return values

S_OK	Successful
E_OUTOFMEMORY	Insufficient memory
ERROR_SCENARIO_BAD_STATE	If this function is run while the scenario is running
E_NOINTERFACE	The object trying to be added doesn't support the correct interfaces, or if the pointer to fire is invalid
ERROR_SCENARO_FIRE_ALREADY_ADDED	The fire being added is already associated with this scenario
E-POINTER	The address provided for fire is invalid.

STDMETHODIMP CCWFGM_Scenario::AddVectorEngine

(

ICWFGM_VectorEngine *

vectorEngine

)

Adds a vector engine object to this scenario object. The order of vector engine objects is unimportant (where the order of grid engine objects is).

Parameters

vectorEngine

A vector engine object.

See Also

ICWFGM_Scenario::AddVectorEngine

Return values

S_OK	Successful
E_OUTOFMEMORY	Insufficient memory
ERROR_SCENARIO_BAD_STATE	If this function is run while the scenarion is running.
E_POINTER	vectorEngine is invalid
E_NOINTERFACE	VectorEngine does not support the ICWFGM_VectorEngine interface
ERROR_SCENARIO_VECTORENGINE_ALREADY_ADDED	The vector engine object being added is already associated with this scenario.

STDMETHODIMP CCWFGM_Scenario::AdjustBurnCondition

(

)

This method will propagate the last defined day burned condition to all remaining days in the simulation.

This method is a candidate for removal and should not be used. This functionality is best implemented by the client application to avoid any possible assumptions on its behaviour and side-effects. This functionality is likely not needed with a more generalized approach to implementing burning conditions.

See Also

ICWFGM_Scenario::AdjustBurnCondition

Return values

S_OK	Successful
ERROR_SCENARIO_BAD_STATE	If the function is run while a scenario is running

STDMETHODIMP CCWFGM_Scenario::Clone

(

ICWFGM_Scenario **

scenario

)

Creates a new scenario object with all the same properties of the object being

called, returns a handle to the new object in 'scenario'. This operation does not link the cloned object to the fires attached to the object being called, nor does it record the GridEngine handle in the new object, it only duplicates the properties such as start time, end time, calculation intervals, etc.

Parameters

scenario

A scenario object

See Also

ICWFGM_Scenario::Clone

Return values

E_POINTER	The address provided for scenario return value is invalid
S_OK	Successful
E_OUTOFMEMORY	Insufficient memory
ERROR_SEVERITY_WARNING	Unspecified failure
E_NOINTERFACE	Internal serialization issue/error

STDMETHODIMP CCWFGM_Scenario::ExportFires	(	ICWFGM_Ignition *	set,
		ULONGLONG *	start_time,
		ULONGLONG *	end_time,
		USHORT	flags,
		const BSTR	driver_name,
		const BSTR	projection,
		const BSTR	file_path,
		SAFEARRAY *	rules
	)

Exports fires generated from a specific ignition at a specific simulated time, given options.

Parameters

set	Identifies a specific ignition. If NULL, then all fires at the time specified are exported
start_time	Start time for which to export at, specified GMT time since Midnight January 1, 1600. Only displayable time steps will be output.
end_time	End time for which to export at, specified GMT time since Midnight January 1, 1600. Only displayable time steps will be output.
flags	SCENARIO_EXPORT_SUBSET_EXTERIOR If TRUE, then only exterior perimeters are exported. If FALSE, then all exterior and interior perimeters are exported. SCENARIO_EXPORT_SUBSET_ACTIVE If TRUE, then active portions of the perimeters are exported as polylines. If FALSE, then all portions of the perimeters are exported (as polygons). SCENARIO_EXPORT_COMBINE_SET If TRUE, then multiple fire perimeters will be merged together. If FALSE, then boundaries among the fires will persist.
driver_name	Identifies file format. Refer to GDAL documentation for supported formats
projection	Projection file name
file_path	Vector data file name
rules	Array of SExportRule rules defining specific details of what to include in the exported file.

See Also

ICWFGM_Scenario::ExportFires

Return values

E_POINTER	The address provided for time, driver_name or file_path is invalid
S_OK	Successful
ERROR_NO_DATA|ERROR_SEVERITY_WARNING	Nothing has been initialized yet
ERROR_FIRE_INVALID_TIME	If the time is invalid
SUCCESS_FIRE_NOT_STARTED	Fire not y et started (stats is set to 0)
ERROR_SCENARIO_BAD_STATE	If the function is run without a running scenario
E_INVALIDARG	Invalid parameter
ERROR_GRID_UNINITIALIZED	Impossible to export
S_FALSE	Unspecified error
E_FAIL	Unspecidifed error

STDMETHODIMP CCWFGM_Scenario::get_UserData

(

VARIANT *

pVal

)

This property is unused by the scenario object, and is available for exclusive use by the client code.

It is a VARIANT field so that the client code may store pointer values for use in subclassing this object. This value is not loaded or saved during serialization operations, and it is the responsibility of the client code to manage any value or object stored here. Access to this property is not thread-safe.

Parameters

pVal	Value of UserData

See Also

ICWFGM_Scenario::UserData

Return values

E_POINTER	The address provided for pVal is invalid
S_OK	Successful

STDMETHODIMP CCWFGM_Scenario::GetAttribute	(	USHORT	option,
		VARIANT *	value
	)

Polymorphic.  Retrieves a value for a scenario setting that the client application can use to modify the operation of the scenario, or to determine the state of the simulation.  These values are defined in FireEngine_ext.h.
    \param option Option of interest(a list of possible options appears in "FireEngine_ext.h".  Supported / valid attribute/option index supported are:

• CWFGM_SCENARIO_OPTION_ACCEL Boolean. If TRUE, then acceleration is applied to various output statistics in the FBP standard. This value should only applicable to point ignitions. If FALSE, then the fire is assumed to be always at equilibrium.
• CWFGM_SCENARIO_OPTION_BUI Boolean. If TRUE, then the BUI build-up effect is applied to various statistics in the FBP standard.
• CWFGM_SCENARIO_OPTION_TOPOGRAPHY Boolean. If TRUE, then the slope component to calculating the WSV output statistic in the FBP standard is set to 0.0. If TRUE, then the wind speed is used as provided. This setting also affects the slope component in Dr. Richards' 3D equations.
• CWFGM_SCENARIO_OPTION_GREENUP Boolean. Specific FBP fuel types use different equations during green-up. This flag determines whether to use green-up equations or not.
• CWFGM_SCENARIO_OPTION_FMC_TERRAIN Boolean. If TRUE, then elevation is used to calculate FMC. Note that specific rules exist when default elevations have to be used.
• CWFGM_SCENARIO_OPTION_WIND Boolean. If FALSE, then the wind component to calculating the WSV statistic in the FBP standard is set to 0.0. If TRUE, then the wind speed is used as provided.
• CWFGM_SCENARIO_OPTION_EXTINGUISHMENT Boolean. Currently unused.
• CWFGM_SCENARIO_OPTION_USE_2DGROWTH Boolean. TRUE if using Dr. Richards' 2D equations. FALSE if using Dr. Richards' 3D equations.
• CWFGM_SCENARIO_OPTION_BOUNDARY_STOP Boolean. TRUE if the simulation stops when any simulated fire reaches the grid boundary. FALSE if the simulation should continue (in which case, any perimeter of the fire is stopped and clipped at the grid boundary).
• CWFGM_SCENARIO_OPTION_SPOTTING Boolean. Currently unused.
• CWFGM_SCENARIO_OPTION_BREACHING Boolean. Determines whether breaching of vector and gridded fire breaks is allowed.
• CWFGM_SCENARIO_OPTION_SINGLETHREADING Boolean. TRUE if multithreading within a simulation is disabled. FALSE if multithreading is enabled.
• CWFGM_SCENARIO_OPTION_NONFUELS_AS_VECTOR_BREAKS Boolean. When TRUE, square polygons are built around each non-fuel grid cell. This option affects performance, and how breaching, etc. operations perform around non-fuel grid cells.
• CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_TEMPORAL Boolean. When TRUE, temporal weather interpolation is turned on, for all of the WX and hourly/instantantaneous FWI calculations.
• CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_SPATIAL Boolean. When TRUE, spatial weather interpolation is turned on. This option applies to both WX and FWI values, and will work whether there is 1 or more weather stations assigned to the scenario. If FALSE, then there should only be one weather stream.
• CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_PRECIP Boolean. Conditional on CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_SPATIAL. When TRUE, precipitation is spatially interpolated using IDW. When FALSE, precipitation from the primary weather stream is used.
• CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_WIND Boolean. Conditional on CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_SPATIAL. When TRUE, wind is spatially interpolated (WS is defined using IDW, WD is chosen from the closest station); when FALSE, wind from the primary weather stream is used.
• CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_TEMP_RH Boolean. Conditional on CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_SPATIAL. When TRUE, temperature, dew point temperature, and RH are calculated spatially from adiabatic lapse rates; when FALSE, values from the primary weather stream are used.
• CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_CALCFWI Boolean. If FALSE, then the current FWI values are returned (possibly interpolated). If TRUE, then the current FWI values are calculated from the prior FWI values and the current weather values (likely spatially interpolated).
• CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_HISTORY Boolean. Conditional on CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_SPATIAL and CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_CALCFWI. If TRUE, then historical FWI values are calculated to try to attain equilibrium on FWI values.
• CWFGM_SCENARIO_OPTION_ACCURATE_FMC_LOCATION Boolean. When TRUE, the precise location of a simulated fire vertex is used when calculating FMC. When FALSE, the grid's lower left corner is used in calculating FMC.
• CWFGM_SCENARIO_OPTION_STARTING_POINTS 16-bit unsigned integer. Number of verticies used for a point ignition. Valid values are 6 to 64 inclusive.
• CWFGM_SCENARIO_OPTION_MULTITHREADING 32-bit unsigned integer. If multithreading is enabled, then this option determines how many threads to allow.
• CWFGM_SCENARIO_OPTION_PERIMETER_RESOLUTION 64-bit floating point. Maximum distance between any two vertices on a fire perimeter.
• CWFGM_SCENARIO_OPTION_SPATIAL_THRESHOLD 64-bit floating point. Maximum distance (in grid units) that a vertex is allows to travel while advancing a fire perimeter.
• CWFGM_SCENARIO_OPTION_SMOOTHING_WEIGHT 64-bit floating point. Smoothing factor which allows a vertex's neighbours' rates of spread to impact its calculated distance travelled.
• CWFGM_GRID_ATTRIBUTE_LATITUDE 64-bit floating point, radians.
• CWFGM_GRID_ATTRIBUTE_LONGITUDE 64-bit floating point, radians.
• CWFGM_SCENARIO_OPTION_SPECIFIED_FMC 64-bit floating point. User-override FMC value for the simulation. If >= 0, then the value is used, if < 0 then, this value is not used.
• CWFGM_SCENARIO_OPTION_DEFAULT_ELEVATION 64-bit floating point, metres. User specified elevation to use when there is no grid elevation available for at a requested grid location.
• CWFGM_SCENARIO_OPTION_IGNITION_SIZE 64-bit floating point. Diameter (in grid units) of the starting circle of an ignition point. Also used to determine the width of an ignition line.
• CWFGM_SCENARIO_OPTION_START_TIME 64-bit unsigned integer. GMT time provided as seconds since Midnight January 1, 1600
• CWFGM_SCENARIO_OPTION_END_TIME 64-bit unsigned integer. GMT time provided as seconds since Midnight January 1, 1600
• CWFGM_SCENARIO_OPTION_CURRENT_TIME 64-bit unsigned integer. GMT time provided as seconds since Midnight January 1, 1600
• CWFGM_SCENARIO_OPTION_TEMPORAL_THRESHOLD 64-bit signed integer. Units are in seconds. Maximum time allowed between any two adjacent simulation time steps.
• CWFGM_SCENARIO_OPTION_TEMPORAL_THRESHOLD_ACCEL 64-bit signed integer. Units are in seconds. Maximum time allowed between two adjacent simulation time steps when any ignition is in its acceleration phase (when ROSt is less than 90% of ROSeq).
• CWFGM_SCENARIO_OPTION_DISPLAY_INTERVAL 64-bit signed integer. Units are in seconds. Time interval for output fire perimeters, or 0 if every time step is to be outputted.
• CWFGM_GRID_ATTRIBUTE_TIMEZONE 64-bit signed integer. Units are in seconds, relative to GMT. For example, MST (Mountain Standard Time) would be -6 * 60 * 60 seconds. Valid values are from -12 hours to +12 hours.
• CWFGM_GRID_ATTRIBUTE_DAYLIGHT_SAVINGS 64-bit signed integer. Units are in seconds. Amount of correction to apply for daylight savings time.
• CWFGM_GRID_ATTRIBUTE_DST_START 64-bit unsigned integer. Units are in seconds. Julian date determining when daylight savings starts within the calendar year.
• CWFGM_GRID_ATTRIBUTE_DST_END 64-bit unsigned integer. Units are in seconds. Julian date determining when daylight savings ends within the calendar year.
• CWFGM_ATTRIBUTE_LOAD_WARNING BSTR. Any warnings generated by the COM object when deserializating.
• CWFGM_SCENARIO_OPTION_CACHE_GRID_POINTS Boolean. When TRUE, caches will be calculated to determine the closest points (for statistics purposes) to the center of each grid cell.

Parameters

value

Polymorphic. Value retrieved.

See Also

ICWFGM_Scenario::GetAttribute

Return values

E_POINTER	The address provided for value is invalid
S_OK	Successful
E_INVALIDARG	An unknown option was asked for
ERROR_SCENARIO_OPTION_INVALID	An invalid option has been selected

STDMETHODIMP CCWFGM_Scenario::GetBurnConditionDays

(

USHORT *

days

)

Retrieves the number of burn condition days.

Parameters

days	The number of days which satisfy the burn condition

See Also

ICWFGM_Scenario::GetBurnConditionDays

Return values

E_POINTER	The address provided for days is invalid
S_OK	Successful

STDMETHODIMP CCWFGM_Scenario::GetBurnedBox	(	ULONGLONG	time,
		double *	left,
		double *	right,
		double *	bottom,
		double *	top
	)

Retrieves the rectangular area encompassing all burned areas of all fires at a specific time during the simulation.

Parameters

time	A GMT time provided as seconds since Midnight January 1, 1600
left	Minimum X coordinate, inclusive
right	Maximum X coordinate, inclusive
bottom	Minimum Y coordinate, inclusive
top	Maximum Y coordinate, inclusive

See Also

ICWFGM_Scenario::GetBurnedBox

Return values

E_POINTER	The address provided for left, right, bottom, or top is invalid
S_OK	Successful
ERROR_SCENARIO_BAD_STATE	If the function is run while a scenario is running
ERROR_SEVERITY_WARNING	Unspecified error
SUCCESS_FIRE_NOT_STARTED	Either no fires or the request predates the start time of the simulation

STDMETHODIMP CCWFGM_Scenario::GetDayBurnCondition	(	SHORT	day,
		VARIANT_BOOL *	bEffective,
		USHORT *	StartHour,
		USHORT *	EndHour,
		double *	MaxWS,
		double *	MinRH,
		double *	MinFWI
	)

Retrieves the burning conditions for a specific day in the simulation.  If the burning time is outside the bounds of StartHourand EndHour, then the fire does not burn.  If the wind speed is less than MaxWS, then the fire does not burn.  If the relative humidity is greater than MinRH, then the fire does not burn.  Otherwise, the fire will burn based on the spatial and temporal conditions available.

This method is a candidate for updating and should used with care. This method definition uses a non-standard (w/r to the rest of this interface) means of identifying days and times. This method declaration is also very limiting with respect to the type and range of conditions which may define the burning condition (and thus the fire growth).

Parameters

day	Identifies the day of the simulation to set these conditions upon
bEffective	Enables or disables the burning condition
StartHour	Start of the burning period of the day
EndHour	End of the burning period of the day
MaxWS	Minimum wind speed which will sustain burning
MinRH	Maximum relative humidity which will sustain burning
MinFWI	Minimum FWI value which will sustain burning

See Also

ICWFGM_Scenario::GetDayBurnCondition

Return values

E_POINTER	The address provided for bEffective, StartHour, EndHour, MaxWS, or MinRH is invalid
ERROR_SEVERITY_WARNING	Day in not within acceptable range

STDMETHODIMP CCWFGM_Scenario::GetDefaultBurnCondition	(	VARIANT_BOOL *	bEffective,
		USHORT *	StartHour,
		USHORT *	EndHour,
		double *	MaxWS,
		double *	MinRH,
		double *	MinFWI
	)

Burning conditions may individually exist for each day of the simulation.  In addition, a standard, default burning condition can be defined for any day without specific settings.  This method retrieves those default burning conditions.

This method is a candidate for updating and should used with care. This method definition uses a non-standard (w/r to the rest of this interface) means of identifying times. This method declaration is also very limiting with respect to the type and range of conditions which may define the burning condition (and thus the fire growth).

Parameters

bEffective	Enables or disables the burning condition
StartHour	Start of the burning period of the day
EndHour	End of the burning period of the day
MaxWS	Minimum wind speed which will sustain burning
MinRH	Maximum relative humidity which will sustain burning
MinFWI	Minimum FWI value which will sustain burning

See Also

ICWFGM_Scenario::GetDefaultBurnCondition

Return values

E_POINTER	The address provided for bEffective, StartHour, EndHour, MaxWS, or MinRH is invalid
S_OK	Successful

STDMETHODIMP CCWFGM_Scenario::GetGridEngine	(	LONGLONG *	layerThread,
		ICWFGM_GridEngine **	pVal
	)

Sets or retrieves the object exposing the GridEngine interface that this scenario object uses to retrieve the spatial and temporal grid data (representing fuels, elevations, and weather). Note that objects implementing this interface may be chained, or layered together, but the scenario object is only concerned with the top-most object.

Parameters

pVal	Value of GridEngine
layerThread	Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers.

See Also

ICWFGM_Scenario::GetGridEngine

Return values

E_POINTER	The address provided for layerThread or pVal is invalid
S_OK	Successful
ERROR_GRID_UNINITIALIZED	The value was retrieved before it had been initialized.

STDMETHODIMP CCWFGM_Scenario::GetIgnitionCount

(

ULONG *

count

)

Returns the number of ignitions associated with this scenario object.

Parameters

count

Number of ignitions

See Also

ICWFGM_Scenario::GetIgnitionCount

Return values

E_POINTER	The address provided for count is invalid
S_OK	Successful

STDMETHODIMP CCWFGM_Scenario::GetNumberFires	(	ULONGLONG *	time,
		ULONG *	count
	)

Returns the number of fires (burning, partially burning, or not burning) which are in the simulation at the specified time.

Parameters

time	Time for the query
count	Return value, number of fires

See Also

ICWFGM_Scenario::GetNumberFires

Return values

E_POINTER	The address provided for time, or size is invalid
S_OK	Successful
ERROR_NO_DATA|ERROR_SEVERITY_WARNING	Nothing initialized yet
ERROR_SCENARIO_BAD_STATE	If the function is run while a scenario is not running
SUCCESS_FIRE_NOT_STARTED	Either no fires or the request predates the start time of the simulation

STDMETHODIMP CCWFGM_Scenario::GetNumberSteps

(

ULONG *

steps

)

Given a scenario, this method returns the number of output time steps that have been calculated in the simulation for this fire. A fire can simultaneously contain statistical information for a variety of scenarios.

Parameters

steps

Number of output times steps

See Also

ICWFGM_Scenario::GetNumberSteps

Return values

E_POINTER	The address provided for steps is invalid
S_OK	Successful
ERROR_FIRE_SCENARIO_UNKNOWN	This fire object is not attached to the scenario specified by the scenario parameter
ERROR_SCENARIO_BAD_STATE	If the function is run while a scenario is running

STDMETHODIMP CCWFGM_Scenario::GetStats	(	ULONG	fire,
		ULONGLONG *	time,
		USHORT	stat,
		VARIANT *	stats
	)

This method returns a particular statistic for the fire, for a specific simulation at a specific time. stat must be a valid statistic, as defined in FireEngine_ext.h. time is passed in as a requested time and returned as the actual time that the data is for.

\param fire Index of the fire
\param time Specified GMT time since Midnight January 1, 1600
\param stat Requested statistic.  Valid statistics for query are:
<ul>
  <li><code>CWFGM_FIRE_STAT_TOTAL_PERIMETER</code> 64-bit floating point.  (metres)  Total fire perimeter, including interior and exterior and active/inactive portions.
  <li><code>CWFGM_FIRE_STAT_EXTERIOR_PERIMETER</code> 64-bit floating point.  (metres)  Total exterior fire perimeter, including active and inactive portions.
  <li><code>CWFGM_FIRE_STAT_ACTIVE_PERIMETER</code> 64-bit floating point.  (metres)  Portion of the fire front considered active (interior and exterior) (where 1 or both vertices are active)
  <li><code>CWFGM_FIRE_STAT_AREA</code> 64bit floating point. (sq. metres)  Total area of the fire.
  <li><code>CWFGM_FIRE_STAT_TOTAL_PERIMETER_CHANGE</code> 64-bit floating point.  (metres)  Change in the total perimeter growth.
  <li><code>CWFGM_FIRE_STAT_TOTAL_PERIMETER_GROWTH</code> 64-bit floating point.  (metres per minute)  Rate of change in the total perimeter growth rate.
  <li><code>CWFGM_FIRE_STAT_EXTERIOR_PERIMETER_CHANGE</code> 64-bit floating point.  (metres)  Change in the exterior perimeter growth.
  <li><code>CWFGM_FIRE_STAT_EXTERIOR_PERIMETER_GROWTH</code> 64-bit floating point.  (metres per minute)  Rate of change in the exterior perimeter growth rate.
  <li><code>CWFGM_FIRE_STAT_ACTIVE_PERIMETER_CHANGE</code> 64-bit floating point.  (metres)  Change in the active perimeter growth.
  <li><code>CWFGM_FIRE_STAT_ACTIVE_PERIMETER_GROWTH</code> 64-bit floating point.  (metres per minute)  Rate of change in the active perimeter growth rate.
  <li><code>CWFGM_FIRE_STAT_AREA_CHANGE</code> 64-bit floating point.  (sq. metres).  Change in fire area.
  <li><code>CWFGM_FIRE_STAT_AREA_GROWTH</code> 64-bit floating point.  (sq. metres).  Rate of change in the fire area.
  <li><code>CWFGM_FIRE_STAT_NUM_POINTS</code> 32-bit integer.  Number of vertices defining the fire perimeter(s).
  <li><code>CWFGM_FIRE_STAT_NUM_ACTIVE_POINTS</code> 32-bit integer.  Number of active vertices defining the fire perimeter(s).
  <li><code>CWFGM_FIRE_STAT_CUMULATIVE_NUM_POINTS</code> 32-bit integer.  Total, cumulative number of verticies defining the simulation's perimeters.
  <li><code>CWFGM_FIRE_STAT_NUM_FRONTS</code> 32-bit integer.  Number of fire fronts (interior and exterior).
  <li><code>CWFGM_FIRE_STAT_NUM_ACTIVE_FRONTS</code> 32-bit integer.  Number of fire fronts (interior and exterior) which have at least 1 active vertex.
  <li><code>CWFGM_FIRE_STAT_ROS</code> 64-bit floating point. Maximum rate of spread calculated from Dr. Richards' ellipse equations (metres per minute)
  <li><code>CWFGM_FIRE_STAT_CFB</code> 64-bit floating point. Maximum crown fraction burned (unitless), based on ROS from Dr. Richards' ellipse equations
  <li><code>CWFGM_FIRE_STAT_CFC</code> 64-bit floating point. Maximum crown fuel consumption (kg/m2), based on ROS from Dr. Richards' ellipse equations
  <li><code>CWFGM_FIRE_STAT_SFC</code> 64-bit floating point. Maximum surface fuel consumption (kg/m2), based on ROS from Dr. Richards' ellipse equations
  <li><code>CWFGM_FIRE_STAT_TFC</code> 64-bit floating point. Maximum total fuel consumption (kg/m2), based on ROS from Dr. Richards' ellipse equations
  <li><code>CWFGM_FIRE_STAT_FI</code> 64-bit floating point. Maximum fire intensity, based on ROS from Dr. Richards' ellipse equations
  <li><code>CWFGM_FIRE_STAT_FLAMELENGTH</code> 64-bit floating point. Maximum flame length (metres), based on ROS from Dr. Richards' ellipse equations
</ul>
\param stats Calculated statistic value
\sa ICWFGM_Scenario::GetStats

\retval E_POINTER The address provided for time or stats is invalid
\retval S_OK Successful
\retval ERROR_NO_DATA|ERROR_SEVERITY_WARNING Nothing has been initialized yet
\retval ERROR_FIRE_INVALID_TIME If the time is invalid
\retval ERROR_FIRE_SCENARIO_UNKNOWN This fire object is not attached to the scenario specified by the scenario parameter
\retval SUCCESS_FIRE_NOT_STARTED Fire not yet started (stats is set to 0)
\retval ERROR_FIRE_STAT_UNKNOWN If the stat does not resolve to a known statistic

STDMETHODIMP CCWFGM_Scenario::GetStatsArray	(	ULONG	fire,
		ULONGLONG *	time,
		USHORT	stat,
		ULONG *	size,
		SAFEARRAY **	stats
	)

Given a fire, this method returns a statistic for each point defining a fire front at the time specified in the simulation. stat must be a valid statistic, as defined in FireEngine_ext.h. size is passed in as the size of the array, and returned as the actual number of elements set. xand y are pointers to arrays that will receive the locations (in grid units) of the fire. time is passed in as a requested time and returned as the actual time that the data is for. Statistics data is returned for both active and inactive points.

Parameters

fire	Index of the fire
time	Specified GMT time since Midnight January 1, 1600
stat	Requested statistic, valid statistics are: CWFGM_FIRE_STAT_FBP_RSI initial spread rate without BUI effect, from FBP calculations (metres per minute) CWFGM_FIRE_STAT_FBP_ROS rate of spread from FBP calculations (metres per minute) CWFGM_FIRE_STAT_FBP_BROS back rate of spread from FBP calculations (metres per minute) CWFGM_FIRE_STAT_FBP_FROS flank rate of spread from FBP calculations (metres per minute) CWFGM_FIRE_STAT_RAZ wind speed vector azimuth from FBP calculations (radians, Cartesian) CWFGM_FIRE_STAT_ROS rate of spread calculated from Dr. Richards' ellipse equations (metres per minute) CWFGM_FIRE_STAT_CFB crown fraction burned (unitless), based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_CFC crown fuel consumption (kg/m2), based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_SFC surface fuel consumption (kg/m2), based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_TFC total fuel consumption (kg/m2), based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_FI fire intensity, based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_FLAMELENGTH flame length (metres), based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_OUTER Boolean. (identifies if the point is on the outer hull)
size	Size of the stats array
stats	Array of statistics

See Also

ICWFGM_Scenario::GetStatsArray

Return values

E_POINTER	The address provided for time, size or stats is invalid
S_OK	Successful
E_OUTOFMEMORY	Insufficient memory
ERROR_NOT_DATA|ERROR_SEVERITY_WARNING	Nothing has been initialized yet
SUCCESS_FIRE_NOT_STARTED	The scenario's simulation has been reset to run but hasn't actually stepped yet(in this case, size is returned 0)
ERROR_FIRE_SCENARIO_UNKNOWN	This fire object is not attached to the scenario specified by the scenario parameter
ERROR_SCENARIO_BAD_STATE	If the function is run without any ignitions assigned to the scenario.

STDMETHODIMP CCWFGM_Scenario::GetStatsPercentage	(	ULONG	fire,
		ULONGLONG *	time,
		USHORT	stat,
		double	greater_equal,
		double	less_than,
		double *	stats
	)

This method returns a count of occurence particular statistic for a specific range of values, given a fire and time. stat must be a valid statistic, as defined in FireEngine.h

Parameters

fire	Index of the fire
time	Specified GMT time since Midnight January 1, 1600
stat	Requested statistic. Valid statistics for query are: CWFGM_FIRE_STAT_FBP_RSI initial spread rate without BUI effect, from FBP calculations (metres per minute) CWFGM_FIRE_STAT_FBP_ROS rate of spread from FBP calculations (metres per minute) CWFGM_FIRE_STAT_FBP_BROS back rate of spread from FBP calculations (metres per minute) CWFGM_FIRE_STAT_FBP_FROS flank rate of spread from FBP calculations (metres per minute) CWFGM_FIRE_STAT_ROS rate of spread calculated from Dr. Richards' ellipse equations (metres per minute) CWFGM_FIRE_STAT_CFB crown fraction burned (unitless), based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_CFC crown fuel consumption (kg/m2), based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_SFC surface fuel consumption (kg/m2), based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_TFC total fuel consumption (kg/m2), based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_FI fire intensity, based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_FLAMELENGTH flame length (metres), based on ROS from Dr. Richards' ellipse equations
greater_equal	Lower range of values
less_than	Upper range of values
stats	Calculated statistic value

See Also

ICWFGM_Scenario::GetStatsPercentage

Return values

E_POINTER	The address provided for time or stats is invalid
S_OK	Successful
ERROR_NO_DATA|ERROR_SEVERITY_WARNING	Nothing has been initialized yet
ERROR_FIRE_INVALID_TIME	If the time is invalid
ERROR_FIRE_SCENARIO_UNKNOWN	This fire object is not attached to the scenario specified by the scenario parameter
SUCCESS_FIRE_NOT_STARTED	Fire not yet started (stats is set to 0)
ERROR_FIRE_STAT_UNKNOWN	If stat does not resolve to a known statistic
ERROR_SCENARIO_BAD_STATE	If the function is run without a running scenario
E_OUTOFMEMORY	Insufficient memory

STDMETHODIMP CCWFGM_Scenario::GetStepsArray	(	ULONG *	size,
		SAFEARRAY **	times
	)

Given an array, return the times for each time step calculated in the simulation. size is passed in as the size of the array, and returned as the actual number of elements set. times is a pointer to an array that will receive the GMT times for each calculated time step. The size of the array that is required can be obtained by calling GetNumberSteps().

Parameters

size	Size of the times array
times	Array of times

See Also

ICWFGM_Scenario::GetStepsArray

Return values

E_POINTER	The address provided for size, or times is invalid
S_OK	Successful
E_OUTOFMEMORY	Insufficient memory

STDMETHODIMP CCWFGM_Scenario::GetVectorArray	(	ULONG	fire,
		ULONGLONG *	time,
		ULONG *	size,
		SAFEARRAY **	xy_pairs
	)

Given a fire, this method returns the points defining a fire front at the time specified in the simulation. size is passed in as the size of the array, and returned as the actual number of elements set. Locations are returned in X/Y pairs in the appropriate array (in grid units) of the fire. time is passed in as a requested time and returned as the actual time that the data is for.

Parameters

fire	Index of the fire
time	Specified time(on return, time is set to the actual time the array of coordinates relates to)
size	Size of the xy_pairs array
xy_pairs	2D Array of coordinates

See Also

ICWFGM_Scenario::GetVectorArray

Return values

E_POINTER	The address provided for time, size or xy_pairs is invalid
S_OK	Successful
E_OUTOFMEMORY	Insufficient memory
ERROR_FIRE_SCENARIO_UNKOWN	This fire object is not attached to the scenario specified by the scenario
SUCCESS_FIRE_NOT_STARTED	The scenario's simulation has been reset to turn, but hasn't actually stepped yet(in this case, size is returned 0)
SUCCESS_FIRE_BURNED_OUT	This fire has completely burned out in this simulation and has no remaining points defining it front for this time (size is returned 0)
ERROR_NO_DATA|ERROR_SEVERITY_WARNING	Nothing has been initialized yet
ERROR_SCENARIO_BAD_STATE	If the function is run without any ignition assigned to the scenario

STDMETHODIMP CCWFGM_Scenario::GetVectorEngineCount

(

ULONG *

count

)

Returns the number of vector engine objects associated with this scenario object.

Parameters

count

Number of vector engine objects

See Also

ICWFGM_Scenario::GetVectorEngineCount

Return values

E_POINTER	The address provided for count is invalid
S_OK	Successful

STDMETHODIMP CCWFGM_Scenario::GetVectorSize	(	ULONG	fire,
		ULONGLONG *	time,
		ULONG *	size
	)

Given a fire, this method returns the number of points defining a fire front at the time specified in the simulation. time is passed in as a requested time and returned as the actual time that the vector size relates to.

Parameters

fire	Index of the fire
time	Specified time(on return, time is set to the actual time the vector size relates to)
size	Number of points defining a fire front

See Also

ICWFGM_Scenario::GetVectorSize

Return values

E_POINTER	The address provided for time or size is invalid
S_OK	Successful(if time is invalid)
ERROR_FIRE_SCENARIO_UNKOWN	This fire object is not attached to the scenario specified by the scenario parameter
SUCCESS_FIRE_NOT_STARTED	The scenario's simulation has been reset to run, but hasn't actually stepped yet(in this case size is returned to 0)
ERROR_NO_DATA|ERROR|SEVERITY|WARNING	Nothing has been initialized yet
ERROR_SCENARIO_BAD_STATE	If the function is run without any ignitions assigned to the scenario

STDMETHODIMP CCWFGM_Scenario::GetXYStats	(	double	X,
		double	Y,
		ULONGLONG *	time,
		USHORT	stat,
		USHORT	interp_method,
		VARIANT *	stats
	)

This method returns a particular statistic for a specific location in the fire/grid, for a specific simulation at a specific time. stat must be a valid statistic, as defined in FireEngine_ext.h. time is passed in as a requested time and returned as the actual time that the data is for.

Parameters

X	The x coordinate
Y	The y coordinate
time	Specified GMT time since January 1, 1600
stat	Request statistic. Valid statistics for query are: CWFGM_FIRE_STAT_FBP_RSI initial spread rate without BUI effect, from FBP calculations (metres per minute) CWFGM_FIRE_STAT_FBP_ROS rate of spread from FBP calculations (metres per minute) CWFGM_FIRE_STAT_FBP_BROS back rate of spread from FBP calculations (metres per minute) CWFGM_FIRE_STAT_FBP_FROS flank rate of spread from FBP calculations (metres per minute) CWFGM_FIRE_STAT_RAZ wind speed vector azimuth from FBP calculations (radians, Cartesian) CWFGM_FIRE_STAT_CFB crown fraction burned (unitless), based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_CFC crown fuel consumption (kg/m2), based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_SFC surface fuel consumption (kg/m2), based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_TFC total fuel consumption (kg/m2), based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_FI fire intensity, based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_FLAMELENGTH flame length (metres), based on ROS from Dr. Richards' ellipse equations CWFGM_FIRE_STAT_FMC foliar moisture content CWFGM_FIRE_STAT_ROS rate of spread calculated from Dr. Richards' ellipse equations (metres per minute) CWFGM_FIRE_STAT_ACTIVE Boolean. (Identifies if the point is active or stopped.)
interp_method	How to calculate/determine the value of the statistic requested SCENARIO_XYSTAT_TECHNIQUE_CLOSEST_VERTEX Picks the closest vertex from 1 of 2 specific fire perimeters: the one which first contained the point of interest, and the perimeter immediately prior to that. SCENARIO_XYSTAT_TECHNIQUE_IDW Calculates the statistic using IDW, using all local, active vertices. SCENARIO_XYSTAT_TECHNIQUE_AREA_WEIGHTING Calculates the statistic using weighting based on union between voronoi regions and the grid cell of interest. SCENARIO_XYSTAT_TECHNIQUE_VORONOI_OVERLAP Calculates the statistic using weighting based on the union of the point's inserted voronoi region and the voronoi regions of each vertex without the point. SCENARIO_XYSTAT_TECHNIQUE_CALCULATE Calculates the statistic in the same manner as the simulation would.
stats	Calculated statistic value

See Also

ICWFGM_Scenario::GetXYStats

Return values

E_POINTER	The address provided for time or stats is invalid
S_OK	Successful
ERROR_NO_DATA|ERROR_SEVERITY_WARNING	Nothing has been initialized yet
ERROR_FIRE_INVALID_TIME	If the time is invalid
ERROR_FIRE_SCENARIO_UNKNOWN	This fire object is not attached to the scenario specified by the scenario parameter
SUCCESS_FIRE_NOT_STARTED	Fire not yet started(stats is set to 0)
ERROR_FIRE_STAT_UNKNOWN	If stat does not rewolve to a known statistic
ERROR_SCENARIO_BAD_STATE	If the function is run without a running scenario
E_OUTOFMEMORY	Insufficient memory

STDMETHODIMP CCWFGM_Scenario::IgnitionAtFireIndex	(	ULONG	index,
		ULONGLONG *	time,
		ICWFGM_Ignition **	fire
	)

Given a fire at a specific time in the simulation, identifies the ignition from which the fire originated.

Parameters

index	Index of the fire
time	Time of the simulation
fire	Return value; ignition

See Also

ICWFGM_Scenario::IgnitionAtFireIndex

Return values

E_POINTER	The address provided for fire is invalid
S_OK	Successful
ERROR_NODATA|ERROR_SEVERITY_WARNING	Nothing initialized yet
ERROR_SCENARIO_BAD_STATE	If the function is run while a scenario is not running
SUCCESS_FIRE_NOT_STARTED	Either no fires or the request predates the start time of the simulation
ERROR_SCENARIO_FIRE_UNKNOWN	This fire object is not attached to the scenario specified by the scenario parameter

STDMETHODIMP CCWFGM_Scenario::IgnitionAtIndex	(	ULONG	index,
		ICWFGM_Ignition **	fire
	)

Given an index value, returns a pointer to an ignition associated with this scenario.

Parameters

index	Index to an ignition
fire	An ignition object

See Also

ICWFGM_Scenario::IgnitionAtIndex

Return values

E_POINTER	The address provided for fire is invalid
S_OK	Successful
ERROR_SCENARIO_FIRE_UNKOWN	Index is invalid

STDMETHODIMP CCWFGM_Scenario::IndexOfIgnition	(	ICWFGM_Ignition *	fire,
		ULONG *	index
	)

Returns the index of fire in this scenario's set of ignitions.

Parameters

fire	An ignition object
index	Index to a fire object

See Also

ICWFGM_Scenario::IndexOfIgnition

Return values

E_POINTER	The address provided for fire or index is invalid
S_OK	Successful
ERROR_SCENARIO_FIRE_UNKNOWN	If fire does not resolve to a know fire for this scenario

STDMETHODIMP CCWFGM_Scenario::IndexOfVectorEngine	(	ICWFGM_VectorEngine *	vectorEngine,
		ULONG *	index
	)

Returns the index of vectorEngine in this scenario's set of vector engines.

Parameters

vectorEngine	A vector engine object
index	Indes to a vector engine

See Also

ICWFGM_Scenario::IndexOfVectorEngine

Return values

E_POINTER	The address provided for vectorEngine or index is invalid
S_OK	Successful
ERROR_SCENARIO_VECTORENGINE_UNKNOWN	If vectorEngine does not reolve to a known vector engine for this scenario

STDMETHODIMP CCWFGM_Scenario::IsXYBurned	(	double	X,
		double	Y,
		ULONGLONG	time,
		short *	burned
	)

Retrieves whether the location at (X, Y) was burned before or during time.

Parameters

X	X coordinate
Y	Y coordinate
time	A GMT time provided as seconds since Midnight January 1, 1600
burned	If the location has been burned, this value is set to 1, otherwise it is set to 0.

See Also

ICWFGM_Scenario::IsXYBurned

Return values

E_POINTER	The address provided for burned is invalid
S_OK	Successful
ERROR_SCENARIO_BAD_STATE	If the function is run while a scenario is running
ERROR_NODATA|ERROR_SEVERITY	WARNING Nothing initialized yet
SUCCESS_FINE_NOT_STARTED	Either no fires or the request predates the start time of the simulation

STDMETHODIMP CCWFGM_Scenario::put_UserData

(

VARIANT

newVal

)

This property is unused by the scenario object, and is available for exclusive use by the client code.

It is a VARIANT so that the client code may store pointer values for use in subclassing this object. This value is not loaded or saved during serialization operations, and it is the responsibility of the client code to manage any value or object stored here. Access to this property is not thread-safe.

Parameters

newVal

Replacement value for UserData

See Also

ICWFGM_Scenario::UserData

Return values

E_POINTER	The address provided for pVal is invalid
S_OK	Successful

STDMETHODIMP CCWFGM_Scenario::PutGridEngine	(	LONGLONG	layerThread,
		ICWFGM_GridEngine *	newVal
	)

Sets or retrieves the object exposing the GridEngine interface that this scenario object uses to retrieve the spatial and temporal grid data (representing fuels, elevations, and weather). Note that objects implementing this interface may be chained, or layered together, but the scenario object is only concerned with the top-most object.

Parameters

newVal	Replacement value for GridEngine
layerThread	Handle for scenario layering/stack access, allocated from an ICWFGM_LayerManager COM object. Needed. It is designed to allow nested layering analogous to the GIS layers.

See Also

ICWFGM_Scenario::PutGridEngine

Return values

S_OK	Successful
ERROR_GRID_UNINITIALIZED	The value was retrieved before it had been initialized.
E_NOINTERFACE	The object provided doesn't support the ICWFGM_GridEngine interface.

STDMETHODIMP CCWFGM_Scenario::RemoveIgnition

(

ICWFGM_Ignition *

fire

)

Removes an association between an ignition and this scenario object.

Parameters

fire	An ignition object

See Also

ICWFGM_Scenario::RemoveIgnition

Return values

E_POINTER	The address provided for fire is invalid
S_OK	Successful
ERROR_SCENARIO_BAD_STATE	If this function is run while the scenario is running
ERROR_SCENARIO_FIRE_UNKNOWN	Fire is unknown to this scenario object

STDMETHODIMP CCWFGM_Scenario::RemoveVectorEngine

(

ICWFGM_VectorEngine *

vectorEngine

)

Removes a vector engine object from this scenario.

Parameters

vectorEngine

A vector engine object

See Also

ICWFGM_Scenario::RemoveVectorEngine

Return values

E_POINTER	The address provided for VectorEngine is invalid.
S_OK	Successful
ERROR_SCENARIO_BAD_STATE	If this function is run while the scenario is running
ERROR_SCENARIO_VECTORENGINE_UNKNOWN	If vectorEngine does not resolve to a known vector engine for this scenario.

STDMETHODIMP CCWFGM_Scenario::SetAttribute	(	USHORT	option,
		VARIANT	value
	)

Polymorphic.  Sets a value for a scenario setting that the client application can modify to change the operation of the scenario.  
    \param option Option of interest(a list of possible options appears in "FireEngine_ext.h".  Supported / valid attribute/option index supported are:

• CWFGM_SCENARIO_OPTION_ACCEL Boolean. If TRUE, then acceleration is applied to various output statistics in the FBP standard. This value should only applicable to point ignitions. If FALSE, then the fire is assumed to be always at equilibrium.
• CWFGM_SCENARIO_OPTION_BUI Boolean. If TRUE, then the BUI build-up effect is applied to various statistics in the FBP standard.
• CWFGM_SCENARIO_OPTION_TOPOGRAPHY Boolean. If TRUE, then the slope component to calculating the WSV output statistic in the FBP standard is set to 0.0. If TRUE, then the wind speed is used as provided. This setting also affects the slope component in Dr. Richards' 3D equations.
• CWFGM_SCENARIO_OPTION_GREENUP Boolean. Specific FBP fuel types use different equations during green-up. This flag determines whether to use green-up equations or not.
• CWFGM_SCENARIO_OPTION_FMC_TERRAIN Boolean. If TRUE, then elevation is used to calculate FMC. Note that specific rules exist when default elevations have to be used.
• CWFGM_SCENARIO_OPTION_WIND Boolean. If FALSE, then the wind component to calculating the WSV statistic in the FBP standard is set to 0.0. If TRUE, then the wind speed is used as provided.
• CWFGM_SCENARIO_OPTION_EXTINGUISHMENT Boolean. Currently unused.
• CWFGM_SCENARIO_OPTION_USE_2DGROWTH Boolean. TRUE if using Dr. Richards' 2D equations. FALSE if using Dr. Richards' 3D equations.
• CWFGM_SCENARIO_OPTION_BOUNDARY_STOP Boolean. TRUE if the simulation stops when any simulated fire reaches the grid boundary. FALSE if the simulation should continue (in which case, any perimeter of the fire is stopped and clipped at the grid boundary).
• CWFGM_SCENARIO_OPTION_SPOTTING Boolean. Currently unused.
• CWFGM_SCENARIO_OPTION_BREACHING Boolean. Determines whether breaching of vector and gridded fire breaks is allowed.
• CWFGM_SCENARIO_OPTION_SINGLETHREADING Boolean. TRUE if multithreading within a simulation is disabled. FALSE if multithreading is enabled.
• CWFGM_SCENARIO_OPTION_NONFUELS_AS_VECTOR_BREAKS Boolean. When TRUE, square polygons are built around each non-fuel grid cell. This option affects performance, and how breaching, etc. operations perform around non-fuel grid cells.
• CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_TEMPORAL Boolean. When TRUE, temporal weather interpolation is turned on, for all of the WX and hourly/instantantaneous FWI calculations.
• CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_SPATIAL Boolean. When TRUE, spatial weather interpolation is turned on. This option applies to both WX and FWI values, and will work whether there is 1 or more weather stations assigned to the scenario. If FALSE, then there should only be one weather stream.
• CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_PRECIP Boolean. Conditional on CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_SPATIAL. When TRUE, precipitation is spatially interpolated using IDW. When FALSE, precipitation from the primary weather stream is used.
• CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_WIND Boolean. Conditional on CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_SPATIAL. When TRUE, wind is spatially interpolated (WS is defined using IDW, WD is chosen from the closest station); when FALSE, wind from the primary weather stream is used.
• CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_TEMP_RH Boolean. Conditional on CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_SPATIAL. When TRUE, temperature, dew point temperature, and RH are calculated spatially from adiabatic lapse rates; when FALSE, values from the primary weather stream are used.
• CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_CALCFWI Boolean. If FALSE, then the current FWI values are returned (possibly interpolated). If TRUE, then the current FWI values are calculated from the prior FWI values and the current weather values (likely spatially interpolated).
• CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_HISTORY Boolean. Conditional on CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_SPATIAL and CWFGM_SCENARIO_OPTION_WEATHER_INTERPOLATE_CALCFWI. If TRUE, then historical FWI values are calculated to try to attain equilibrium on FWI values.
• CWFGM_SCENARIO_OPTION_ACCURATE_FMC_LOCATION Boolean. When TRUE, the precise location of a simulated fire vertex is used when calculating FMC. When FALSE, the grid's lower left corner is used in calculating FMC.
• CWFGM_SCENARIO_OPTION_STARTING_POINTS 16-bit unsigned integer. Number of verticies used for a point ignition. Valid values are 6 to 64 inclusive.
• CWFGM_SCENARIO_OPTION_MULTITHREADING 32-bit unsigned integer. If multithreading is enabled, then this option determines how many threads to allow.
• CWFGM_SCENARIO_OPTION_PERIMETER_RESOLUTION 64-bit floating point. Maximum distance between any two vertices on a fire perimeter.
• CWFGM_SCENARIO_OPTION_SPATIAL_THRESHOLD 64-bit floating point. Maximum distance (in grid units) that a vertex is allows to travel while advancing a fire perimeter.
• CWFGM_SCENARIO_OPTION_SMOOTHING_WEIGHT 64-bit floating point. Smoothing factor which allows a vertex's neighbours' rates of spread to impact its calculated distance travelled.
• CWFGM_GRID_ATTRIBUTE_LATITUDE 64-bit floating point, radians.
• CWFGM_GRID_ATTRIBUTE_LONGITUDE 64-bit floating point, radians.
• CWFGM_SCENARIO_OPTION_SPECIFIED_FMC 64-bit floating point. User-override FMC value for the simulation. If >= 0, then the value is used, if < 0 then, this value is not used.
• CWFGM_SCENARIO_OPTION_DEFAULT_ELEVATION 64-bit floating point, metres. User specified elevation to use when there is no grid elevation available for at a requested grid location.
• CWFGM_SCENARIO_OPTION_IGNITION_SIZE 64-bit floating point. Diameter (in grid units) of the starting circle of an ignition point. Also used to determine the width of an ignition line.
• CWFGM_SCENARIO_OPTION_START_TIME 64-bit unsigned integer. GMT time provided as seconds since Midnight January 1, 1600
• CWFGM_SCENARIO_OPTION_END_TIME 64-bit unsigned integer. GMT time provided as seconds since Midnight January 1, 1600
• CWFGM_SCENARIO_OPTION_TEMPORAL_THRESHOLD 64-bit signed integer. Units are in seconds. Maximum time allowed between any two adjacent simulation time steps.
• CWFGM_SCENARIO_OPTION_TEMPORAL_THRESHOLD_ACCEL 64-bit signed integer. Units are in seconds. Maximum time allowed between two adjacent simulation time steps when any ignition is in its acceleration phase (when ROSt is less than 90% of ROSeq).
• CWFGM_SCENARIO_OPTION_DISPLAY_INTERVAL 64-bit signed integer. Units are in seconds. Time interval for output fire perimeters, or 0 if every time step is to be outputted.
• CWFGM_GRID_ATTRIBUTE_TIMEZONE 64-bit signed integer. Units are in seconds, relative to GMT. For example, MST (Mountain Standard Time) would be -6 * 60 * 60 seconds. Valid values are from -12 hours to +12 hours.
• CWFGM_GRID_ATTRIBUTE_DAYLIGHT_SAVINGS 64-bit signed integer. Units are in seconds. Amount of correction to apply for daylight savings time.
• CWFGM_GRID_ATTRIBUTE_DST_START 64-bit unsigned integer. Units are in seconds. Julian date determining when daylight savings starts within the calendar year.
• CWFGM_GRID_ATTRIBUTE_DST_END 64-bit unsigned integer. Units are in seconds. Julian date determining when daylight savings ends within the calendar year.
• CWFGM_SCENARIO_OPTION_CACHE_GRID_POINTS Boolean. When TRUE, caches will be calculated to determine the closest points (for statistics purposes) to the center of each grid cell.

Parameters

value

Polymorphic. Value for option being set.

See Also

ICWFGM_Scenario::SetAttribute

Return values

S_OK	Successful
ERR0R_SCENARIO_OPTION_INVALID	An unknown boolean option was asked for
ERROR_SCENARIO_BAD_STATE	If this function is run while the scenario is running
E_INVALIDARG	If value is not 0 or 1
E_FAIL	Unspecified error
E_POINTER	The address provided is invalid

STDMETHODIMP CCWFGM_Scenario::SetDayBurnCondition	(	SHORT	day,
		VARIANT_BOOL	bEffective,
		USHORT	StartHour,
		USHORT	EndHour,
		double	MaxWS,
		double	MinRH,
		double	MinFWI
	)

Sets the burning conditions for a specific day in the simulation.  If the burning time is outside the bounds of StartHour and EndHour, then the fire does not burn.  If the wind speed is less than MaxWS, then the fire does not burn.  If the relative humidity is greater than 'MinRH', then the fire does not burn.  Otherwise, the fire will burn based on the spatial and temporal conditions available.

This method is a candidate for updating and should used with care. This method definition uses a non-standard (w/r to the rest of this interface) means of identifying days and times. This method declaration is also very limiting with respect to the type and range of conditions which may define the burning condition (and thus the fire growth). The implementation in this scenario object also requires that if burning conditions exits for days 3, 5, then specific burning conditions must also exist for days 0, 1, 2, 4.

Parameters

day	Identifires the day of the simulation to set these conditions upon
bEffective	Enables or disables the burning condition
StartHour	Start of the burning period of the day
EndHour	End of the burning period of the day
MaxWS	Minimum wind speed which will sustain burning
MinRH	Maximum relative humidity which will sustain burning
MinFWI	Minimum FWI value which will sustain burning

See Also

ICWFGM_Scenario::SetDayBurnCondition

Return values

S_OK	Successful
ERROR_SEVERITY_WARNING	If day not within acceptable range
E_INVALIDARG	If any of the parameters passed in are invalid
ERROR_SCENRARIO_BAD_STATE	If function is called while scenario is running

STDMETHODIMP CCWFGM_Scenario::SetDefaultBurnCondition	(	VARIANT_BOOL	bEffective,
		USHORT	StartHour,
		USHORT	EndHour,
		double	MaxWS,
		double	MinRH,
		double	MinFWI
	)

Burning conditions may individually exist for each day of the simulation.  In addition, a standard, default burning condition can be defined for any day without specific settings.  This method sets these default burning conditions.

This method is a candidate for updating and should used with care. This method definition uses a non-standard (w/r to the rest of this interface) means of identifying times. This method declaration is also very limiting with respect to the type and range of conditions which may define the burning condition (and thus the fire growth).

Parameters

bEffective	Enables or disables the burning condition
StartHour	Start of the burning period of the day
EndHour	End of the burning period of the day
MaxWS	Minimum windpseed which will sustain burning
MinRH	Maximum relative humidity which will sustain burning
MinFWI	Minimum FWI value which will sustain burning

See Also

ICWFGM_Scenario::SetDefaultBurnCondition

Return values

S_OK	Successful
ERROR_SCENARIO_BAD_STATE	If the function is run while a scenario is running

STDMETHODIMP CCWFGM_Scenario::Simulation_Clear

(

)

Clears the current scenario's calculations, unlocks the scenario's objects and clears the displays.

See Also

ICWFGM_Scenario::Simulation_Clear

Return values

S_OK	Success
ERROR_SCENARIO_BAD_STATE	Scenario is running

STDMETHODIMP CCWFGM_Scenario::Simulation_Reset

(

)

Prepares a scenario's simulation to begin running. This routine must be called before Simulation_Step(), and must be called to re-run a simulation. This routine erases any data stored from a previously running simulation.

See Also

ICWFGM_Scenario::Simulation_Reset

Return values

S_OK	Scenario ready to execute, but has not begun
ERROR_GRID_UNINTIATLIZED	No ICWFGM_GridEngine object has been specified, or that object doesn't have an initialized latitude, longitude, or time zone.
ERROR_SCENARIO_NO_FIRES	No fires have been attached to the scenario
ERROR_SCENARIO_BAD_TIMES	Start or end time is invalid or the internal or output calculations intervals are invalid
ERROR_SCENARIO_BAD_TIME_STEPS	The time steps are invalid
ERROR_SCENARIO_INVALID_BURNCONDITIONS	Invalid burn condition settings (burning periods between days overlap)
ERROR_SEVERITY_WARNING	The FuelMap for the object implementing the ICWFGM_GridEngine interface has not been set, or no FBP data has been loaded
ERROR_GRID_WEATHER_NOT_IMPLEMENTED	The object implementing the ICWFGM_Grid_Enging interface does not handle weather data, and it was asked to test for valididty against simulation times
ERROR_SCENARIO_BAD_STATE	If this function is run while the scenario is running
ERROR_GRID_WEATHER_INVALID_DATES	Weather grids which were attached are in an invalid state
S_FALSE	Unspecified error
E_OUTOFMEMORY	Insufficient memory
E_INVALIDARG	Unspecified error
E_FAIL	Unspecified error
ERROR_WEATHER_STREAM_NOT_ASSIGNED	No weather streams are attached to this scenario
E_POINTER	Unspecified error

STDMETHODIMP CCWFGM_Scenario::Simulation_State

(

)

Returns the current state of the simulation, being currently running, complete, or in some invalid state preventing any simulation from beginning.

See Also

ICWFGM_Scenario::Simulation_State

Return values

S_OK	Scenario ready toexecute, but has not begun
ERROR_GRID_UNINITALIZED	No ICWFGM_GridEngine object has been specified or that object doesn't have an initialized latitude, longitude, or time zone
ERROR_SCENARIO_NO_FIRES	No fires have been attached to the scenario
ERROR_SCENARIO_BAD_TIMES	Start of end time is invalid, or the internal or output calculations intervals are invalid
ERROR_SCEARNIO_BAD_TIMESTEPS	The time steps are invalid
ERROR_SCENARIO_INVALID_BURNCONDITIONS	Invalid burn condition settings (burning periods between days overlap)
ERROR_SEVERITY_WARNING	The FuelMap for the object implementing the ICWFGM_GridEngine interface has not been set, or no FBP data has been loaded
ERROR_GRID_WEATHER_NOT_IMPLEMENTED	The object implementing the ICWFGM_GridEngine does not handle weather data, and it was asked to test for validity against simulation times
SUCCESS_SCENARIO_SIMULATION_RESET	The scenarios has been reset and is pending simulation execution
SUCCESS_SCENARIO_SIMULATION_RUNNING	The scenario's simulation is running
SUCCESS_SCENARIO_SIMULATION_COMPLETE	The scenario's simulation is complete
ERROR_GRID_WEATHER_INVALID_DATES	Weather grids which were attached are in an invalid state
ERROR_GRID_PRIMARY_STREAM_UNSPECIFIED	Multiple weather streams exist, but none have been identified as the primary weather stream.
S_FALSE	Unspecified error
E_OUTOFMEMORY	Out of memory
E_INVALIDARG	Unspecified error
E_FAIL	Unspecified error
ERROR_WEATHER_STREAM_NOT_ASSIGNED	No weather streams are attached to this scenario
E_POINTER	Unspecified error

STDMETHODIMP CCWFGM_Scenario::Simulation_Step

(

)

Runs the simulation for exactly one calculation time step period of time. This routine can be called after Simulation_Reset().

See Also

ICWFGM_Scenario::Simulation_Step

Return values

S_OK	Scenario ready to execute, but has not begun
ERROR_SCENARIO_BAD_STATE	Scenario is not running
SUCCESS_SCENARIO_SIMULATION_COMPLETE	This step completes simulation
ERROR_GRID_UNINITIALIZED	No ICWFGM_GridEngine object has been specified, or that object doesn't have an initalized latitude, longitude, or time zone
E_OUTOFMEMORY	Insufficient memory

STDMETHODIMP CCWFGM_Scenario::Simulation_StepBack

(

)

Removes one displayable step during a simulation.

See Also

ICWFGM_Scenario::Simulation_StepBack

Return values

S_OK	Successful
ERROR_SCENARIO_BAD_STATE	Scenario is not running
ERR0R_GRID_UNINTIALIZED	No ICWFGM_GridEngine object has been specified, or that object doesn't have an initialized latitude, longitude, or time zone.

STDMETHODIMP CCWFGM_Scenario::VectorEngineAtIndex	(	ULONG	index,
		ICWFGM_VectorEngine **	vectorEngine
	)

Given an index value, returns a pointer to a vector engine associated with this scenario.

Parameters

index	Indes to a vector engine
vectorEngine	A vector engine object

See Also

ICWFGM_Scenario::VectorEngineAtIndex

Return values

E_POINTER	The address provided for vector Engine is invalid
S_OK	Successful
ERROR_SCENARIO_VECTORENGINE_UNKNOWN	If index does not resolve to a known vector engine