High-level interface to a PixInsight view object. More...
#include <View.h>
Inheritance diagram for pcl::View:
Public Types | |
| using | stf_list = Array< HistogramTransformation > |
Public Member Functions | |
| View ()=default | |
| View (const View &v) | |
| ~View () override | |
| void | AddToDynamicTargets () |
| bool | AreScreenTransferFunctionsEnabled () const |
| Rect | Bounds () const |
| bool | CanRead () const |
| bool | CanWrite () const |
| template<class S > | |
| Variant | ComputeOrFetchProperty (const S &property, bool notify=true) |
| Variant | ComputeProperty (const IsoString &property, bool notify=true) |
| void | DeleteProperty (const IsoString &property, bool notify=true) |
| void | DeletePropertyIfExists (const IsoString &property, bool notify=true) |
| void | DestroyScreenTransferFunctions (bool notify=true) |
| void | DisableScreenTransferFunctions (bool disable=true, bool notify=true) |
| void | EnableScreenTransferFunctions (bool=true, bool notify=true) |
| IsoString | FullId () const |
| ImageVariant | GetImage () const |
| void | GetScreenTransferFunctions (stf_list &) const |
| void | GetSize (int &width, int &height) const |
| bool | HasProperty (const IsoString &property) const |
| int | Height () const |
| IsoString | Id () const |
| ImageVariant | Image () const |
| bool | IsColor () const |
| bool | IsCompletePreview () const |
| bool | IsDynamicTarget () const |
| bool | IsMainView () const |
| bool | IsPartialPreview () const |
| bool | IsPreview () const |
| bool | IsStoredPreview () const |
| bool | IsVolatilePreview () const |
| void | Lock (bool notify=true) const |
| void | LockForWrite (bool notify=true) const |
| PropertyArray | PermanentProperties () const |
| PropertyArray | Properties () const |
| ViewPropertyAttributes | PropertyAttributes (const IsoString &property) const |
| PropertyDescriptionArray | PropertyDescriptions () const |
| Variant::data_type | PropertyType (const IsoString &property) const |
| Variant | PropertyValue (const IsoString &property) const |
| void | RelockForRead (bool notify=true) const |
| void | RemoveFromDynamicTargets () |
| void | Rename (const IsoString &newId) |
| void | SetProperties (const PropertyArray &properties, bool notify=true, ViewPropertyAttributes attributes=ViewPropertyAttribute::NoChange) |
| void | SetPropertyAttributes (const IsoString &property, ViewPropertyAttributes attributes, bool notify=true) |
| void | SetPropertyValue (const IsoString &property, const Variant &value, bool notify=true, ViewPropertyAttributes attributes=ViewPropertyAttribute::NoChange) |
| void | SetScreenTransferFunctions (const stf_list &, bool notify=true) |
| void | SetStorablePermanentProperties (const PropertyArray &properties, bool notify=true) |
| void | SetStorablePermanentPropertyValue (const IsoString &property, const Variant &value, bool notify=true) |
| void | SetStorableProperties (const PropertyArray &properties, bool notify=true) |
| void | SetStorablePropertyValue (const IsoString &property, const Variant &value, bool notify=true) |
| PropertyArray | StorablePermanentProperties () const |
| PropertyArray | StorableProperties () const |
| void | Unlock (bool notify=true) const |
| void | UnlockForRead (bool notify=true) const |
| int | Width () const |
| ImageWindow | Window () const |
| Public Member Functions inherited from pcl::UIObject | |
| virtual | ~UIObject () noexcept(false) |
| virtual void | EnsureUnique () |
| bool | IsAlias () const |
| bool | IsGarbage () const |
| bool | IsNull () const |
| bool | IsSameObject (const UIObject &o) const |
| bool | IsUnique () const |
| String | ObjectId () const |
| IsoString | ObjectType () const |
| bool | operator< (const UIObject &o) const |
| bool | operator== (const UIObject &o) const |
| size_type | RefCount () const |
| void | SetObjectId (const String &id) |
Static Public Member Functions | |
| static Array< View > | AllPreviews () |
| static Array< View > | AllViews (bool excludePreviews=false) |
| static bool | IsReservedViewPropertyId (const IsoString &id) |
| template<class S > | |
| static bool | IsValidViewId (const S &id) |
| static View & | Null () |
| static View | ViewById (const IsoString &fullId) |
| Static Public Member Functions inherited from pcl::UIObject | |
| static UIObject & | Null () |
Additional Inherited Members | |
| Protected Member Functions inherited from pcl::UIObject | |
| UIObject ()=default | |
| UIObject (const UIObject &x) | |
| UIObject (UIObject &&x) | |
| UIObject & | operator= (const UIObject &x) |
| UIObject & | operator= (UIObject &&x) |
Detailed Description
Instances of View are managed aliases of actual view objects in the PixInsight core application. Views are the main image holders in the PixInsight platform.
Views can be main views or previews. A main view holds the entire image of an image window. A preview is a volatile subimage defined on an image window. In all respects, both types of views can be manipulated transparently with the abstract interface provided by the View class. The View::IsPreview() and View::IsMainView() members inform you about the particular type of a given View object.
Each view has a unique identifier, which you can get and set through the View::Id(), View::FullId(), and View::Rename() member functions.
View::Image() gives you full access to the image in a view as an ImageVariant object.
Each view in PixInsight holds a set of histograms and statistical data as shared resources that can be accessed by all installed processes and interfaces. The View::CalculateHistograms() and View::CalculateStatistics() families of member functions give full access to these shared resources.
In a similar way, each view maintains a set of histogram transformations used as screen transfer functions (STF). A STF is applied to modify the screen representation of an image, without altering actual image data. The View::GetScreenTransferFunctions() / View::SetScreenTransferFunctions() family of functions allow you to acquire and modify the STF of any view.
The View::Lock() / View::Unlock() family of functions allow you to write thread-safe processing routines in current and future PixInsight multithreaded environments.
Finally, the static functions View::ViewById(), View::AllViews() and View::AllPreviews() provide for global searching and listing of existing view objects.
- See also
- ImageWindow
Member Typedef Documentation
◆ stf_list
A container of HistogramTransformation instances used to represent the managed Screen Transfer Functions (STF) of a view object in the core PixInsight application.
Constructor & Destructor Documentation
◆ View() [1/2]
|
default |
Constructs a null view. A null view does not correspond to an existing view in the PixInsight core application.
◆ View() [2/2]
|
inline |
Constructs a View instance as an alias of an existing View object.
- Note
- It cannot be overemphasized that this constructor does not create a new view. It only creates an alias object for an existing view in the calling module. In all respects, the alias and aliased objects are completely interchangeable; they behave exactly in the same way because both refer to the same server-side object.
◆ ~View()
|
inlineoverride |
Member Function Documentation
◆ AddToDynamicTargets()
| void pcl::View::AddToDynamicTargets | ( | ) |
Adds this view to the list of targets of the current active dynamic interface.
Dynamic interfaces call this function for views that get involved in active dynamic procedures. For example, the DynamicCrop interface calls this function when you select a view by defining an initial cropping rectangle with the mouse.
Any images selected as dynamic targets cannot be closed or modified in any way while an active dynamic interface depends on them.
If you implement a dynamic interface, always call this function for a view if your dynamic interface depends on it. Failing to do so will lead to unstable and incoherent behavior of the core application's GUI.
- Warning
- Once your dynamic interface ceases depending on this view, call the RemoveFromDynamicTargets() function for it.
◆ AllPreviews()
Returns a container with the existing previews. Main views are excluded.
◆ AllViews()
Returns a container with all the existing views. This includes all main views and previews.
◆ AreScreenTransferFunctionsEnabled()
| bool pcl::View::AreScreenTransferFunctionsEnabled | ( | ) | const |
Returns true iff screen transfer functions (STF) are enabled for this view. If STFs are disabled, they are not used for screen renditions.
◆ Bounds()
|
inline |
◆ CanRead()
| bool pcl::View::CanRead | ( | ) | const |
Returns true iff this view is not locked for reading.
◆ CanWrite()
| bool pcl::View::CanWrite | ( | ) | const |
Returns true iff this view is not locked for writing.
◆ DestroyScreenTransferFunctions()
| void pcl::View::DestroyScreenTransferFunctions | ( | bool | notify = true | ) |
Destroys the screen transfer functions (STF) for this view.
◆ DisableScreenTransferFunctions()
|
inline |
◆ EnableScreenTransferFunctions()
| void pcl::View::EnableScreenTransferFunctions | ( | bool | = true, |
| bool | notify = true |
||
| ) |
Enables or disables screen transfer functions (STF) for this view. If STFs are enabled, each non-identity STF is used to modify screen renditions of the corresponding image channel.
◆ FullId()
| IsoString pcl::View::FullId | ( | ) | const |
Returns the full identifier of this view.
If this is a main view, this function returns its identifier, which is the same string returned by the Id() member function.
If this view corresponds to a preview, this function returns a unique identifier of the form:
<image_id>-><id>
where <image_id> is the identifier of the preview's parent image, and <id> is the identifier of the preview. The "->" sequence is the scope resolution operator, used to specify pertenence of a preview to its parent image in the PixInsight environment.
◆ GetImage()
|
inline |
Returns an ImageVariant instance that transports the image in this view.
- Deprecated:
- Use View::Image() in newly produced code.
◆ GetScreenTransferFunctions()
| void pcl::View::GetScreenTransferFunctions | ( | stf_list & | ) | const |
Retrieves the set of screen transfer functions (STF) for this view in the specified container.
The STF container is a dynamic array. Each array element is a HistogramTransformation object corresponding to the STF for an image channel or color component:
Array element #0 = Red/gray channels
Array element #1 = Green channel
Array element #2 = Blue channel
Array element #3 = Lightness/brightness/luminance components
◆ GetSize()
| void pcl::View::GetSize | ( | int & | width, |
| int & | height | ||
| ) | const |
Copies the width and height in pixels of the image in this view to the specified variables.
◆ Height()
|
inline |
◆ Id()
| IsoString pcl::View::Id | ( | ) | const |
Returns the identifier of this view.
View identifiers are unique within their naming context. Identifiers of main views are unique in the global context, since each main view holds an image in the core application. The identifier of a preview is unique in the context of its parent image window.
◆ Image()
| ImageVariant pcl::View::Image | ( | ) | const |
Returns an ImageVariant instance that transports the image in this view.
The returned ImageVariant object transports a shared image. A shared image is a managed alias for an actual image living in the core PixInsight application. This is because a view is also a managed object.
With this function you gain access to the image in a view, which is crucial to perform any kind of processing in the PixInsight/PCL framework.
Before calling this function, however, you must make sure that your processing thread has the appropriate access rights to the view, since PixInsight is a multithreaded environment. This is done by calling the Lock() member function of View.
◆ IsColor()
| bool pcl::View::IsColor | ( | ) | const |
Returns true iff this view holds a color image, false if it is a grayscale image.
◆ IsCompletePreview()
| bool pcl::View::IsCompletePreview | ( | ) | const |
Returns true iff this view is a preview and it covers its parent main view completely.
◆ IsDynamicTarget()
| bool pcl::View::IsDynamicTarget | ( | ) | const |
Returns true iff this view has been selected as a target of an active dynamic interface.
◆ IsMainView()
| bool pcl::View::IsMainView | ( | ) | const |
Returns true iff this is a main view. A main view holds the entire image in an image window.
◆ IsPartialPreview()
| bool pcl::View::IsPartialPreview | ( | ) | const |
Returns true iff this view is a preview and it does not cover its parent main view completely.
◆ IsPreview()
| bool pcl::View::IsPreview | ( | ) | const |
Returns true iff this view corresponds to a preview object. A preview is a volatile subimage defined in an image window.
◆ IsStoredPreview()
| bool pcl::View::IsStoredPreview | ( | ) | const |
Returns true iff this view is a preview and has one or more stored states. When a preview has been stored, it behaves as an independent image with its own processing history. A stored preview does not rely on its mother image to return to a 'base' state.
◆ IsValidViewId()
|
inlinestatic |
◆ IsVolatilePreview()
| bool pcl::View::IsVolatilePreview | ( | ) | const |
Returns true iff this view is a preview and is in volatile state. A volatile preview contains a temporary image that can be undone/redone with the Preview > Undo and Preview > Redo core application commands.
◆ Lock()
| void pcl::View::Lock | ( | bool | notify = true | ) | const |
Locks this view for read and write operations.
Processes usually call this function to make sure that a target view's image cannot be modified by another thread while they are processing it. This is necessary because PixInsight is a multithreaded environment. If a process modifies an image without locking it, other processing threads could try to read or write the same pixels concurrently, with unpredictable results.
If the view is not currently locked by other processing thread, this function locks it and returns immediately. If the view is already locked, this function waits until it becomes unlocked by other threads.
If the notify argument is false, this function will not send ViewLocked() notifications to process interfaces.
- Warning
- Always make sure that you unlock a view that you have previously locked. If your processing routines leave views locked incorrectly, they'll cause serious problems. A locked view is inaccessible to other processes, and even the user may be unable to recover locked image data.
◆ LockForWrite()
| void pcl::View::LockForWrite | ( | bool | notify = true | ) | const |
Locks this view for write operations only.
Call this function if you need to make sure that a view's image will not be modified by other threads, but your processing routines will not modify it.
For example, if your routines need reading this view's image as source data for your processing tasks, but not writing to it, you should call this function instead of Lock(). In this way you allow other processes (including the core application's GUI) to access this view and its image for read-only operations. This improves efficiency and useability of the whole PixInsight environment.
◆ Null()
|
static |
Returns a reference to a null View instance. A null View does not correspond to an existing view in the PixInsight core application.
Referenced by pcl::AutoViewLock::~AutoViewLock().
◆ RelockForRead()
| void pcl::View::RelockForRead | ( | bool | notify = true | ) | const |
Relocks a view for reading (after UnlockForRead()).
Call this function after UnlockForRead(), if necessary. Please read the information given for that function.
◆ RemoveFromDynamicTargets()
| void pcl::View::RemoveFromDynamicTargets | ( | ) |
Removes this view from the list of targets of the current active dynamic interface.
Call this function when your dynamic interface no longer depends on this view. Please read the important information given for AddToDynamicTargets().
◆ Rename()
| void pcl::View::Rename | ( | const IsoString & | newId | ) |
Changes the identifier of this view to newId.
If newId is not unique in the naming context of this view, a unique identifier is obtained automatically by appending a suffix string to the specified newId string.
After calling this function, a ImageRenamed() notification message will be sent to all process interfaces.
◆ SetScreenTransferFunctions()
| void pcl::View::SetScreenTransferFunctions | ( | const stf_list & | , |
| bool | notify = true |
||
| ) |
Sets the screen transfer functions (STF) for this view.
The specified container is a dynamic array. Each array element is a HistogramTransformation object corresponding to the STF for an image channel or color component:
Array element #0 = Red/gray channels
Array element #1 = Green channel
Array element #2 = Blue channel
Array element #3 = Lightness/brightness/luminance components
◆ Unlock()
| void pcl::View::Unlock | ( | bool | notify = true | ) | const |
Unlocks this view for read and write operations.
Please read the important information given for the Lock() function member.
You shouldn't call this function if your routines have not called the Lock() function before. In other words, call Unlock() just once for each previous call lo Lock().
- Warning
- Be aware that just after this function returns, your processing routine must not try to modify this view or its associated image, since other thread might have locked it. If you need to gain exclusive read/write rights over this view, call Lock() again.
◆ UnlockForRead()
| void pcl::View::UnlockForRead | ( | bool | notify = true | ) | const |
Temporarily unlocks a view for reading.
If your code has successfully called Lock() for this view, then its screen rendition cannot be updated, because the core application will never try to read pixel data from a view that is read-locked. This can be a problem if, for example, you need to refresh this view's screen rendition to provide feedback to the user at a given stage of your processing.
The solution for such situations is calling this function to temporarily permit read-only accesses to this view and its image. When you no longer want to allow read-only operations for this view, call RelockForRead() and continue your processing work.
Your code may call Unlock() safely after this function; you should not call RelockForRead() if your processing task has finished, or if this view is no longer needed for it.
- Warning
- Do not use this function if your code has not called Lock() previously.
◆ ViewById()
Returns a view with the specified full identifier. If no view exists with the specified identifier, this function returns View::Null().
◆ Width()
|
inline |
◆ Window()
| ImageWindow pcl::View::Window | ( | ) | const |
Returns a managed alias for the image window this view pertains to.
The documentation for this class was generated from the following file:
