ReproduciblePI.js

/*
 * ReproduciblePI.js v1.0
 * (C) Sergio Diaz, sergiodiaz.eu, June 2021
 *
 * This script is a simple code generator to aid in PixInsight reproducibility.
 * The generated code is NOT complete, you'll have to tweak and extend it for a
 * fully working script (see CAVEATS below).
 *
 *
 * ____/ Scenario \_______________
 * You have finished your PixInsight project and have every step of your
 * processing workflow or pipeline as a process icon on the workspace. It
 * involves some masks and maybe other intermediate images, and each one has its
 * own process history. You have positioned each process icon in and orderly
 * manner on your workspace, maybe wrote some comments in the processes
 * descriptions, but you want to take a step further and develop a script to
 * describe unambiguously your pipeline.
 * Executing this tool will dump to the console a good start point for your
 * script. It will generate code for instantiating all views and processes in
 * the workspace, and it will try to derive a pipeline by looking at the history
 * of every view, with some limitations (sorry).
 * So you copy the code from the console and place it in a .js file or directly
 * in the Script Editor of PixInsight. At this point the code is not complete,
 * you'll have to review the generated comments and probably move or add some
 * lines (see below). But hopefully it will help to get you there faster.
 *
 * There are a few parameters to tweak the generated code, see "Global switches"
 * below.
 *
 *
 * ____/ CAVEATS \_______________
 * - Intermediate images, generated by processes (e.g., masks) cannot be
 * positioned by the script in the pipeline. The code generated to reference
 * those views is appended to the Views section, but you'll have to cut&paste
 * them to the correct location in the pipeline section. A TODO reminder is
 * added in the code.
 * - Only manually executed processes could be matched to processes in the
 * history container for the script to generate the pipeline.
 * As I couldn't find any direct connection between a process icon and its
 * counterpart in the history container, the scripts tries to match by
 * execution start time (see ProcessInstance.startJD()).
 * ProcessInstances instantiated by fromIcon() are clones, they "inherit"
 * the startJD values but they don't update them to the icon when executed.
 * With something like Process01.writeIcon("Process01"), the process
 * parameters can be updated, but not startJD (neither description).
 * So if you execute the generated script, history will no longer have
 * startJD values matching to the icons' startJD, then pipeline generation
 * couldn't be performed.
 *
 *
 * ____/ Global switches \_______________
 * - generateFileOpening:
 *   * true  => the generated code will load from disk every view that has an
 *              associated file path; the rest will be references (as below)
 *   * false => the generated code will instantiate the views in the workspace
 *              by reference
 *
 * - generateProcessSource:
 *   * true  => it will generate code to fully define every process and its
 *              parameters (like "Edit Instance Source Code..." on the process
 *              icon contextual menu).
 *   * false => the generated code will instantiate the process icons on the
 *              workspace (taking the parameter values from the icon).
 *
 * References:
 * [1] https://pixinsight.com/forum/index.php?threads/pjsr-any-access-to-the-history.6349/
 */

#feature-id    Utilities > ReproduciblePI

#feature-info  A simple code generator to aid in PixInsight reproducibility.


var generateFileOpening = false;
var generateProcessSource = false;


//#define __DEBUG__


// Generate code to reference all views
var viewArr = [];
Console.writeln("// ____/ Views \\________________\n");

if (generateFileOpening) {
   Console.writeln("function viewFromFile(filePath) {");
   // Assumes one image per file
   Console.writeln("\tvar window = ImageWindow.open('" + window.filePath + ")[0];");
   Console.writeln("\twindow.visible = true;");
   Console.writeln("\treturn window.mainView.id;");
   Console.writeln("}");
   Console.writeln();
}

Console.writeln("// TODO: ");
Console.writeln("// - Views generated by the pipeline must be declared there (cut and paste from here).");
Console.writeln("// - Views whose id has changed during the pipeline must be changed below (use the original id).\n");
for (window of ImageWindow.windows) {
   var viewId = window.mainView.id;

   Console.writeln("// " + viewId + ": " + window.filePath);

   if (generateFileOpening && window.filePath) {
      Console.writeln("var " + viewId + " = viewFromFile(" + window.filePath + ");");
   } else {
      Console.writeln("var " + viewId + " = View.viewById(\"" + viewId + "\");")
   }

   viewArr.push(viewId);
}
Console.writeln();
Console.writeln();


// Generate code to instantiate all process icons on the workspace
Console.writeln("// ____/ Process Icons \\________________\n");

// Aux function to sort process instances by start time (startJD)
function compareJD(id1, id2) {
   pi1JD = ProcessInstance.fromIcon(id1).startJD();
   pi2JD = ProcessInstance.fromIcon(id2).startJD();
   return pi1JD > pi2JD;
}

var processMap = {}; // dictionary that maps startJD -> processId // TODO: startJD=0??
var icons = ProcessInstance.icons(); // .icons() follows instantiation order
icons.sort(compareJD); // sorts by ascending startJD
for (iconId of icons) {
   processInstance = ProcessInstance.fromIcon(iconId);

   // Process type and description as comment
   Console.write("// " + processInstance.constructor.name);
   //Console.write(", " + processInstance.startJD());
   if (processInstance.description()) {
      Console.write(" [" + processInstance.description() + "]");
   }
   Console.writeln();

   if (generateProcessSource) {
      Console.writeln(processInstance.toSource("JavaScript", iconId));
   } else {
      Console.write("var " + iconId + " = ProcessInstance.fromIcon(\"" + iconId + "\");");
   }

   Console.writeln();

   processMap[processInstance.startJD()] = iconId;
}
Console.writeln();
Console.writeln();


#ifdef __DEBUG__
Console.writeln("viewArr:\n" + JSON.stringify(viewArr));
Console.writeln("processMap:\n" + JSON.stringify(processMap));
#endif


// Aux function that gets info about the i-th step of a ProcessContainer
function getProcessingStep(processContainer, i, viewId) {
   var processInstance = processContainer.at(i);
   var startJD = processInstance.startJD();
   var iconId = processMap[startJD]; //processInstance.processId();
   var maskId = historyProcessContainer.maskId(i);
   var maskInv = historyProcessContainer.maskInverted(i);

   var step = {
      "startJD": startJD,
      "viewId": viewId,
      "iconId": iconId,
      "maskId": maskId,
      "maskInv": maskInv
   };

   return step;
}


// Generate global history, iterating over all views
var globalHistoryArr = [];
for (viewId of viewArr) {
   //Console.writeln(viewId);
   var view = View.viewById(viewId);

   // View's initial state
   var initStateProcessContainer = view.initialProcessing;
   // Record each step to create the view, if any
   for (let i = 0; i < initStateProcessContainer.length; i++) {
      step = getProcessingStep(initStateProcessContainer, i, "UNDEFINED");
      globalHistoryArr.push(step);
   }

   // View's history
   var historyProcessContainer = view.processing;
   // Record each step in view's history
   for (let i = 0; i < view.historyIndex; i++) {
      step = getProcessingStep(historyProcessContainer, i, viewId);
      globalHistoryArr.push(step);
   }
}

// Sort global history by process start time
globalHistoryArr.sort( (step1, step2) => (step1.startJD > step2.startJD) );

#ifdef __DEBUG__
Console.writeln("globalHistoryArr:\n" + JSON.stringify(globalHistoryArr));
#endif


Console.writeln("// ____/ Pipeline \\________________\n");

Console.writeln();
Console.writeln("function pipeline() {");

for (step of globalHistoryArr) {
   // Step summary as comment
   Console.writeln(
      "\t// " + step.iconId + "( " + step.viewId + " )  " +
      (step.maskId? "[ " + (step.maskInv? "~":" ") + step.maskId + " ]": "")
   );

   if (step.maskId) {
      // Apply mask [inverted]: <view>.window.setMask(<mask>.window[, true]);
      Console.writeln("\t" + step.viewId + ".window.setMask(" + step.maskId + ".window" + (step.maskInv? ", true": "") + ");");
   }

   // Apply process on view: <process>.executeOn(<view>); (view target context)
   Console.writeln("\t" + step.iconId + ".executeOn(" + step.viewId + ");");

   if (step.maskId) {
      // Remove mask: <view>.window.removeMask();
      Console.writeln("\t" + step.viewId + ".window.removeMask();");
      // TODO: omit if next step involves same view, same mask
   }

   Console.writeln();
}

Console.writeln("}");

Console.writeln();
Console.writeln();

Console.writeln("pipeline();\n");