PCL Version 1.0.105 - Reference Documentation Preview

[Juan Conejero]

Hi all,

I have just uploaded a working preview of the reference documentation for version 1.0.105 of the PixInsight Class Library (PCL). This is the version we are using right now to build the PixInsight Core application version 1.8.0:

http://pixinsight.com/developer/pcl/doc/20120917/html/

This version is similar to the next public version of PCL, which will be the last one in the 1.0 cycle before the new open-source version 2.0.

Of special importance are the new Process, ProcessParameter and ProcessInstance classes. These classes implement intermodule communication for installed processes. In other words: these classes make it possible for a module to instantiate and execute any installed processes, just as this can be done with JavaScript scripts using the PixInsight JavaScript Runtime (PJSR).

If you want to take a look at the documentation for these classes and make any suggestions, now is the right moment to do so.

Enjoy!

Edited: Links updated for the latest PCL documentation snapshot on 2012/09/17

[georg.viehoever]

I like what i see. Could you give a piece of example code showing how it is intended to be used?
Georg

[Juan Conejero]

Sure. Here is a little example to execute a PixelMath instance:

Code: [Select]

#include <pcl/ProcessInstance.h>
#include <pcl/ErrorHandler.h>

namespace pcl
{

// ...

bool SubtractScaledBackground( const String& imageId, float k )
{
   try
   {
      /*
       * Get access to the view with the specified identifier
       */
      View view = View::ViewById( imageId );
      if ( view.IsNull() )
         throw Error( "No such view: " + imageId );

      /*
       * Get access to the PixelMath process. If PixelMath is not installed,
       * or if it cannot be accessed for some reason, this constructor throws
       * an Error exception.
       */
      Process PM( "PixelMath" );

      /*
       * Create a PixelMath instance
       */
      ProcessInstance pm( PM );
      if ( pm.IsNull() )
         throw Error( "Couldn't instantiate the PixelMath process" );

      /*
       * Set instance parameters
       */
      String expression = "$T - " + String().Format( "%.4f", k ) + "*$T_background";
      pm.SetParameterValue( expression, "expression" );
      pm.SetParameterValue( false, "rescale" );

      /*
       * Validate instance execution
       */
      String whyNot;
      if ( !pm.CanExecuteOn( view, whyNot ) )
         throw Error( "Cannot execute PixelMath instance on view \'" + imageId + "\'<br/>"
                      "Reason: " + whyNot );

      /*
       * Execute the instance.
       * On failure, PixelMath already throws a user-visible exception (as
       * every process in PixInsight), so we throw a CatchedException just to
       * jump to the exception handler.
       */
      if ( !pm.ExecuteOn( view ) )
         throw CatchedException();

      return true;
   }

   ERROR_HANDLER
   return false;
}

} // pcl

The calls to ProcessInstance::SetParameterValue() work because they implicitly instantiate the new pcl::Variant class (sorry, still not documented), which acts like a union to store instances of a variety of standard data types and PCL classes. Similarly, there is a ProcessInstance::ParameterValue() member function returning a Variant that allows you to access parameter values, including output parameters (properties) after execution of a process instance.

[georg.viehoever]

Minor: Maybe Process::Aliases() should return an IsoStringList, just as Categories()

[georg.viehoever]

When I compose a process from other processes, is it possible to get only one entry in the process history? Is it possible to undo the process in one step. I currently dont see interfaces for that.
Georg

[Juan Conejero]

Minor: Maybe Process::Aliases() should return an IsoStringList, just as Categories()

Good catch. I'll change it in Process and ProcessParameter.

[Juan Conejero]

When I compose a process from other processes, is it possible to get only one entry in the process history?

Yes. The ProcessInstance::ExecuteOn member function allows you to prevent generation of undo states (and hence history entries) by setting its swapFile parameter to false. You'll find more detailed information in the documentation for this function.

[georg.viehoever]

Just what i need. Thanks

[bitli]

Thanks for the preview,

My understanding is that it will be possible to access output parameters of a process (hopefully the process will provide the information currently in the console in the form of output paramters).

Will it be possible to get the list of images created and/or modified by the execution of a process?  Some process create images with their own id and, except by using hack in the caller like listing the content of workspace before and after a process, it is difficult for a driver process to know which images were created be the child process.

-- bitli

[Juan Conejero]

Hi Bitli,

access output parameters of a process

This is already possible (from long time ago). Processes such as ImageCalibration, ImageIntegration, StarAlignment, etc, provide read-only output parameters, also known as output properties. Output properties can already be accessed from JavaScript scripts, and since the next version of PCL, also from PCL-based modules. A good example is the BatchPreprocessing script, where we use output properties to coordinate the whole preprocessing pipeline.

Output properties are fully documented for processes such as ImageIntegration and StarAlignment (see the Scripting and Automation sections of the corresponding documents). The Object Browser window in version 1.7 (which is integrated with Script Editor), or the Object Explorer component in version 1.8, provide information on all process parameters, including output properties. You have this information also in Process Explorer when the Property Browser panel is selected.

[bitli]

Thanks.
I guess that I expected a generic way to find out all images created by a process (without a priori knowledge of the process). This was for use by VaryParams (or other generic driver scripts) which don't know a priori the result of a process. Some process (for example DBE for the background) may generate an image depending on some parameters.  I did not see an output parameter on DBE which would provide the name of the output image.
Currently I scan the workspace before and after running the process - this works quite well in practice but is a little bit fragile and hacky.
[Edit] In fact i get the list of all new images after process execution and I assume that the process selected the 'primary' image (the corrected image for example in case of DBE) and that the other images created are somewhat 'secondary' (the background in case of DBE)[end of edit]
-- bitli

[georg.viehoever]

http://pixinsight.com/developer/pcl/doc/20120901/html/ still displayes "PCL - PixInsight Class Library Version 1.0". You may want to update this to avoid confusion with the old version.

[Juan Conejero]

A new version of the reference documentation is now available for PCL 1.0.105:

http://pixinsight.com/developer/pcl/doc/20120917/html/

I have updated the main documentation page, including a brief introduction (thanks for the catch, Georg!). This version fixes lots of documentation bugs and includes full documentation for two new classes: AutoPointer and Variant. It also documents many aspects of the new PixInsight/PCL threading model: Thread, although it still contains some outdated information (e.g., nested parallelism is supported in PI 1.8).

[georg.viehoever]

I am preparing to develop a PCL module for the upcoming PI1.8. Questions:

• Will PCL modules developed for PI1.7.x require more than just a recompilation?
  
• Which is the recommended development platform for Linux and Windows (e.g. Fedora17-x64 with default gcc, Win7-x64 with VS2012)?
• Anything else we should know when developing on PI1.7 now, but releasing for PI1.8 later?

Georg