User:Barre/Workflow

Introduction

The following sections describe the wizard workflow that is currently used in KWWidgets. This worfklow framework was created to help porting the EMSegmentation module (Polina Golland, Kilian Pohl) to Slicer3. This work is also part of the National Alliance for Medical Image Computing (NAMIC), funded by the National Institutes of Health through the NIH Roadmap for Medical Research, Grant U54 EB005149.

Since a wizard is fundamentally a set of steps as well as additional logic and controls to navigate from one step to the other, we decided that a state machine or a Petri net would present a reasonable low-level basis for this framework. After some internal discussion at Kitware, we agreed that even a stab at a simple Petri net engine would not be a trivial task given the time frame and the resources allocated for this project. However, we chose to leverage and borrow a large part of the state machine engine design found in IGSTK, while porting it to a more KWWidgets/VTK friendly environment. The resulting framework does not provide ITK-style C++ templating or extensive compile-time checks, but is compatible with VTK's coding style and wrapping technology.

KWWizardDialog Example

EMSegmentation Module

State Machine Engine

Nothing groundbreaking here. A few simple classes to represent states, inputs, and transitions that are triggered when the machine is in a particuliar state and receive a specific input, etc.

• vtkKWStateMachineState: a state
• vtkKWStateMachineInput: an input (which triggers transitions)
• vtkKWStateMachineTransition: a transition between 2 states
• vtkKWStateMachine: a state machine

A few additional classes are available.

• vtkKWStateMachineCluster: a cluster (group) of states
• vtkKWStateMachineDOTWriter: a writer to Graphviz's DOT format
• vtkKWStateMachineWriter: a writer superclass

vtkKWStateMachineState

The vtkKWStateMachineState class provides the representation for a state. The following members are available:

• Id: unique state ID
• Name: string
• Description: string
• Enter/Leave: callbacks and events

The Enter/Leave callbacks and events are fired automatically by the state machine when it enters (respectively leaves) that state, independent of the transition to (respectively from) that state. This can be used, for example, to bring up the GUI of the wizard step associated to that state, or cleanup any resources that were used by that GUI.

vtkKWStateMachineInput

The vtkKWStateMachineInput class provides the representation for an input, i.e. the single token that triggers a transition from one state to the other. The following members are available:

• Id: unique input ID
• Name: string

vtkKWStateMachineTransition

The vtkKWStateMachineTransition class provides the representation for transition between two states given a specific input. The following members are available:

• Id: unique transition ID
• OriginState: vtkKWStateMachineState
• Input: vtkKWStateMachineInput
• DestinationState: vtkKWStateMachineState
• Start/End: callbacks and events

The Start callback and event are fired automatically when the transition is "started" by the state machine: the state machine is about to leave the OriginState but has not yet entered the DestinationState. This End callback and event are fired in a similar fashion when the transition is "ended" by the state machine: the state machine has left the OriginState and entered the DestinationState.

Associating a command/callback to a transition is a pretty common state machine pattern, but the question remains as when to trigger this callback: before leaving the originating state, or after reaching the destination state. We chose to accomodate both solutions by allowing the user to specify a command that can be triggered either at the beginning of the transiton (Start), or at the end.

vtkKWStateMachine

The vtkKWStateMachine class provides the representation for a state machine engine. A state machine is defined by a set of states, a set of inputs and a transition matrix that defines for each pair of (state,input) what is the next state to assume. The following members are available:

• AddState(state): add a state to the state machine
• AddInput(input): add an input to the state machine
• AddTransition(transition): add a transition to the state machine

Transitions instances can also be created automatically given the corresponding states and input:

• CreateTransition(origin_state, input, destination_state): create and add a transition

The initial and current state of the machine can be set and (respectively retrieved) using:

• SetInitialState(state): set the initial state (bootstrap the machine)
• GetCurrentState(state): retrive the current state

The engine itself is set into motion by pushing inputs and periodically asking the machine to process them:

• PushInput(state): push a new input to the queue of inputs to be processed
• ProcessInputs: perform state transitions for every pending input stored in the input queue.

Additional methods are provided to retrieve inputs/states/transitions from the machine, query the number of inputs/states/transition, search for a specific transition, etc. Transitions triggered by the state machine are saved in a transition history than can be queried. Clusters (groups) of states can be formed, providing a way to relate some states logically (this is used for display and I/O purposes, for example).

Example

The TestStateMachine.cxx file provides a detailed example on how to use the state machine engine. Here are a few excerpts:

  vtkKWStateMachine *state_machine = vtkKWStateMachine::New();

[...]

  vtkKWStateMachineState *state_1 = vtkKWStateMachineState::New();
  state_1->SetName("Start");
  state_machine->AddState(state_1);

[...]

  vtkKWStateMachineInput *input_next = vtkKWStateMachineInput::New();
  input_next->SetName("next");
  state_machine->AddInput(input_next);

[...]

  // Transition: state_1 / input_next => state_2

  vtkKWStateMachineTransition *trans_a = vtkKWStateMachineTransition::New();
  trans_a->SetOriginState(state_1);
  trans_a->SetInput(input_next);
  trans_a->SetDestinationState(state_2);
  state_machine->AddTransition(trans_a);

  // Transition: state_1 / skip => state_3

  state_machine->CreateTransition(state_1, input_skip, state_3);

[...]

  // Run the state machine

  state_machine->SetInitialState(state_1);
  state_machine->PushInput(input_next);    // state_1 to state_2
  state_machine->PushInput(input_invalid); // state_2 to state_2
  state_machine->ProcessInputs();

The vtkKWStateMachineDOTWriter class can be used to output a graphical representation of the state machine to the Graphviz's DOT format (see below). The resulting file can either be turned into an image using the dot executable, or rendered dynamically/on-the-fly by any MediaWiki supporting the GraphViz extension.

Note that both state 2 and 3 were grouped together logically using a cluster.

  vtkKWStateMachineCluster *cluster = vtkKWStateMachineCluster::New();
  cluster->AddState(state_2);
  cluster->AddState(state_3);
  state_machine->AddCluster(cluster);

  vtkKWStateMachineDOTWriter *writer = vtkKWStateMachineDOTWriter::New();
  writer->SetInput(state_machine);
  writer->SetGraphLabel("State Machine Example");
  writer->WriteToStream(cout);

Wizard Workflow

How can we make things a little easier for the specific case of a simple Wizard? Here are a couple of thoughts:

• a wizard is a most of the time a linear succession of steps (this will be our major assumption so far),
• you can navigate from one step to the next one other using a 'Next' and 'Back' button,
• you can navigate from one step to the previoous one using a 'Back' button,
• a 'Finish' may allow you to skip to the last step,
• a menu or a list of steps may allow you to go to a specific step explicitly,
• one need to make sure a step is valid before going to the next one,
• one probably do *not* need to make sure a step is valid before going to the previous one,
• one probably want to be able to guess a reasonable set of defaults values for a given step (ideally, values that make that step already 'valid'),
• one could be interested in knowing how much of a step is 'completed' to make it 'valid' (this could be used in the UI to display step names as 'green' or 'red' and locate visually which steps require to be completed in priority).

Let's introduce the following subclasses:

vtkKWWizardStep

A wizard step, subclass of vtkKWStateMachineState:

 - [Set/Get] ValidateCommand (callback): callback that will validate the step and push the 
                                         corresponding error inputs if needed (returns int)
 - [Set/Get] EstimateDefaultsCommand (callback): callback that will attempt to estimate reasonable 
                                                 defaults value for this step
 - [Set/Get] EstimateCompletionCommand (callback): callback that can be used to estimate the completion
                                                   of that step (returns normalized double)
 - [Get] GoToSelfInput (vtkKWStateMachineInput*): member variable that acts as an input specifying 
         "I want to go to that instance step"

Note that GoToSelfInput is just a convenience member variable, an input that is automatically made available to you so that you can specify that you want to go to a specific step. Encapsulating the input inside the step you want to go to make it pretty clear from a notation/code point of view that you are referring to a specific step. This does not mean, however, that transitions have been created for you at this point, this is still up to you to explicitly create transitions that respond to that input, or explicitly call methods like vtkKWWizardWorkflow::AddLinearNavigationTransitions() (see below) to create some. Anyway, it is up to you to use GoToSelfInput or not, you can definitely ignore it actually.

vtkKWWizardWorkflow

A wizard workflow, subclass of vtkKWStateMachine. The following class, vtkKWWizardWorkflow, is a specialization of a vtkKWStateMachine that offers a few convenience classes relying on the strong assumption that there exist a "linear" path of steps that were added as vtkKWWizardStep instances. As such, at given any step, the workflow can find the previous and next step (if any) and use that knowledge (see below). However, methods are not provided to retrieve the previous or next step in order not to bring the impression that a may start writing logic based on this methods, instead of programming the state machine correctly.

 - AddLinearNavigationTransitions(): assuming the states/steps were added as instance of vtkKWWizardStep, in 
    the right order, create transitions from one step to the next step (if any), and from one step to the previous
    one (if any). This can be done by using each steps' GoToSelfInput member variable as input to the transitions.
    For example, given steps A, B, C, this method would pretty much call:
       this->AddTransition(A, B->GetGoToSelfInput(), B);   // go from A to B
       this->AddTransition(B, A->GetGoToSelfInput(), A);   // go from B to A
       this->AddTransition(B, C->GetGoToSelfInput(), C);   // go from B to C
    At this point, pushing B->GetGoToSelfInput() on the state machine, when the current state is A, will move it to
    step B.
 - AddDirectNavigationTransitions(): assuming the states/steps were added as instance of vtkKWWizardStep, in 
    the right order, create direct transitions from one step to all other steps (as a side effect, this also includes
    adding all linear transitions in the process).
    This can be done by using each steps' GoToSelfInput member variable as input to the transitions.
    For example, given steps A, B, C, this method would pretty much call:
       this->AddTransition(A, B->GetGoToSelfInput(), B);   // go from A to B
       this->AddTransition(A, C->GetGoToSelfInput(), C);   // go from A to C
       this->AddTransition(B, A->GetGoToSelfInput(), A);   // go from B to A
       this->AddTransition(B, C->GetGoToSelfInput(), C);   // go from B to C
       this->AddTransition(C, A->GetGoToSelfInput(), A);   // go from C to A
       this->AddTransition(C, B->GetGoToSelfInput(), B);   // go from C to B

Again, those are convenience methods, they probably probably more transitions than you would need, but you can also choose to ignore them and add transitions manually. The following methods are also for convenience and can be used to navigate from one step to the other, and as such can be associated to buttons like "Next" or "Back" in a Wizard UI:

 - RequestGoToNextStep(): given the current step 'current_step', try to go to the next step by
   invoking 'current_step->ValidateCommand on the current step/state to check if we can leave the step 
   (i.e. its contents is valid), or if an error should be reported (its contents is not valid):
   - if ValidateCommand fails (returns o), do nothing, as it is up to the ValidateCommand
     to push error inputs that will in turn trigger transitions that can display error messgages and lead back
     to the same 'current_step' for example.
   - if ValidateCommand succeeds (returns 1), get the next step 'next_step' following 'current_step' and push a 
     next_step->GoToSelfInput to the state machine to go to 'next_step'.
 - RequestGoToPreviousStep(): given the current step 'current_step', go to the previous step by
   getting the previous step 'prev_step' preceeding 'current_step' (if any) and push a prev_step->GoToSelfInput to the
   state machine to go to 'prev_step'.
 - GoToStep(vtkKWWizardStep *step): given the current step 'current_step'
   'while' we have not reached 'step', validate current step, 
     - if it fails break the loop, 
     - if it succeeds get the next step, invoke EstimateDefaultsCommand and
       push a next_step->GoToSelfInput
   the loop will try to go as far as it can, as long as the step could be
   validated with the defaults that were estimated.    
 - GoToLastStep(): self-explanatory

Remember, those are convenience methods that are useful to drive the state machine from a UI. You can ignore them and still rely on the generic state machine model to program your wizard. The "linearity" of transition between the states is from a "step" point of view, you can add more states to the machine as instances of vtkKWStateMachineState, as long as only instances of vtkKWWizardStep are used to specificy a linear "path" among the states. This is a constraint/assumption.

From a UI point of view, we probably also need something that can tell us *if* we can go to a given step, so that we can disable or grey out the corresponding "Next"/"Back" button, I'll leave that for another time.