How to properly use the Bullet ray tracing engine

I have Phobos images initialized with spice using a DSK shape model. I have an old IsisPreferences files and did not include the ShapeModel group and the RayTraceEngine. I’m not clear what happens by default.

I have added the ShapeModel group to my preference file and have left things commented out, but if I want to use Bullet (or Embree), do I need to reprocess my data or will ISIS simply use the specified ray trace engine in the preference file when I un-comment that section? Is there any way to know what it is using?

Is there documentation anywhere in regard to use of a DSK shape model in ISIS? I couldn’t find anything other than what has been documented by others outside of Astro (Bennu), which was useful, but not at the level of invoking it.

Thanks!

The ray tracing engine is selected based on your preferences file. By default it uses the NAIF low-level routines which are okay as long as you have the shapemodel on a very high speed drive. To use the Bullet engine set RayTraceEngine to Bullet in your preferences file’s ShapeModel group.

Group = ShapeModel
  RayTraceEngine = Bullet
  OnError = Continue
EndGroup

If you spiceinit a cube with your preferences set to use embree or bullet it will add the “RayTraceEngine” keyword to the kernels group on the cube. This will be used if later run an application and your preferences file does not specify a RayTraceEngine but the selection of Bullet or Embree in your Preferences file will take precedence over anything spiceinit adds.

So, you do not need to re-process your images. You can just modify your preferences file. I keep extra preferences files around for embree and bullet whenever I want to use them.

There’s a little bit more information here:

https://isis.astrogeology.usgs.gov/7.0.0/documents/PreferenceDictionary/PreferenceDictionary.html

1 Like

@jessemapel, if you spiced a file explicitly using the bullet ray tracing (so that the keyword appears on the label after), is there a way to use the default isis ray tracing in subsequent programs?

If my preference file has the ShapeModel group commented out, will programs see “RayTraceEngine = bullet” in the image label and use that regardless of what it going on in the preference file?

I’m just wondering if it’s better to only use it when you want to via the -pref command line option (post spiceinit), but that option doesn’t work with the interactive programs. It’s not clear to me which programs honor the keyword in the label and how to have them ignore it if desired.

Thanks!

Try setting “RayTraceEngine = None” in your preferences file. If the keyword is just missing, then what you spiceinit’d with will be used, Bullet in this case.

Almost every program that uses the shapemodel will honor the your ray tracing engine choice. The exceptions are programs that open the shapemodel outside of the camera model, which I’m not aware of any specific ones that do.

Ok, that worked!

I’m trying to figure out best practices for working with the ray tracing in my general processing flow. Ideally I would keep bullet on all of the time, but occasionally it produces errors for some images when the default ray tracing doesn’t and I’d like to be able to choose if necessary. Thanks so much the needed detail.

This would be a good thing to add to the documentation in regard to the preference file. There is more of course that could be expanded on in regard to ray tracing, but just knowing how to turn off bullet or embree and use the default is really useful and we don’t say so anywhere that I am aware of.

1 Like

I just bumped an issue from the documentation work saying we need better docs on this. I’ll be sure to link this discussion so it gets included.

1 Like

I’m having some problems with keeping the bullet ray tracing available all of the time by having it uncommented in my isis preference file and am unsure if this is expected behavior or not.

Contents of ISIS preference file:

Group = ShapeModel
RayTraceEngine = Bullet
OnError = Continue
EndGroup

I need to have this on for Phobos to work around isis ray tracing failures in isis7.1.0-RC1. I opted not to have Bullet written to the image labels for a number of reasons and want it on for these data because I can not pass programs like qview and qnet a preference file containing this information.

However, when I initialize a Kaguya TC image (which picks up the LOLA DEM by default), I get this error:

Error = “Bullet could not initialize ISIS Cube DEM”

I thought the ray tracing engines only applied to DSK shape models, is that correct? Is this a bug that should be reported or is this behavior expected?

I worked around this by pointing to a preference file where RayTraceEngine=None, but there is nothing convenient about that and pointing to various preference files for different datasets is a bit cumbersome. Thanks for the feedback.