Preview Data and Functions
In this document we'll describe the set of data items and functions that characterize the previewing system implemented in PixInsight. Most of a preview's flexibility and usefulness are given by these data and functions, so you should gain some fluency with them in order to benefit from preview objects.
Here we focus attention on those functions directly involved in the process previewing mechanism. You may want to see other sections dedicated to more general, interactive preview operations such as creating/deleting previews and moving/resizing/selecting previews, and also to some miscellaneous preview operations.
Basic preview functions include many procedures available to try out processes on preview objects, as well as a useful system to undo and redo previewed processes.
More advanced preview operations are the preview storage functions, which include the Store, Restore and Reset preview functions. Storage functions give you tight control on how and when preview subimages are generated. By storing previews, you can accumulate processes on them. This way you may not just try out individual processes on a preview, but sequences of them to experiment with different processing strategies.
The following data structures, owned by preview objects in PixInsight, are relevant to the preview functions discussed in this document:
This is where previewing takes place, and is usually referred to as just the preview's subimage. When you preview a process, you actually apply a process instance to a preview's temporary subimage. The temporary subimage is also what is shown on the screen and what you can obtain readouts, histograms and statistics from.
This second subimage is optional; it's up to you when to generate it. As we'll see later on this document, when you store a preview, you are actually generating the preview's stored subimage as a copy of its current temporary subimage. So, in other words, a stored subimage is just a copy of a preview's temporary subimage as it was at a given moment.
These are generated dynamically. Auxiliary subimages include those automatically generated to support undo/redo operations, and subimages used to speed up previews by saving partial processing results. The user has actually no way to gain direct control over auxiliary subimages in PixInsight LE 1.0.
This is simply a copy of the last process instance executed (previewed) on the preview object, if any. As you'll see, a preview's last process can be undone and redone, just as you are used to do with documents in most applications.
Each view in PixInsight has its own associated processing history object. A processing history is a data container storing all of the processes that have been applied to a view in chronological order. As you might do with an image view's processing history, you can reuse a preview's processing history to apply it to images, to other previews, and to store and edit it as an independent container.
A preview's processing history is permanently synchronized with the preview's subimages. The preview's processing history includes the processes that have been applied to the preview to achieve the current state of its temporary subimage.
Processing histories are crucial in PixInsight and will deserve a specific documentation chapter.
Keeping the above data items in mind, we can see now the different preview functions available to the user in PixInsight LE 1.0.
When you try a process on a preview object in PixInsight, the preview's temporary subimage is initialized with a copy of the stored subimage, if the preview has been stored, or its pixels are read from the original image view if it hasn't. Then the process instance is executed for the preview's temporary subimage, and a copy of it is kept as an account of the last previewed process.
Previews are intrinsically temporary objects in PixInsight: successive preview operations will cause the previous state of the temporary subimage and the last process to be replaced with new data before executing a new process instance.
With the Undo Preview operation you can change quickly between a preview's current and previous state. This is very useful to verify how a process or sequence of processes actually performs by comparison with the original image.
To support the undo/redo mechanism for previews, auxiliary subimages and copies of processes are generated on the fly to store undone preview data.
The Redo and Undo Preview operations are complementary each other. Redo simply reverts to a previously undone operation.
When you store a preview, mainly two things happen. Firstly, the current temporary subimage is copied to the stored subimage, which is created if it didn't exist yet. Second, if a process had been applied to the preview, it is appended to the preview's processing history.
You know when a preview has been stored because the Information tool bar says that if the preview is the active current view. For example, you might see something like that for a stored preview:
In the default tool bar configuration, The Information tool bar is visible on the bottom control bar. You can make this tool bar visible at any moment through.
When you restore a preview, you are leaving it in the state it was before the last process was executed on it. Restore is similar to Undo, except no way exists to revert a Restore operation, as Redo does for Undo. Restore is a sort of eraser for the last previewed process.
Note that if no stored subimage exists for the preview, Restore uses a fresh subimage extracted from the original image view to update the preview's temporary subimage. In this case, Restore and Reset are equivalent operations.
Reset destroys all of the information generated for a preview and reloads a fresh subimage from its parent image view. Destroyed data includes existing stored and auxiliary subimages as well as the processing history and the last executed process. After Reset, a preview is left as if it had been just created.
Most preview operations can be easily performed through tool buttons, menu items, or keyboard shortcuts, as described in the following subsections.
However, there is actually no single, easy to explain way to preview processes in PixInsight, but many and sophisticated ways. This topic is covered in documentation sections dedicated to processes. In addition, at this point you might want to read an introductory document on how to use preview objects.
In general, preview functions are enabled only if you have at least a preview defined in the active image window. Preview functions apply to the active image window's selected preview or to the current view if it corresponds to a preview.