High-level interface to a process instance. More...

#include <ProcessInstance.h>

Inheritance diagram for pcl::ProcessInstance:

Public Member Functions
	ProcessInstance (const Process &process)

	ProcessInstance (const ProcessInstance &p)

	~ProcessInstance () override

bool	AllocateTableRows (const IsoString &tableId, size_type rowCount)

bool	AllocateTableRows (const ProcessParameter &table, size_type rowCount)

bool	Assign (const ProcessInstance &p)

bool	CanExecuteGlobal (String &whyNot) const

bool	CanExecuteOn (const ImageVariant &image, String &whyNot) const

bool	CanExecuteOn (const View &view, String &whyNot) const

bool	CanLaunchInterface () const

ProcessInstance	Clone () const

String	Description () const

double	ElapsedTime () const

bool	ExecuteGlobal ()

bool	ExecuteOn (ImageVariant &image, const IsoString &hints=IsoString())

bool	ExecuteOn (View &view, bool swapFile=true)

void	GetExecutionTimes (double &startJD, double &elapsedSecs) const

bool	IsHistoryUpdater (const View &view) const

bool	IsMaskable (const View &view, const ImageWindow &mask) const

bool	Launch ()

bool	LaunchInterface ()

ProcessInstance &	operator= (const ProcessInstance &p)

Variant	ParameterValue (const IsoString &parameterId, size_type rowIndex=~size_type(0)) const

Variant	ParameterValue (const ProcessParameter &parameter, size_type rowIndex=~size_type(0)) const

Process	ParentProcess () const

void	SetDescription (const String &text)

bool	SetParameterValue (const Variant &value, const IsoString &parameterId, size_type rowIndex=~size_type(0))

bool	SetParameterValue (const Variant &value, const ProcessParameter &parameter, size_type rowIndex=~size_type(0))

double	StartJD () const

size_type	TableRowCount (const IsoString &tableId) const

size_type	TableRowCount (const ProcessParameter &table) const

String	ToSource (const IsoString &language="JavaScript", const IsoString &varId=IsoString(), int indent=0) const

bool	Validate (String &whyNot)

uint32	Version () const

Public Member Functions inherited from pcl::UIObject
virtual	~UIObject () noexcept(false)

virtual void	EnsureUnique ()

bool	IsAlias () const

bool	IsGarbage () const

bool	IsNull () const

bool	IsSameObject (const UIObject &o) const

bool	IsUnique () const

String	ObjectId () const

IsoString	ObjectType () const

bool	operator< (const UIObject &o) const

bool	operator== (const UIObject &o) const

size_type	RefCount () const

void	SetObjectId (const String &id)

Static Public Member Functions
static ProcessInstance	FromIcon (const IsoString &iconId)

static ProcessInstance	FromSource (const String &source, const IsoString &language="JavaScript")

static IsoStringList	Icons ()

static IsoStringList	IconsByProcessId (const IsoString &processId)

static ProcessInstance &	Null ()

Static Public Member Functions inherited from pcl::UIObject
static UIObject &	Null ()

Additional Inherited Members
Protected Member Functions inherited from pcl::UIObject
	UIObject ()=default

	UIObject (const UIObject &x)

	UIObject (UIObject &&x)

UIObject &	operator= (const UIObject &x)

UIObject &	operator= (UIObject &&x)

Detailed Description

ProcessInstance, along with Process, provides access to any installed process through intermodule communication.

ProcessInstance represents a live instance of an installed process that can be edited (by setting parameter values) and executed.

See also: Process

Definition at line 86 of file ProcessInstance.h.

Constructor & Destructor Documentation

◆ ProcessInstance() [1/2]

pcl::ProcessInstance::ProcessInstance ( const Process & process )

Constructs this object as a reference to a new instance of the specified process. The newly created instance has a set of default parameter values.

◆ ProcessInstance() [2/2]

pcl::ProcessInstance::ProcessInstance ( const ProcessInstance & p )

inline

Copy constructor. The newly constructed object references the same server-side process instance as the specified object p.

Note: Note that this constructor does not generate a new process instance. It just constructs a high-level reference to an existing process instance.

Definition at line 105 of file ProcessInstance.h.

◆ ~ProcessInstance()

pcl::ProcessInstance::~ProcessInstance ( )

inlineoverride

Destroys a process instance.

After destruction of this object, the server-side process instance is also destroyed (garbage-collected) if it is no longer referenced by other ProcessInstance objects.

Definition at line 116 of file ProcessInstance.h.

Member Function Documentation

◆ AllocateTableRows() [1/2]

bool pcl::ProcessInstance::AllocateTableRows	(	const IsoString &	tableId,
		size_type	rowCount
	)

inline

Allocates table rows for a table process parameter.

This is an overloaded member function, provided for convenience. It allows reallocating a table parameter rows using a parameter identifier instead of a reference to a ProcessParameter object. Otherwise this member function behaves exactly like AllocateTableRows( const ProcessParameter&, size_type )

Definition at line 682 of file ProcessInstance.h.

◆ AllocateTableRows() [2/2]

bool pcl::ProcessInstance::AllocateTableRows	(	const ProcessParameter &	table,
		size_type	rowCount
	)

Allocates table rows for a table process parameter.

Parameters

table	Reference to a table parameter in the parent process.
rowCount	Number of table rows to allocate. If the parameter has table row limitations, this value must be within the acceptable range.

Calling this member function deallocates all previously existing table rows in this instance, if there were any. Table rows cannot be appended neither deleted selectively; the whole table parameter is reallocated as a whole each time this member function is called. Calling this function with rowCount set to zero (if zero rows are acceptable for the specified table parameter) effectively deallocates the whole table parameter in this instance.

Returns true if the specified number of rows could be allocated successfully in this process instance; false in the event of error.

◆ Assign()

bool pcl::ProcessInstance::Assign ( const ProcessInstance & p )

Assigns the parameters of a process instance referenced by the specified object p to the instance referenced by this object. Returns true if the assignment operation was successful; false in the event of error.

Note that this member function does not do the same as an assignment operator or a copy constructor, because the latter two operations simply cause this object to reference an existing server-side instance (and possibly leave a previous instance unreferenced). This member function does not generate a new process instance and does not change existing references to server-side objects; it just copies process parameters (and probably other module-dependent data) from one existing instance to another.

Note: For this member function to success, the parent Process has to be an assignable process. Assignable processes return true from reimplemented Process::IsAssignable() virtual functions.

◆ CanExecuteGlobal()

bool pcl::ProcessInstance::CanExecuteGlobal ( String & whyNot ) const

Returns true iff this process instance can be executed in the global context.

If this member function returns false, the process should return in the string whyNot a description of the reasons why this instance cannot be executed on the global context. If the function returns true, the string whyNot will be cleared (so it will be empty and its previous contents will be lost).

A process is executed in the global context when it is not explicitly executed on a particular view. Two well-known examples of global processes are Preferences and ReadoutOptions. Note that a process can work both globally and on views. For example, the PixelMath process can work globally to generate new images, or locally when it is executed on a target view.

◆ CanExecuteOn() [1/2]

bool pcl::ProcessInstance::CanExecuteOn	(	const ImageVariant &	image,
		String &	whyNot
	)		const

Validates execution of this process instance on the specified image. Returns true iff this instance can be executed on the image.

If this member function returns false, the process should return in the string whyNot a description of the reasons why this instance cannot be executed on the specified image. If the function returns true, the string whyNot will be cleared (so it will be empty and its previous contents will be lost).

◆ CanExecuteOn() [2/2]

bool pcl::ProcessInstance::CanExecuteOn	(	const View &	view,
		String &	whyNot
	)		const

Validates execution of this process instance on the specified view. Returns true iff this instance can be executed on the view.

If this member function returns false, the process should return in the string whyNot a description of the reasons why this instance cannot be executed on the specified view. If the function returns true, the string whyNot will be cleared (so it will be empty and its previous contents will be lost).

◆ CanLaunchInterface()

bool pcl::ProcessInstance::CanLaunchInterface ( ) const

Returns true iff this process instance is able to open and activate a process interface.

Normally, each process has an associated interface that can always be launched through any existing (and valid) instance of the appropriate process class. However, there are some processes for which an interface does not make sense. A well-known example is the Invert process.

◆ Clone()

ProcessInstance pcl::ProcessInstance::Clone ( ) const

Generates a uniquely referenced, newly created process instance as a duplicate of the instance referenced by this object, and returns a high-level reference to it as a new ProcessInstance object.

◆ Description()

String pcl::ProcessInstance::Description ( ) const

Returns the descriptive text currently associated with this process instance, or an empty string if this instance has no description.

In PixInsight, each process instance has an associated text that the user can edit to describe the purpose and conditions of the applied processes. This feature is an extremely useful and efficient way to document a processing procedure.

◆ ElapsedTime()

double pcl::ProcessInstance::ElapsedTime ( ) const

inline

Returns the total elapsed time in seconds for the latest execution of this process instance, or zero if either this instance has never been executed, or if the execution time has not been recorded for some reason.

Definition at line 421 of file ProcessInstance.h.

◆ ExecuteGlobal()

bool pcl::ProcessInstance::ExecuteGlobal ( )

Executes this process instance on the global context. Returns true upon successful execution; false in the event of error.

See the documentation for CanExecuteGlobal() for additional comments on process execution contexts.

◆ ExecuteOn() [1/2]

bool pcl::ProcessInstance::ExecuteOn	(	ImageVariant &	image,
		const IsoString &	hints = `IsoString()`
	)

Executes this process instance on the specified image. Returns true upon successful execution; false in the event of error.

Parameters

image Reference to an ImageVariant object that transports the image to be processed.

hints A string containing a (possibly empty) list of hints intended to modify the way an image is processed. A process can simply ignore all of these hints, or just look for one or more hints that it recognizes and supports, ignoring others. When two or more hints are specified, they must be separated by space characters (0x20). File formats also support hints in a similar way; see for example the FileFormatInstance::Open() member function for more information. The default value is an empty string.

◆ ExecuteOn() [2/2]

bool pcl::ProcessInstance::ExecuteOn	(	View &	view,
		bool	swapFile = `true`
	)

Executes this process instance on the specified view. Returns true upon successful execution; false in the event of error.

The optional swapFile argument allows the caller to control generation of swap data as part of the instance execution. If swapFile is true (the default value), the PixInsight core application will save the previous state of the target view before instance execution. In this case the executed instance will be appended to the view's process history in the usual way, and the process will be undoable.

If swapFile is false, the previous state of the view is not saved, the instance is not added to the view's history, and the process cannot be undone after execution. In this case the caller module is responsible for leaving the image transported by view in a valid and predictable state. Keep in mind that if no swap data are generated before excution, the user has no way to restore the previous state of the image, and also has no way to control the sequence of processes that have given rise to the current state of the image. If these side effects are not correctly controlled and handled by the calling module, they will violate basic design principles of the PixInsight platform, and hence they can be a good reason for denying certification of a module.

This member function is typically called with the swapFile argument set to false by processes that execute other processes to implement their own tasks. For example, the standard ProcessContainer process (which is internal to the core application) does exactly this to execute a sequence of processes as a unique step in a view's process history. Another case where swapFile should be set to false is when a process generates a new image as a result of running a sequence of processes, but it wants to appear as the unique process in the initial state element of the view's process history.

◆ FromIcon()

static ProcessInstance pcl::ProcessInstance::FromIcon ( const IsoString & iconId )

static

Returns a process instance generated as a duplicate of the instance transported by a process icon with the specified identifier iconId.

Returns a null instance if the specified icon does not exist, or if an icon exists with the specified identifier but it is not a process icon (e.g., an image icon).

◆ FromSource()

static ProcessInstance pcl::ProcessInstance::FromSource	(	const String &	source,
		const IsoString &	language = `"JavaScript"`
	)

static

Returns a process instance generated from the specified source code.

Note: This member function is still not implemented; it will be implemented in a future version of PCL. For now, this function always returns a null process instance.

◆ GetExecutionTimes()

void pcl::ProcessInstance::GetExecutionTimes	(	double &	startJD,
		double &	elapsedSecs
	)		const

Gets the running times for the latest execution of this process instance.

Parameters

[out]	startJD	Starting execution time as a Julian day number.
[out]	elapsedSecs	Total elapsed execution time in seconds.

If this instance has never been executed, or if the execution times have not been recorded for some reason, both output values are set to zero.

◆ Icons()

static IsoStringList pcl::ProcessInstance::Icons ( )

static

Returns a string list with the identifiers of all existing process icons, or an empty list if there are no process icons.

◆ IconsByProcessId()

static IsoStringList pcl::ProcessInstance::IconsByProcessId ( const IsoString & processId )

static

Returns a string list with the identifiers of all existing process icons transporting instances of the specified process, or an empty list if no such icons exist.

◆ IsHistoryUpdater()

bool pcl::ProcessInstance::IsHistoryUpdater ( const View & view ) const

Returns true iff this process instance will modify the process history of the specified view, in case it is executed on it.

If this member function returns false, then this instance can be safely executed on the view as a read-only process; the view won't be modified in any way.

◆ IsMaskable()

bool pcl::ProcessInstance::IsMaskable	(	const View &	view,
		const ImageWindow &	mask
	)		const

Returns true iff this process instance can be masked with the specified image window when executed on the specified view.

When a process is masked, its result is mixed with the image in the state it was before execution, according to the values of a mask image. This process is carried out automatically by the PixInsight core application.

◆ Launch()

bool pcl::ProcessInstance::Launch ( )

Launches this process instance.

If this process has an associated default interface, then its top level window is shown and activated, and this instance is imported by the interface. After importing this instance, the interface will show its parameter values.

If this process has no default interface, then the core application attempts to execute this instance. If the process prefers global execution (see the Process::PrefersGlobalExecution() member function), then this instance will be executed in the global context; otherwise it will be executed on the current view, if there is at least one image available.

Returns true if this instance was successfully launched; false in the event of error, or if the core application was unable to launch or execute the instance.

◆ LaunchInterface()

bool pcl::ProcessInstance::LaunchInterface ( )

Opens and activates the interface associated to this process, and causes it to import this instance. After importing this instance, the interface will show its parameter values. Returns true if the interface could be successfully launched; false in the event of error.

◆ Null()

static ProcessInstance& pcl::ProcessInstance::Null ( )

static

Returns a reference to a null process instance. A null ProcessInstance object does not correspond to an existing process instance in the PixInsight core application.

◆ operator=()

ProcessInstance& pcl::ProcessInstance::operator= ( const ProcessInstance & p )

inline

Assignment operator. Returns a reference to this object.

Makes this object reference the same server-side process instance as the specified object p. If the previous instance becomes unreferenced, it will be garbage-collected by the PixInsight core application.

Definition at line 157 of file ProcessInstance.h.

◆ ParameterValue() [1/2]

Variant pcl::ProcessInstance::ParameterValue	(	const IsoString &	parameterId,
		size_type	rowIndex = `~size_type( 0 )`
	)		const

inline

Returns the value of a process parameter.

This is an overloaded member function, provided for convenience. It allows retrieving parameter values using parameter identifiers instead of references to ProcessParameter objects. Otherwise this member function behaves exactly like ParameterValue( const ProcessParameter&, size_type ) const

Definition at line 546 of file ProcessInstance.h.

◆ ParameterValue() [2/2]

Variant pcl::ProcessInstance::ParameterValue	(	const ProcessParameter &	parameter,
		size_type	rowIndex = `~size_type(0)`
	)		const

Returns the value of a process parameter.

Parameters

parameter	Reference to an existing parameter in the parent process of this instance (see Process::Parameters()).
rowIndex	Zero-based index of the table row, when the specified parameter is a table column parameter. Must be within the range of existing rows for the corresponding table parameter in this instance, that is, from zero to the number of table rows minus one. If parameter is not a table column parameter this argument is ignored.

If the specified parameter is a table process parameter, this member function throws an Error exception. A table process parameter does not have a value, and its contents cannot be retrieved directly as a whole.

Note that the default value of the rowIndex argument is an impossible row index number: ~size_type(0). This value has been selected on purpose in order to force the caller to specify a row index when parameter is a table column parameter. This is a simple but effective security mechanism to robustify parameter access code: if no row index is specified for a table column parameter, this member function will always return an invalid Variant object (see below).

This member function returns a Variant object with the current value of the specified parameter or table cell parameter in this instance. An invalid Variant object is returned in the following cases:

If the specified parameter is not a valid parameter of the parent process.

If parameter is a table column parameter and the specified rowIndex is larger than or equal to the number of existing rows for the parent table parameter in this instance.

The calling process should always check Variant::IsValid() for the objects returned by this function.

◆ ParentProcess()

Process pcl::ProcessInstance::ParentProcess ( ) const

Returns a Process object that represents the installed process that this instance belongs to.

◆ SetDescription()

void pcl::ProcessInstance::SetDescription ( const String & text )

Sets the descriptive text for this process instance.

Instance descriptions can make use of the whole formating capabilities of PixInsight consoles; see the Console class for more information.

◆ SetParameterValue() [1/2]

bool pcl::ProcessInstance::SetParameterValue	(	const Variant &	value,
		const IsoString &	parameterId,
		size_type	rowIndex = `~size_type( 0 )`
	)

inline

Sets the value of a process parameter.

This is an overloaded member function, provided for convenience. It allows changing parameter values using parameter identifiers instead of references to ProcessParameter objects. Otherwise this member function behaves exactly like SetParameterValue( const Variant&, const ProcessParameter&, size_type )

Definition at line 612 of file ProcessInstance.h.

◆ SetParameterValue() [2/2]

bool pcl::ProcessInstance::SetParameterValue	(	const Variant &	value,
		const ProcessParameter &	parameter,
		size_type	rowIndex = `~size_type(0)`
	)

Sets the value of a process parameter.

Parameters

value	New parameter value. The specified Variant object must transport an object of either the same type as the parameter whose value will be changed, or of a type that can legally be converted to the corresponding parameter type. The value must also observe the limits imposed by the parent process regarding acceptable values, numeric ranges, etc.
parameter	Reference to an existing parameter in the parent process of this instance (see Process::Parameters()).
rowIndex	Zero-based index of the table row, when the specified parameter is a table column parameter. Must be within the range of existing rows for the corresponding table parameter in this instance, that is, from zero to the number of table rows minus one. If parameter is not a table column parameter this argument is ignored.

If the specified parameter is a table process parameter, this member function throws an Error exception. A table process parameter does not have a value, and its contents cannot be set directly as a whole.

Note that the default value of the rowIndex argument is an impossible row index number: ~size_type(0). This value has been selected on purpose in order to force the caller to specify a row index when parameter is a table column parameter. This is a simple but effective security mechanism to robustify parameter access code: if no row index is specified for a table column parameter, this member function will always return false.

The value must observe the limits imposed by the parent process regarding valid numeric ranges, length limits, acceptable characters, etc., depending on parameter types. This member function returns true iff the parameter value could be set correctly. If the type of value cannot be converted to the required parameter type, an Error exception is thrown with the appropriate error message.

Note: To set the values of table column parameters, the necessary table rows must be allocated before calling this member function. To allocate table rows, use the AllocateTableRows() member function.

◆ StartJD()

double pcl::ProcessInstance::StartJD ( ) const

inline

Returns the time when this process instance was last executed as a Julian day number. If this instance has never been executed, or if the execution time has not been recorded for some reason, this function returns zero.

Definition at line 409 of file ProcessInstance.h.

◆ TableRowCount() [1/2]

size_type pcl::ProcessInstance::TableRowCount ( const IsoString & tableId ) const

inline

Returns the number of existing rows in a table process parameter.

This is an overloaded member function, provided for convenience. It returns the number of existing table rows using parameter identifiers instead of references to ProcessParameter objects. Otherwise this member function behaves exactly like TableRowCount( const ProcessParameter& ) const

Definition at line 641 of file ProcessInstance.h.

◆ TableRowCount() [2/2]

size_type pcl::ProcessInstance::TableRowCount ( const ProcessParameter & table ) const

Returns the number of existing rows in a table process parameter.

Parameters

table Reference to a table parameter in the parent process.

If the specified parameter is not a table process parameter of the parent process, this member function returns zero.

◆ ToSource()

String pcl::ProcessInstance::ToSource	(	const IsoString &	language = `"JavaScript"`,
		const IsoString &	varId = `IsoString()`,
		int	indent = `0`
	)		const

Returns a source code representation of this process instance.

Parameters

language	The language to use for the source code representation. Currently the only languages supported are "JavaScript" and "XPSM 1.0". The default language is JavaScript.
varId	The identifier of a variable that will be used to represent this instance. If an empty string is specified (which is the default value), the PixInsight core application wll assign a default identifier. This identifier only applies to JavaScript source code representations, not to XML representations.
indent	Indentation distance in characters. This is a constant number of white space characters (0x20) that will be prepended to each source code line. The default value is zero.

The source code generated by this function can be used directly for serialization of process instances in the specified language.

◆ Validate()

bool pcl::ProcessInstance::Validate ( String & whyNot )

Requests the parent process to validate this process instance. Returns true upon successful validation; false if the instance is not valid, or in the event of error.

If this member function returns false, the process should return a description of the reasons to not validate the instance in the string whyNot. If the function returns true, the string whyNot will be cleared (so it will be empty and its previous contents will be lost).

◆ Version()

uint32 pcl::ProcessInstance::Version ( ) const

Returns the version number of this process instance.

Instance version numbers are useful to manage different implementations of processes, especially when instances are deserialized from existing projects, process icons, etc.

This function may return zero if the version number is undefined for this instance for some reason, although this should not happen under normal conditions. Valid version numbers are always ≥ 1.

The version number that will be assigned to newly created process instances will always be the value returned by the MetaProcess::Version() member function (or a reimplementation of it) for the parent process.

The documentation for this class was generated from the following file:

ProcessInstance.h

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ProcessInstance() [1/2]

◆ ProcessInstance() [2/2]

◆ ~ProcessInstance()

Member Function Documentation

◆ AllocateTableRows() [1/2]

◆ AllocateTableRows() [2/2]

◆ Assign()

◆ CanExecuteGlobal()

◆ CanExecuteOn() [1/2]

◆ CanExecuteOn() [2/2]

◆ CanLaunchInterface()

◆ Clone()

◆ Description()

◆ ElapsedTime()

◆ ExecuteGlobal()

◆ ExecuteOn() [1/2]

◆ ExecuteOn() [2/2]

◆ FromIcon()

◆ FromSource()

◆ GetExecutionTimes()

◆ Icons()

◆ IconsByProcessId()

◆ IsHistoryUpdater()

◆ IsMaskable()

◆ Launch()

◆ LaunchInterface()

◆ Null()

◆ operator=()

◆ ParameterValue() [1/2]

◆ ParameterValue() [2/2]

◆ ParentProcess()

◆ SetDescription()

◆ SetParameterValue() [1/2]

◆ SetParameterValue() [2/2]

◆ StartJD()

◆ TableRowCount() [1/2]

◆ TableRowCount() [2/2]

◆ ToSource()

◆ Validate()

◆ Version()