IMcGlueProgressMeter Interface

This is an interface supplied by the client to provide progress meter and message queue discharge during NTI operations.

Namespace: MediaCy.IQL.ObjectManager
Assembly: MediaCy.IQL.ObjectManager (in MediaCy.IQL.ObjectManager.dll) Version: 10.0.6912.0

Syntax

Copy

Public Interface IMcGlueProgressMeter

The IMcGlueProgressMeter type exposes the following members.

Properties

	Name	Description
	ControlFlags
	EndingValue
	NumberOfPhases
	StartingValue
	Title

Top

Methods

	Name	Description
	Initialize
	PopState
	ProcessMessages
	PushState
	ResetToDefaults
	SetProgress
	Shutdown

Top

Remarks

The client code assigns an IMcGlueProgressMeter instance pointer to the IMcEngine::McGlueProgressMeter property and thereafer that instance is used by the NTI operators to communicate progress. The NTI operators will always call Initialize before they use the progress meter, and they will call Shutdown when they are done. All properties should be reset to a default state after a call to Initialize or ResetToDefaults. The NIT operator may set the Title property to a string describing the operation being tracked (e.g., "Low Pass Filter"); or they my allow the the client to supply default (e.g., "Operation"). Operators will assume that the StartingValue is zero and EndingValue is 100 by default. The default state of ControlFlags is set by the client from the mcgluePMFlagsEnum in McGConsts.h. The most reasonable default for ControlFlags is zero (see below). Periodically, the operator will call SetProgress with a value between StartingValue and EndingValue, inclusive. The client should not assume that a call to SetProgress with an argument of EndingValue means that no more calls will be made; wait for Shutdown. You may get multiple calls to set EndingValue, especially if the mcgluePMFlagMultiPartOperation ControlFlag is set (in this case each assignment to EndingValue will be one pass through some algorithm). If you are doing timing, you should reset the base time for each such call (an implied assignment to EndingValue should also be assumed when Initialize is called). The mcgluePMFlagExpectUnevenProgress ControlFlag will be set by operations that are known to take a variable amount of time for each unit of progress. The operator will also call ProcessMessages and check the VARIANT_BOOL* pbEscaped return value for a user escape. The client code should discharge the message queue and look for an Escape key press. It the mcgluePMFlagNoEscapeAllowed ControlFlag is set, you should always return bEscaped as FALSE. If the mcgluePMFlagNoCallback ControlFlag is set, then you should not discharge the message queue or check for escape. The operator will abort if bEscaped is returned as TRUE, but it will still call Shutdown when it is done. The operator may call ResetToDefaults at any time. This call implies an assignment to EndingValue and so a resetting of any base time tracking. PushState and PopState should save and restore all properties on a stack. In addition, if the client is tracking time, the time interval between a PushState and corresponding PopState should be added onto the base time (that is, the pushed time interval is one of suspended operation). Operators may call upon the services of a single instance of a client IMcGlueProgressMeter in a nested fashion. Thus, the Initialize method should do a PushState before anything else, and the Shutdown method should do a PopState after cleaning up the current state.

Note
Code in McGlueProgressMeter.h does most of the above for you. The client only needs to supply a derived class with overrides to a few virtual functions: InitializeImpl, FirstProgressImpl, SetProgressImpl, ProcessMessagesImpl, and ShutdownImpl. An ATL interface class is then derived from this class to declare the interface. Additions and changes (JAS 1/01): The built-in functionality supports nested tracking. However, each phase gets its own display from 0 to 100%, so the progress meter constantly resets to 0. Also, the initialization sets the tracking string to blank. What is needed more often is nested progress tracking where the only phase that can set the text and flags, and where the total span of the progress meter is divided up between the phases of the process. This is handled by expanding on the interface we define - as before the McGlueProgressMeter.h file includes implementation code to support all of the new functionality. When the first process calls Initialize, the nesting level is zero and the process gains "ownership" of the tracking bar. If the process is a simple one (i.e. an erosion filter), then the default single phase is appropriate, the process sets the starting and ending values, and the progress meter tracks from 0 to 100% completion. If the process is more complex (e.g. Close, which combines N passes each of erosion and dilation) then it's first act (after calling the Initialize method) is to notify the progress meter that the process is a multi-phase operation. This is done by setting the mcgluePMFlagMultiPartOperation flag, but calling SetNumberOfPhases will also do this. The process should use the SetNumberOfPhases method to inform the progress meter of only the number of phases it knows about - if one of the phases has sub-phases, it is responsible for that. It is then assumed by the progress meter that each Initialize and Shutdown signals the beginning and end of one of these phases. Note that if the owner process has a phase of its own, it must call Initialize and Shutdown to meter that phase. It may be instructive to look at even a more complexly nested process. Let's say that calculating measurements may include 1 to N measurements that are enabled (for this example, let's say there are 5 measurements enabled), each of which should track while calculating. Further, one or more of the measurements (in this example M3) may call another operator, which may itself be a compound operation which for this example will call the Close operation with 2 passes. The following represents how the total progress meter span will be sub-divided: \|---------------------------- calculating measurements (100%) -------------------------\| \|-----M1--------\|\|-------M2-------\|\| \|\|-------M4-------\|\|-------M5------\| \| \|-M3--\| \|E\|\|E\|\|D\|\|D\| The thoughtful reader will note that progress in this case will be very uneven - depending on the ratio of the number of objects versus image size (and other factors), the "simple" measurements M1, M2, M4, and M5 will probably track significantly faster than the complex one M3. This is unavoidable without a much more complex negotiation process (the calculation asking each potentially independent measurement about its relative duration, and each measurement asking the operators that it uses).

Note

Code in McGlueProgressMeter.h does most of the above for you. The client only needs to supply a derived class with overrides to a few virtual functions: InitializeImpl, FirstProgressImpl, SetProgressImpl, ProcessMessagesImpl, and ShutdownImpl. An ATL interface class is then derived from this class to declare the interface. Additions and changes (JAS 1/01): The built-in functionality supports nested tracking. However, each phase gets its own display from 0 to 100%, so the progress meter constantly resets to 0. Also, the initialization sets the tracking string to blank. What is needed more often is nested progress tracking where the only phase that can set the text and flags, and where the total span of the progress meter is divided up between the phases of the process. This is handled by expanding on the interface we define - as before the McGlueProgressMeter.h file includes implementation code to support all of the new functionality. When the first process calls Initialize, the nesting level is zero and the process gains "ownership" of the tracking bar. If the process is a simple one (i.e. an erosion filter), then the default single phase is appropriate, the process sets the starting and ending values, and the progress meter tracks from 0 to 100% completion. If the process is more complex (e.g. Close, which combines N passes each of erosion and dilation) then it's first act (after calling the Initialize method) is to notify the progress meter that the process is a multi-phase operation. This is done by setting the mcgluePMFlagMultiPartOperation flag, but calling SetNumberOfPhases will also do this. The process should use the SetNumberOfPhases method to inform the progress meter of only the number of phases it knows about - if one of the phases has sub-phases, it is responsible for that. It is then assumed by the progress meter that each Initialize and Shutdown signals the beginning and end of one of these phases. Note that if the owner process has a phase of its own, it must call Initialize and Shutdown to meter that phase. It may be instructive to look at even a more complexly nested process. Let's say that calculating measurements may include 1 to N measurements that are enabled (for this example, let's say there are 5 measurements enabled), each of which should track while calculating. Further, one or more of the measurements (in this example M3) may call another operator, which may itself be a compound operation which for this example will call the Close operation with 2 passes. The following represents how the total progress meter span will be sub-divided: |---------------------------- calculating measurements (100%) -------------------------| |-----M1--------||-------M2-------|| ||-------M4-------||-------M5------| | |-M3--| |E||E||D||D| The thoughtful reader will note that progress in this case will be very uneven - depending on the ratio of the number of objects versus image size (and other factors), the "simple" measurements M1, M2, M4, and M5 will probably track significantly faster than the complex one M3. This is unavoidable without a much more complex negotiation process (the calculation asking each potentially independent measurement about its relative duration, and each measurement asking the operators that it uses).

Reference

MediaCy.IQL.ObjectManager Namespace