ImageDev

Processing

This section introduces processing interaction functions.

Most of ImageDev algorithms frequently send messages to:
See related example Note: This example mainly shows how to use the verbose mode and how to intercept algorithm progression and messages. Other functions are illustrated at the end of this page.

Syntax

Method Description
void setVerbose(bool enable) Sets default callbacks that print the name of which algorithm is starting and its execution time.
  • enable: Enables callbacks if true, disables them otherwise.
bool getVerbose() Returns True if the verbose mode is enabled, False otherwise.
void setCpuNumber(int cpuNumber) Activates a user-defined number of logical processors to be used by ImageDev algorithms.
Most of the ImageDev algorithms are CPU parallelized. However, if the computation time scales well with the CPU clock speed, it does not with the number of threads. Generally, using more than 8 threads is useless. For instance, a system with a 3.2 GHz, 8 threads processor configuration can run ImageDev algorithms faster than a system with 2.7 GHz and 32 threads.

This phenomenon is easy to explain. When processing an image in parallel, each selected logical processor computes a result for an image block. Once two contiguous blocks are processed, a fusion step is necessary to merge the results of these blocks. This step may be more or less complex depending on several parameters, such as:
  • The nature of the algorithm (point-wise operators require less fusion than fixed window filters, which require less fusion than propagation-based algorithms).
  • The number of logical processors used (the higher it is, the longer the fusion step takes).
  • The size of the blocks (this parameter is automatically managed by ImageDev).
On systems having more than 8 logical processors, it may be interesting to monitor the influence of the number of logical processors used on the execution time of a given recipe.
  • cpuNumber: The number of logical processors to be used. All processors are used if this value is lower than or equal to zero.
int getCpuNumber() Returns the user-defined number of logical processors to be used by ImageDev algorithms. If the returned value is lower than or equal to zero, all processors are used.
void setProgressRatioCallback( ProgressRatioCallback progressRatioCallback ) Sets the ratio callback used to track the progression of algorithms.
  • progressRatioCallback: The progression ratio callback used to track the progression of algorithms. It must have two arguments:
    • A GenericAlgorithm object, which represents the algorithm being executed.
    • A float value representing the progression ratio between 0 and 1.
ProgressRatioCallback getProgressRatioCallback() Returns a pointer or a reference to the ratio callback function if it has been defined, null or none otherwise.
void setProgressMessageCallback( ProgressMessageCallback progressMessageCallback ) Sets the message callback used to be notified about generic messages sent by algorithms.
  • progressMessageCallback: The progression message callback used to notify algorithm information. It must have two arguments:
    • A GenericAlgorithm object, which represents the algorithm being executed.
    • A string value representing the message sent by the algorithm.
ProgressMessageCallback getProgressMessageCallback() Returns a pointer or a reference to the message callback function if it has been defined, null or none otherwise.
void setProgressDataCallback( ProgressDataCallback progressDataCallback ) Sets the data callback used to be notified about formatted messages sent by algorithms.
  • progressDataCallback: The progression data callback used to notify algorithm information. It must have two arguments:
    • A GenericAlgorithm object, which represents the algorithm being executed.
    • A string value representing data sent by the algorithm.
    • A string value representing the encoding of data sent by the algorithm.
ProgressDataCallback getProgressDataCallback() Returns a pointer or a reference to the data callback function if it has been defined, null or none otherwise.
void setCancellationCallback( CancellationCallback cancellationCallback ) Sets the cancellation callback that can be used to interrupt an algorithm before being completed.
  • CancellationCallback: The cancellation callback used to notify algorithm cancellation. It has one argument, a GenericAlgorithm object, which represents the algorithm being executed. This function has to return True when the algorithm must be stopped, False when it can continue its execution.
CancellationCallback getCancellationCallback() Returns a pointer or a reference to the cancellation callback function if it has been defined, null or none otherwise. 
float progress = 0.f;

// change the number of core used by imagedev. 0 means the maximum number of core.
if ( imagedev::getCpuNumber() > 0 )
  imagedev::setCpuNumber( 0 );

// Initialize the progress, cancellation, message and data callbacks
auto ratioCallback = [&]( const GenericAlgorithm&, float ratio ) {
  std::cout << "progress " << ratio << std::endl;
  progress = ratio;
};
auto dataCallback = []( const GenericAlgorithm&, const std::string& data, const std::string& encoding ) {
  std::cout << "new data (" << encoding << "): " << data << std::endl;
};
auto cancellationCallback = [&]( const GenericAlgorithm& ) {
  if ( progress > 0.5f )
  {
    std::cout << "Algorithm cancelled" << std::endl;
    return true;
  }
  return false;
};
imagedev::setProgressRatioCallback( ratioCallback );
imagedev::setProgressDataCallback( dataCallback );
imagedev::setCancellationCallback( cancellationCallback );


// Launch the elasticRegistration algorithm to see its progression
boost::filesystem::path autorad = getBaseImagePath( "autorad.tif" );
boost::filesystem::path autoradDist = getBaseImagePath( "autorad.distorted.tif" );

std::shared_ptr < iolink::ImageView > fixedImage = ioformat::readImage( autorad.string() );
std::shared_ptr < iolink::ImageView > movingImage = ioformat::readImage( autoradDist.string() );

imagedev::ElasticRegistration2d elasticRegistration2dAlgo;
elasticRegistration2dAlgo.setInputFixedImage( fixedImage );
elasticRegistration2dAlgo.setInputMovingImage( movingImage );
elasticRegistration2dAlgo.setMetricType(
    imagedev::ElasticRegistration2d::MetricType::MEAN_SQUARE_DIFFERENCE );
elasticRegistration2dAlgo.setTolerance( 0.025 );
elasticRegistration2dAlgo.setPyramidLevels( { 2, 0 } );
elasticRegistration2dAlgo.setElasticStandardDeviation( { 10.0, 10.0 } );
elasticRegistration2dAlgo.setFluidStandardDeviation( { 10.0, 10.0 } );

try
{
    elasticRegistration2dAlgo.execute();
}
catch ( imagedev::Exception& )
{
    std::cout << "The ElasticRegistration2d algorithm was cancelled." << std::endl;
}

// disable callbacks
imagedev::setProgressRatioCallback( nullptr );
imagedev::setProgressDataCallback( nullptr );
imagedev::setCancellationCallback( nullptr );
Method Description
set_verbose(enable) Sets default callbacks that print the name of which algorithm is starting, its progression, its execution time and manage cancellation.
  • enable: Enables callbacks if true, disables them otherwise.
get_verbose() Returns True if the verbose mode is enabled, False otherwise.
set_cpu_number(cpu_number) Activates a user-defined number of logical processors to be used by ImageDev algorithms.
Most of the ImageDev algorithms are CPU parallelized. However, if the computation time scales well with the CPU clock speed, it does not with the number of threads. Generally, using more than 8 threads is useless. For instance, a system with a 3.2 GHz, 8 threads processor configuration can run ImageDev algorithms faster than a system with 2.7 GHz and 32 threads.

This phenomenon is easy to explain. When processing an image in parallel, each selected logical processor computes a result for an image block. Once two contiguous blocks are processed, a fusion step is necessary to merge the results of these blocks. This step may be more or less complex depending on several parameters, such as:
  • The nature of the algorithm (point-wise operators require less fusion than fixed window filters, which require less fusion than propagation-based algorithms).
  • The number of logical processors used (the higher it is, the longer the fusion step takes).
  • The size of the blocks (this parameter is automatically managed by ImageDev).
On systems having more than 8 logical processors, it may be interesting to monitor the influence of the number of logical processors used on the execution time of a given recipe.
  • cpuNumber: The number of logical processors to be used. All processors are used if this value is lower than or equal to zero.
get_cpu_number() Returns the user-defined number of logical processors to be used by ImageDev algorithms. If the returned value is lower than or equal to zero, all processors are used.
set_progress_ratio_callback(progress_ratio_callback) Sets the ratio callback used to track the progression of algorithms.
  • progressRatioCallback: The progression ratio callback used to track the progression of algorithms. It must have two arguments:
    • A GenericAlgorithm object, which represents the algorithm being executed.
    • A float value representing the progression ratio between 0 and 1.
get_progress_ratio_callback() Returns a pointer or a reference to the ratio callback function if it has been defined, null or none otherwise.
set_progress_message_callback(progress_message_callback) Sets the message callback used to be notified about generic messages sent by algorithms.
  • progressMessageCallback: The progression message callback used to notify algorithm information. It must have two arguments:
    • A GenericAlgorithm object, which represents the algorithm being executed.
    • A string value representing the message sent by the algorithm.
get_progress_message_callback() Returns a pointer or a reference to the message callback function if it has been defined, null or none otherwise.
set_progress_data_callback(progress_data_callback) Sets the data callback used to be notified about formatted messages sent by algorithms.
  • progressDataCallback: The progression data callback used to notify algorithm information. It must have two arguments:
    • A GenericAlgorithm object, which represents the algorithm being executed.
    • A string value representing data sent by the algorithm.
    • A string value representing the encoding of data sent by the algorithm.
get_progress_data_callback() Returns a pointer or a reference to the data callback function if it has been defined, null or none otherwise.
set_cancellation_callback(cancellation_callback) Sets the cancellation callback that can be used to interrupt an algorithm before being completed.
  • CancellationCallback: The cancellation callback used to notify algorithm cancellation. It has one argument, a GenericAlgorithm object, which represents the algorithm being executed. This function has to return True when the algorithm must be stopped, False when it can continue its execution.
get_cancellation_callback() Returns a pointer or a reference to the cancellation callback function if it has been defined, null or none otherwise. 
progress = 0
def progress_callback(algo, ratio):
  progress = ratio
  print("Progress:" + str(ratio))

def data_callback(algo, data, encoding):
  print("Data (" + encoding + "):" + data)

def cancellation_callback(algo):
  if(progress > 0.5):
      print("Algorithm cancelled.")
      return True
  return False

# change the number of core used by imagedev. 0 means the maximum number of core.
if( imagedev.get_cpu_number() > 0 ):
  imagedev::setCpuNumber( 0 )

# Initialize the progress, cancellation, message and data callbacks
imagedev.set_progress_ratio_callback(progress_callback)
imagedev.set_progress_data_callback(data_callback)
imagedev.set_cancellation_callback(cancellation_callback)

# Launch the elasticRegistration algorithm to see its progression
fixedImage = ioformat.read_image(getBaseImagePath("autorad.tif"))
movingImage = ioformat.read_image(getBaseImagePath("autorad.distorted.tif"))

try:
  imagedev.elastic_registration_2d(input_fixed_image=fixedImage,
    input_moving_image=movingImage,
    metric_type=imagedev.ElasticRegistration2d.MetricType.MEAN_SQUARE_DIFFERENCE,
    tolerance=0.025,
    pyramid_levels=[2, 0],
    elastic_standard_deviation=[10.0, 10.0],
    fluid_standard_deviation=[10.0, 10.0])
except Exception as e:
    print("The ElasticRegistration2d algorithm was cancelled.")

# Disable callbacks
imagedev.set_progress_ratio_callback(None)
imagedev.set_progress_data_callback(None)
imagedev.set_cancellation_callback(None)
Method Description
public void SetVerbose(bool enable) Sets default callbacks that print the name of which algorithm is starting and its execution time.
  • enable: Enables callbacks if true, disables them otherwise.
public bool GetVerbose() Returns True if the verbose mode is enabled, False otherwise.
public void SetCpuNumber(int cpuNumber) Activates a user-defined number of logical processors to be used by ImageDev algorithms.
Most of the ImageDev algorithms are CPU parallelized. However, if the computation time scales well with the CPU clock speed, it does not with the number of threads. Generally, using more than 8 threads is useless. For instance, a system with a 3.2 GHz, 8 threads processor configuration can run ImageDev algorithms faster than a system with 2.7 GHz and 32 threads.

This phenomenon is easy to explain. When processing an image in parallel, each selected logical processor computes a result for an image block. Once two contiguous blocks are processed, a fusion step is necessary to merge the results of these blocks. This step may be more or less complex depending on several parameters, such as:
  • The nature of the algorithm (point-wise operators require less fusion than fixed window filters, which require less fusion than propagation-based algorithms).
  • The number of logical processors used (the higher it is, the longer the fusion step takes).
  • The size of the blocks (this parameter is automatically managed by ImageDev).
On systems having more than 8 logical processors, it may be interesting to monitor the influence of the number of logical processors used on the execution time of a given recipe.
  • cpuNumber: The number of logical processors to be used. All processors are used if this value is lower than or equal to zero.
public int GetCpuNumber() Returns the user-defined number of logical processors to be used by ImageDev algorithms. If the returned value is lower than or equal to zero, all processors are used.
public static void SetProgressRatioCallback(ProgressRatioCallback progressRatioCallback) Sets the ratio callback used to track the progression of algorithms.
  • progressRatioCallback: The progression ratio callback used to track the progression of algorithms. It must have two arguments:
    • A GenericAlgorithm object, which represents the algorithm being executed.
    • A float value representing the progression ratio between 0 and 1.
public static ProgressRatioCallback GetProgressRatioCallback() Returns a pointer or a reference to the ratio callback function if it has been defined, null or none otherwise.
public static void SetProgressMessageCallback(ProgressMessageCallback progressMessageCallback) Sets the message callback used to be notified about generic messages sent by algorithms.
  • progressMessageCallback: The progression message callback used to notify algorithm information. It must have two arguments:
    • A GenericAlgorithm object, which represents the algorithm being executed.
    • A string value representing the message sent by the algorithm.
public static ProgressMessageCallback GetProgressMessageCallback() Returns a pointer or a reference to the message callback function if it has been defined, null or none otherwise.
public static void SetProgressDataCallback(ProgressDataCallback progressDataCallback) Sets the data callback used to be notified about formatted messages sent by algorithms.
  • progressDataCallback: The progression data callback used to notify algorithm information. It must have two arguments:
    • A GenericAlgorithm object, which represents the algorithm being executed.
    • A string value representing data sent by the algorithm.
    • A string value representing the encoding of data sent by the algorithm.
public static ProgressDataCallback GetProgressDataCallback() Returns a pointer or a reference to the data callback function if it has been defined, null or none otherwise.
public static void SetCancellationCallback(CancellationCallback cancellationCallback) Sets the cancellation callback that can be used to interrupt an algorithm before being completed.
  • CancellationCallback: The cancellation callback used to notify algorithm cancellation. It has one argument, a GenericAlgorithm object, which represents the algorithm being executed. This function has to return True when the algorithm must be stopped, False when it can continue its execution.
public static CancellationCallback GetCancellationCallback() Returns a pointer or a reference to the cancellation callback function if it has been defined, null or none otherwise. 
float progress = 0;

// change the number of core used by imagedev. 0 means the maximum number of core.
if (ImageDev.Processing.GetCpuNumber() > 0)
  ImageDev.Processing.SetCpuNumber(0);

// Initialize the progress, cancellation, message and data callbacks
Processing.SetProgressRatioCallback(
  (algo, ratio) =>
  {
    Utilities.WriteInfoMsg("Progress: " + ratio);
    progress = ratio;
  }
);

Processing.SetCancellationCallback(
    (algo) =>
    {
        if (progress > 0.5f)
        {
            Console.WriteLine("Algorithm cancelled.");
            return true;
        }
        return false;
    }
);

// Check that callback are set
if (Processing.GetProgressRatioCallback() != null)
{
  Utilities.WriteInfoMsg("Progression callback is set.");
}

if (Processing.GetCancellationCallback() != null)
{
  Utilities.WriteInfoMsg("Cancellation callback is set.");
}

// Launch the elasticRegistration algorithm to see its progression
var fixedImage = IOFormat.ViewIO.ReadImage(GetBaseImagePath("autorad.tif")) as ImageView;
var movingImage = IOFormat.ViewIO.ReadImage(GetBaseImagePath("autorad.distorted.tif")) as ImageView;

ElasticRegistration2d elasticRegistration2dAlgo = new ElasticRegistration2d
{
  inputFixedImage = fixedImage,
  inputMovingImage = movingImage,
  metricType = ElasticRegistration2d.MetricType.MEAN_SQUARE_DIFFERENCE,
  tolerance = 0.025,
  pyramidLevels = new uint[] { 2, 0 },
  elasticStandardDeviation = new double[] { 10.0, 10.0 },
  fluidStandardDeviation = new double[] { 10.0, 10.0 }
};

try
{
    elasticRegistration2dAlgo.Execute();
}
catch
{
    Console.WriteLine("The ElasticRegistration2d algorithm was cancelled.");
}

// Disable callbacks
Processing.SetProgressRatioCallback(null);
Processing.SetCancellationCallback(null);