English Español Français

Getting started with PixInsight

by Enzo De Bernardini and Alejandro Tombolini


This article will attempt to provide a start guide to begin using the processing image platform PixInsight from the first and most basic steps, aimed to newbie users. The purpose of this guide is to show easily the most important concepts related to the use of the interface, which once learned will allow confidently advance in the use of the different processing tools.

If you do not have your PixInsight license yet, you can purchase it on the official site or request a trial license. We also recommend participating in PixInsight Forum.

Open an Image

There are several ways to open an image:

Once opened the image it will have assigned an unique identifier within the application (ID) which appears next to the file name in the title bar of the window. This identifier can be edited (see Set Image Identifier). The title bar of the image window is also shared by other data: channels (eg: RGB) and zoom level (eg: 1:1 = 100%). In turn, each image window has in his left side a view selector where is always first the main view (the main image) and then underneath, the previews that were created.

Image title bar

Zoom Mode / Pan Mode

Two basic functions to examine a picture are zoom and pan. There are several ways to zoom the image, being the most simple rotate the mouse wheel forward to zoom out and backward to zoom in. Note how zoom factor change in the title bar of the image window. In zoom tool bar can be found other ways to change it and also keyboard shortcuts:

  • Zoom In  CTRL + +
  • Zoom Out  CTRL + -
  • Zoom 1:1  CTRL + 1

Pan (image shift), can be activated from Tool Bar Mode or using the keyboard shortcut ALT+P. Once activated, by clicking and dragging you can scroll the image without using the scroll bars of the window.  Another practical option is to use the button on the mouse wheel if your mouse has it. Pressing the wheel (without turning) momentary switches to Pan Mode while holding. Moving the mouse-click wheel can move the image. A keyboard shortcut that can also be useful is to press the spacebar: it switches to Pan Mode while you hold down the spacebar, allowing clicking and dragging with the mouse.

 See how to clone pan and zoom from one image to other.


The previews are fundamentals elements in the use of PixInsight. They can be created in the desired number being always size boxes at choice (even covering the entire picture if necessary) and located where required within the image window. The fastest and easiest way to create a preview is to use the New Preview Mode tool New Preview located in the Preview toolbar (see Tool Bar - Preview if disabled), and always from the main view of the image draw a rectangle in the desired size clicking, holding and dragging, and then releasing the button.

The generated preview will join the view selector with its own ID. Click on the appropriate preview view to access it. Immediately after generating a preview the tool changes to edit mode and may (always from the main view) change the size and position by dragging the rectangle and moving edges or corners.

See video tutorials related to previews.

Process Console

The Process Console is always present and visible with each applied process or script. It is the place where processes will return data about the execution thereof. In turn can be entered by writing different commands, from the simple ones (eg: clear and then ENTER to clean it) to others more complex (see Command Line Interface). It is a browser window that will open each time a process or script is applied. At first the data may be somewhat disconcerting, but with practice many of them will be good reference.

Process Console

In the bottom of the console is the Pause/Abort button that when pressed during the execution of a process, interrupt its task and warn the user about the termination of the process.


The process modules can be found in Process Explorer browser window (the most frequently used) and in the Process menu. There are nodes grouped into process families, and these nodes can be expanded and collapsed. There are also included two special nodes: One of favorites (Favorites, where can be added the most used processes) and another where all processes (All Processes) are listed.

To open a process window double click on the name or icon. Process windows share many features in its lower part, where there are located icons with different functions. Several of these icons are always present in all processes, while others are just in a few. The following example shows the bottom of the window HistogramTransformation process (HT).

process windows icons

Icons Description:

  1. New Instance
  2. Apply
  3. Real-Time Preview
  4. Edit Instance Source Code
  5. Browse Documentation
  6. Track-View
  7. Reset

Apply Processes

A long list of processes (HistogramTransformation, CurvesTransformation, etc.) can be applied directly on the main image or preview by dragging and dropping the instance icon (blue triangle) on the target image or preview, or by pressing Apply (F5) to apply on the active view.

When applying a process on a preview changes can be displayed instantly (between the original and the new state) using the Undo Preview Undo Preview / Redo Preview Redo Preview button on the Preview Tool bar. This allows to compare the results immediately. Note that the same button changes from one state to another and consecutive clicks show the before and after application of the process on the preview.

The previews are volatile: if not specified otherwise, the result of a process applied to a preview is eliminated by applying any process to the same preview again. The previews always take as reference the data of the main view (the image data). Two consecutive applications of a process on the same preview will result in only the application of the latter process, eliminating the results of applying the first.

Instance Icons Creation

Setting in process modules can be saved as instance icons, dragging the blue triangle (New Instance) to a blank area of ​​the workspace. This icons will save all the data so that when re-open (double click on the icon) the process window will open and load the data stored in the icon. This procedure is one of the most commonly used in the processing environment PixInsight, being extremely useful. It is possible in that way to experiment with various configurations and generate icons of the best settings for the current process allowing then to reload or apply to another image or preview the one selected, among other uses.

To apply a process contained in an instance icon over an image or preview, simply drag and drop the icon on the target image or preview.

Instance icons can be renamed, deleted and organized, between other things.


The scripts are programs that when run apply different processes or functions. Many of these programs were written by PixInsight users using the Script Editor included in the platform, which provides different facilities to write the code.

The scripts can be found in the Script menu grouped by functionality (Batch Processing, Image Analysis, Utilities, etc.), and within the Process Explorer in the Scripts node.

There are many scripts of different features available. One of the most important is BatchPreprocessing (BPP) located within the category Batch Processing, which automates the tasks of preprocessing (generation of master of calibration, calibration, alignment, deBayer and integration).

See also BPP videos and others video tutorials related to scripts

ScreenTransferFunction (STF)

Many times a preprocessed astronomical image has much of the information compressed into a small portion of the histogram, and in turn a number of processes should be applied in this state, when the image has not been stretched yet (linear). To display the information of the image without affecting its actual values ​​(for practical visualization purposes only) there exist ScreenTransferFunction (STF) tool.


Usually begins with an automatic application (Auto SFT, Auto Stretch, CTRL + A) which can be linked-channels (the same transformation is applied to all channels) or unlinked-channel (independent transformation will be applied to each channel) when enable/disable the Link RGB Channels icon (Link Channels). You can make manual adjustments to the transformation by dragging any of the three triangular controls. If the channels are linked, simultaneously will move the corresponding to each of them.

To activate/deactivate STF press the F12 key or use the icon on the tool STF Disabled. As with all processes, to return to the default values ​​(in the case of the STF is no change in image display) press the corresponding button to reset Reset.

As shown in the following video, the ScreenTransferFunction toolbar also allows operate with many of the functions of the module.

Remember that ScreenTransferFunction only changes the visualization of the image and does not change the values ​​on it (does not affect the values ​​of the pixels, just the way it is displayed). For example, if the image is saved with STF applied it will save without reflecting the image being viewed (and probably appear very dark). If desired it is possible to transfer STF values ​​to HistogramTransformation tool.


Mask have the functionality of protection of certain areas of an image. Tipically a mask is a gray scale image, where a pixel value of 1 (white) represent a point where a process will be applied completely, and a pixel value of 0 (black) represent a point where the process will not be applied. In the intermediate pixel values between 1 and 0 the applied process will have intermediate result. An example of using mask is the protection of background or stars.

You can generate a typical luminance mask extracting the CIE L* component of an image using the button Extract CIE L* Component CIE L* from the Image tool bar. The generated image (in gray scale) can be procesed (for instance utilizing HistogramTransformation tool) to adjust it to the needs of the image to be protected.

To apply a mask over an image in PixInsight, the image and the mask must have the same dimensions, otherwise will be incompatible. There are several ways to apply a mask:

  • Menu Mask › Select Mask, with the main image active.
  • Keyboard shortcut CTRL + M, with the main image active.
  • Button Select Mask Select Mask in Mask toolbar.
  • Drag the image identifier and drop it on the view selector in the main image. The following video shows the procedure, which is usually the most convenient and the most used.

Note that the image identifier of the main image changes color when there is an active mask applied.

Mask have different states that can be controlled from the Mask toolbar:

  • Invert Mask SHIFT + CTRL + I Invert Mask - Invert the application of the mask, which is equivalent to invert the values of the image of the mask. Does not change the image of the mask, only reverses the results when using a process.
  • Enable/Disable Mask SHIFT + CTRL + M Enable/Disable Mask- Enable and disable the mask (not the split with the main image, only activate or deactivate its effect). Note that the color of the image identifier switches when activate and deactivate the mask.
  • Show Mask CTRL + K Show Mask - Shows and hides the visualization of the mask on the main image. The mask is shown on the image to view the areas to be protected (the default mask color is red -it is just an arbitrary reference color-, but can be changed from the  toolbar Mask Rendering Mode or from Mask › Rendering Mode menu).

Note that the mask can be active and be hidden (not visible but having effect), or be inactive and be visible (visible, but have no effect). The status Enable/Disable Mask and Show Mask are independent. Visualize the status of the buttons in the toolbar (active/inactive) and the color in the image identifier which indicate if the mask is active.

To remove a mask (unlink the main picture image from the mask image) can be used the button Remove Mask Remove Mask from the Mask toolbar, or the menu option Mask › Remove Mask.

See video tutorials related to masks.


PixInsight can create projects, which keep the complete state of all images, previews, instance icons and processes, including their processing histories. The entire state is saved so it can be taken up at another time, a feature very useful to freeze processing tasks and continue them later.

Save Project SHIFT + CTRL + J Save Project - A window where you should select a name and destination for the project opens. You can specify the name of the author (Author) and descriptive text (Description). Additional options can be configured, but usually the default fulfill the required needs. Saved projects are divided into two main parts: the project file (.xosm) and a folder (same name) with the contents. If you wish to carry the project should be saved both the file and the folder. See video.

Load Project CTRL + J Load Project - A window file browser to locate and open the project file (.xosm) opens. It may take some time to load. See video.

Note that, depending on the processing performed, the project files can take a significant amount of disk space (in the order of several gigabytes).

See Video tutorials related to projects.


Last Update: 03/05/2014 16:05 UT

English Español Français