 |
Isis 3 Developer Reference
|
|
Isis 3 Developer Reference
|
Determine SPICE kernels defined in an ISIS file. More...
#include <Kernels.h>
Public Member Functions | |
| Kernels () | |
| Default Constructor. More... | |
| Kernels (const Kernels &kernels) | |
| Initialize new Kernels from state of existing one. More... | |
| Kernels (const QString &filename) | |
| Construct using an ISIS file name. More... | |
| Kernels (Cube &cube) | |
| Construct using an ISIS Cube object. More... | |
| Kernels (Pvl &pvl) | |
| Construct from an ISIS label. More... | |
| virtual | ~Kernels () |
| Destructor always unloads the kernels from the pool. More... | |
| Kernels & | operator= (const Kernels &kernels) |
| Copy constructor for existing Kernels objecr. More... | |
| int | size () const |
| Returns the number of kernels found and/or loaded. More... | |
| int | Missing () const |
| Return count of missing kernel files. More... | |
| void | Init (Pvl &pvl) |
| Determine Spice kernels in an ISIS label. More... | |
| bool | Add (const QString &kfile) |
| Add a new kernel to the list. More... | |
| void | Clear () |
| Remove all kernel files from internal list. More... | |
| int | Discover () |
| Determine which NAIF kernels are currently loaded in the pool. More... | |
| void | Manage () |
| Set each kernels management status to managed. More... | |
| void | UnManage () |
| Set each kernels' management state to unmanaged. More... | |
| bool | IsManaged () const |
| Determine if all kernels are managed by this object. More... | |
| void | InitializeNaifKernelPool () |
| Initialize the NAIF kernel keeper pool. More... | |
| int | Load (const QString &ktype) |
| Load all kernels with one more types. More... | |
| int | Load () |
| Load all kernels in list. More... | |
| int | UnLoad (const QString &ktype) |
| Unloads all kernels of a specific type. More... | |
| int | UnLoad () |
| Unloads all kernels from the NAIF pool. More... | |
| int | UpdateLoadStatus () |
| Determine the load status of all kernels known to this object. More... | |
| int | Merge (const Kernels &other) |
| Merge the contents of another Kernels object. More... | |
| QStringList | getKernelTypes () const |
| Return list of types in kernel list. More... | |
| QStringList | getKernelList (const QString &ktype="") const |
| Provide a list of all the kernels found. More... | |
| QStringList | getLoadedList (const QString &ktypes="") const |
| Returns list of kernel currently loaded according to status. More... | |
| QStringList | getMissingList () const |
| Returns list of kernels that were not found to exist. More... | |
| int | CameraVersion () const |
| Returns the ISIS camera model version number. More... | |
Determine SPICE kernels defined in an ISIS file.
This class determines all SPICE kernels associated with an ISIS cube file and optionally/selectively loads them using the NAIF toolkit. This creates the kernel pool as it was when spiceinit determined all the kernels and it initialized the file for geometric operations.
Note that because NAIF kernel management is global in nature, careful thought and planning should preceed use of this class. You can get yourself into trouble if you take over management of kernels and inadvertantly unload them without regard for use by other resources. Methods are provided in this implementation to help minimize problems related to management of this global resource.
Note that ISIS caches some of the voluminous NAIF kernels, extracting only what is required from the SPK and CK (generally) kernels for a given observation. After this occurs, these kernels are no longer loaded by the ISIS Spice class hierarchy. This class provides that environment so that further NAIF operations can occur, such as velocity vector and instrument timing manipulations.
This class can be used instead of instantiating an ISIS Spice object. The recommended usage is as follows:
The implications of this code segment are: 1) All the kernels pertinent to an individual ISIS file are identified upon Kernels instantiation, 2) their load status is determined using the UpdateLoadStatus() method, 3) kernels already loaded are flagged as unmanaged, meaning they cannot be unloaded unless management is an explicit "hostile takeover" provided via the Manage() method (don't do it unless you absolutely have to), 4) after checking load status, and kernels you load are managed by your instantiation, and 5) when you UnLoad() or the object is destroyed, all managed kernels are unloaded - unmanaged kernels are not unloaded.
This class can be used in lieu of the Spice class with liberal use of the UpdateLoadStatus() and Discover() methods of this class.
It is possible to double load NAIF kernels, so be sure to maintain load status via UpdateLoadStatus() and proper usage techniques.
| Isis::Kernels::Kernels | ( | ) |
Default Constructor.
Default constructor simple initialization.
| Isis::Kernels::Kernels | ( | const Kernels & | kernels | ) |
Initialize new Kernels from state of existing one.
Initialize new Kernels object from the state of an existing one while preserving the state of one copied. Each kernel file state is copied to this new one. It ensures that ones that are already opened are set to an unmanaged state from the source. It also checks the current open state and will set ones found to be open as unmanaged as well. All other kernels files can be managed by this new instance.
| kernels | Source kernels object |
| Isis::Kernels::Kernels | ( | const QString & | filename | ) |
Construct using an ISIS file name.
| filename | Name of ISIS cube file |
| Isis::Kernels::Kernels | ( | Cube & | cube | ) |
Construct using an ISIS Cube object.
| cube | Cube object of ISIS file |
References Isis::Cube::label().
| Isis::Kernels::Kernels | ( | Pvl & | pvl | ) |
Construct from an ISIS label.
| pvl | ISIS label to get kernel information from |
|
inlinevirtual |
Destructor always unloads the kernels from the pool.
References UnLoad().
| bool Isis::Kernels::Add | ( | const QString & | kfile | ) |
Add a new kernel to the list.
This method is provided to add individual NAIF kernels directly. Files names must contain a path to the file. ISIS "shortcuts" as defined in the DataDirectory group in the IsisPreferences files (e.g., "$base/kernels/lsk/naif0009.tls") are supported as well.
Note that if the file already exists, it is not added. This situation is indicated with a return value of false.
Files added in this way are set to manageable status.
| kfile | Name of kernel file to add with valid directory path |
Referenced by Isis::PushFrameCameraCcdLayout::addKernel().
|
inline |
Returns the ISIS camera model version number.
| void Isis::Kernels::Clear | ( | ) |
Remove all kernel files from internal list.
This method will clear out the kernel file list without any regard for its current state. This does not unload any kernels that are unloaded. One must Unload() prior to calling this method in order to gracefully close out the existing state of the kernel pool.
| int Isis::Kernels::Discover | ( | ) |
Determine which NAIF kernels are currently loaded in the pool.
This method queries the NAIF KEEPER system/pool for all loaded kernels and adds them to the list in this object. It only knows about kernels that are loaded by the NAIF furnsh_c routine. If no kernels are loaded there will be no kernels discovered by this routine.
Upon entry into this method, the current list is discarded without unloading them. Hence, any kernels in this list are discard, whether they are loaded and managed by this class or not. If they are loaded according to the internal state as determined by previous activity in this class, and no additional NAIF activity has occured that unloads them, they should be found again by this method.
Note that ALL kernels discovered by this routine are marked as unmanaged, meaning you cannot unload the kernels without exerting management upon them via the Manage() method. See the Manage() documentation for more details and potential issues with this feature.
This method should not be used to update the load nature of an established kernel list. See the UpdateLoadStatus() method for this feature.
Here is a short coding example showing use of this method. It assumes there are some kernels already loaded (although it is entirely possible that no kernels are loaded). It will take over management of these kernels as well:
Referenced by Isis::LightTimeCorrectionState::checkSpkKernelsForAberrationCorrection().
| QStringList Isis::Kernels::getKernelList | ( | const QString & | ktypes = "" | ) | const |
Provide a list of all the kernels found.
This method will return all the kernel file references as found in the ISIS label.
| ktypes | Optional list of kernel types to return in the list. This can be any type found in the internal list as returned by getKernelTypes(). If empty, returns all kernels. |
Referenced by Isis::LightTimeCorrectionState::checkSpkKernelsForAberrationCorrection().
| QStringList Isis::Kernels::getKernelTypes | ( | ) | const |
Return list of types in kernel list.
This method determines what types of kernels are currently in the internal list and returns them in alphabetical order. An empty list is returned if there are no kernels. The list may contain "UNKNOWN" which is the default type assigned when the type of the kernel file cannot be determined. These kernels are excluded from any loading/unloading.
The list of known types are:
CK SPK DAF (synonymous for SPKs as well so load both) PCK EK META IK FK SCLK IAK (ISIS specific) DSK
Kernel types are determined by inspecting the first 8 characters of a kernel file and extracting the contents there. The actual type is the string value after the last '/' character. This is typically the value that is also returned by the NAIF kinfo_c utility.
References Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::key(), and Isis::CollectorMap< K, T, ComparePolicy, RemovalPolicy, CopyPolicy >::size().
| QStringList Isis::Kernels::getLoadedList | ( | const QString & | ktypes = "" | ) | const |
Returns list of kernel currently loaded according to status.
This method returns a list of kernel filenames that are loaded according to internal status. If the load status is in question, used UpdateLoadStatus() prior to calling this method.
Users can restrict the list to loaded kernels of a specific type. For example, to get a list of all CKs and SPKs loaded, the following code can be used:
| ktypes | Optional string containing comma separated list of types to return if loaded. If empty, returns all types of kernels that are deemed loaded. |
| QStringList Isis::Kernels::getMissingList | ( | ) | const |
Returns list of kernels that were not found to exist.
This method can be used to identify which kernels do not exist when they were added to this object. If the Missing() method returns a number > 0, then this routine returns a list of files missing.
| void Isis::Kernels::Init | ( | Pvl & | pvl | ) |
Determine Spice kernels in an ISIS label.
This method reads keywords in the Kernels group in the ISIS label hierarchy to find all the pertinent kernel files. They are found in the Kernels Group.
The order listed here is the same as the order specified in the ISIS Spice class at the time this class was written. When loading and unloading, the order is the same as is read in here.
| pvl | Assumed to be a valid ISIS cube label containing the Kernels group |
| void Isis::Kernels::InitializeNaifKernelPool | ( | ) |
Initialize the NAIF kernel keeper pool.
This method will thoroughly clear out the NAIF kernel keeper pool. This is done using the NAIF k_clear() utility. As the documentation states, it operates by side effects unloading all kernels and reinitializing the keeper pool.
This method has no regard at to whether any of the NAIF kernels are managed or not. It does update all kernels load status to unloaded.
NOTE: This method should be used with caution as it can have disasterous side effects for ISIS processing. Specifically, using this method arbitrarily will likely cause fatal exceptions particularly for Spice class instantiations.
| bool Isis::Kernels::IsManaged | ( | ) | const |
Determine if all kernels are managed by this object.
This method will return true if all kernels listed in this object are marked as "managed". If any one of the kernels is found to have an unmanaged state, false will be returned by this routine.
Management/unmanagement is an all-or-nothing scheme.
| int Isis::Kernels::Load | ( | const QString & | ktypes | ) |
Load all kernels with one more types.
This method will find all kernels with a specific type and loads them into the NAIF KEEPER system/pool using the NAIF furnsh_c utility. If they are already loaded, they are not loaded again. Status is set to show they are loaded.
This object cannot monitor the kernel pool unless explicit action is taken. See the CheckLoadStatus() method. It will update the load status of kernels in the current list.
NOTE: If individual kernel are not managed by this routine they are not loaded. Users must invoke the Manage() method to enable full kernel manipulation.
| ktypes | One or more kernel types specified in a comma separated list |
Referenced by Isis::PushFrameCameraCcdLayout::addKernel().
| int Isis::Kernels::Load | ( | ) |
Load all kernels in list.
This method will iterate though all NAIF-type kernels and load them into the NAIF KEEPER system/pool using the NAIF furnsh_c utility. If they are already loaded, they are not loaded again. Status is set to show they are loaded.
This object cannot monitor the kernel pool unless explicit action is taken. See the CheckLoadStatus() method. It will update the load status of kernels in the current list.
NOTE: If individual kernel are not managed by this routine they are not loaded. Users must invoke the Manage() method to enable full kernel manipulation.
| void Isis::Kernels::Manage | ( | ) |
Set each kernels management status to managed.
This method will change every kernels's management state to managed so that full manipulation of every kernel can be performed by this object.
If a kernel is managed, it will be allowed to UnLoad at will. This is typically the only restriction of an unmanaged kernel.
| int Isis::Kernels::Merge | ( | const Kernels & | other | ) |
Merge the contents of another Kernels object.
This method mergest the contents of another Kernels object into this one. Kernels that exist in both instances of the object are handled special. The status of this object's version of the file is updated to reflect conditions of the other objects kernels.
When the file does not exist in this object, the kernel file structure is copied from the other Kernels object, its managed status is set to false (since it pre-exists in another object that must relinquish its management of it) and is added to this objects kernel list.
When the file does exist in this object, its load status is checked in the other Kernels object. If it is loaded according to the other object, it is marked as loaded in this object and its managed state is set to unmanaged (since it contained in another object, no assumptions can be made as to whom and how it came about to be loaded.
The following code fragment demonstrates how to ensure only one Kernels object retains complete control of the merged set of kernels:
The UpdateLoadStatus() ensures the state of the managed kernel list in master is completely up to date.
| other | Other Kenels object containing a separate list of NAIF kernels that will be merged with the contents of this object. |
| int Isis::Kernels::Missing | ( | ) | const |
Return count of missing kernel files.
Copy constructor for existing Kernels objecr.
This copy constructor ensures the kernel list copied from an existing object is set to proper conditions as to minimize interference of both object that existence.
Any current kernels that in this object are removed without regard for ther current state. The list of kernels in the source object are copied and their state is analyzed. Any opened kernels are set to unmanaged state.
| kernels | Source list from which the list is copied |
|
inline |
Returns the number of kernels found and/or loaded.
| int Isis::Kernels::UnLoad | ( | const QString & | ktypes | ) |
Unloads all kernels of a specific type.
This method will parse a string containing acronyms of NAIF kernels types and close only those found with the associated type. Types in the context of this class are loosely managed. They are typically types returned by the NAIF utilities, kinfo_c and kdata_c.
Only those files that match will be unloaded. There load states will be altered to reflect its load status.
Only files that are tagged as manageable but this object are closed. Unmanaged kernels are essentially ignored.
| ktypes | Comma delimited string specifying the type to unload. This string is of the form "LSK,FK,SPK". |
| int Isis::Kernels::UnLoad | ( | ) |
Unloads all kernels from the NAIF pool.
This method will unload all kernels from the kernel pool. It will unload them one at a time, which is known to be inefficient. You could consider using the InitializeNaifKernelPool() method for a more thorough and efficient cleansing.
Referenced by ~Kernels().
| void Isis::Kernels::UnManage | ( | ) |
Set each kernels' management state to unmanaged.
This method changes the management state to unmanaged, thus restricting the ability of this method to unload loaded kernels.
When a kernel is marked as unmanaged, it will persist in its loaded state even after the destruction of this object (there is really no way to track how kernels get loaded reliably).
| int Isis::Kernels::UpdateLoadStatus | ( | ) |
Determine the load status of all kernels known to this object.
This method will reevaluate the load status of each NAIF kernel contained within this object. This method can be useful when there are more than one of these Kernels objects instantiated.
It will check to determine if each NAIF kernel is loaded using the NAIF kinfo_c utility. It will change loaded status to unloaded and unloaded status to loaded from results of the query. It does not consider the managed state of any kernel.
One can always choose to use the Load() and UnLoad() utilities for explicit handling of the kernel (type) states.