Changed mechanism for specifying shapemodel RayTraceEngine keywords from IsisPreferences to BulletEngineSelect.pref preference file

[kledmundson]

Description

Currently, spiceinit adds the RayTraceEngine, OnError, and Tolerance keywords to the Kernels group from the IsisPreferences file to specify the ray-tracing engine for shapemodel processing. Having these keywords loaded via IsisPreferences is not desirable because it is loaded by every ISIS program every time they run. This has the potential to override existing selections used in spiceinit and produce unintended consequences. Providing these keywords in a dedicated preference file (e.g. BulletEngineSelect.pref) gives the user much more control over when they are applied.

The BulletEngineSelect.pref preference file was added to the "ISIS3/isis folder". This file contains the following...

Group = ShapeModel
RayTraceEngine = Bullet
OnError = Continue
EndGroup

and enables the user to set the RayTraceEngine to Bullet, in particular when running spiceinit on a cube.

Additionally, the CMakeLists.txt file was modifed to ensure BulletEngineSelect.pref is copied to $ISISROOT when running cmake.

References to RayTraceEngine keywords were removed from the IsisPreferences and TestPreferences files.

Documentation for spiceinit was updated to reflect these changes.

Related Issue

#5807

How Has This Been Validated?

All ctests passing.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Documentation change (update to the documentation; no code change)
• Breaking change (fix or feature that would cause existing functionality to change)
• Infrastructure change (changes to things like CI or the build system that do not impact users)

Checklist:

• I have read and agree to abide by the Code of Conduct
• I have read the CONTRIBUTING document.
• My change requires a change to the documentation and I have updated the documentation accordingly.
• I have added tests to cover my changes.
• I have added myself to the .zenodo.json document.
• I have added my user impacting change to the CHANGELOG.md document.

Licensing

This project is mostly composed of free and unencumbered software released into the public domain, and we are unlikely to accept contributions that are not also released into the public domain. Somewhere near the top of each file should have these words:

This work is free and unencumbered software released into the public domain. In jurisdictions that recognize copyright laws, the author or authors of this software dedicate any and all copyright interest in the software to the public domain.

• I dedicate any and all copyright interest in this software to the public domain. I make this dedication for the benefit of the public at large and to the detriment of my heirs and successors. I intend this dedication to be an overt act of relinquishment in perpetuity of all present and future rights to this software under copyright law.

[github-actions]

The build and test suite have started for your pull request.

To view your build log, please reference the build with source version: "PR_5809".

Additionally, check the latest "dev" source version to identify existing test failures. Please note that you are not responsible for the test failures that exist on both your PR and the dev branch.

[acpaquette]

Hi @kledmundson, just some general discussion on this. What's the benefit of adding the custom preferences file over just using the general preferences file?

I know it allows the user to customize the trace engine on a per app basis, I'm just not sure if we need to put another preference file in ISIS for users to manage. I agree with the updated docs but it might be better to add the PVL to the docs and allow users to create it themselves.

Something along the lines of:
Users need to specify the tracing engine used in ISIS when running spiceinit. To access ray-tracing engines in ISIS for projection, copy the following PVL into a .pref file, lets call it BulletEngineSelect.pref

########################################################
# Specifies Bullet ray-tracing engine for processing with
# shape models.
#
# RayTraceEngine = Bullet
# OnError = Continue | Fail
# Tolerance = { numerical value that will be set as the
#           tolerance for the Bullet or Embree shape
#           model }
#
########################################################

Group = ShapeModel
  RayTraceEngine = Bullet
  OnError = Continue
EndGroup

End

Then, run spiceinit with shape=user, a specified shape model, and -pref=$ISISROOT/BulletEngineSelect.pref on the command line. This will add the RayTraceEngine, OnError, and Tolerance keywords to the Kernels group if specified in the preference file BulletEngineSelect.pref

[kledmundson]

Hey @acpaquette,

After some discussion with Kris, I think the primary value-added here is that the user would (typically) never need to manage/maintain the pref file. Plus, if the pref file ever changes, the documentation would still be valid.

[acpaquette]

That seems somewhat counter intuitive, adding a different preference file wouldn't change how/when a user may want to tweak the configuration. This change would require a change to current documentation here: https://github.com/DOI-USGS/asc-public-docs/blob/main/docs/concepts/isis-fundamentals/preference-dictionary.md

Detailing to users where the new settings for "shapemodel" would be instead of the isisPreference file.

Even if users would rarely touch the file, detailing what the file is and what options are available is still needed