HOOPS Visualize Documentation

< Table of Contents

PROGRAMMING GUIDE

9.1 Importing files

9.1 Importing files

HOOPS Visualize can load a variety of different 2D and 3D file formats. If HOOPS Exchange is also licensed, the list of importable file formats is extended even further. Regardless of which type of file you are loading, HOOPS Visualize uses a common pattern to load all files. There are four basic steps:

  1. Use an import options kit to set the file load options.
  2. Load the file. Using a notifier is highly recommended, but not required. All files are loaded asynchronously.
  3. Take appropriate action based on the status of the notifier.
  4. Respond to any errors or exceptions.

9.1.1 General import example

The following example loads a HOOPS Stream File (HSF). HSF is the native file format for Visualize. An HSF contains all model information as well as its related scene hierarchy that can be used to save and load complete scenes. The data is stored in a compressed format. HSFs are loaded using the Stream class. Other file formats use a similar class. For example, to load an STL file, you would use the STL class. It is recommended to make use of a notifier during file loading. Notifiers are available for all file types - their purpose is to track loading progress:

[snippet 9.1.1.a]
try
{
Stream::ImportOptionsKit importOptionsKit;
importOptionsKit.SetSegment(mySegmentKey); // set destination segment
notifier = Stream::File::Import(filename, importOptionsKit);
// the notifier can be used to check the load progress
float percent_complete;
notifier.Status(percent_complete);
// pauses this thread until the HSF is finished loading
notifier.Wait();
}
catch (IOException ioe)
{
// handle exception
throw;
}
try
{
importOptionsKit.SetSegment(mySegmentKey); // set destination segment
notifier = Stream.File.Import(filename, importOptionsKit);
// the notifier can be used to check the load progress
float percent_complete;
notifier.Status(out percent_complete);
// pauses this thread until the HSF is finished loading
notifier.Wait();
}
catch (IOException ioe)
{
// handle exception
}

Snippet 9.1.1.a demonstrates the use of Wait() on your notifier object. Because all notifier classes do their I/O in a separate thread, the potential exists to use the object before it is done loading, especially if you try to interact with it immediately after you call Import(). Calling Wait() ensures the I/O operation is complete before continuing. If you do not use Wait(), you could end up with unexpected behavior.

After the file load is finished, you should test the result of the load operation to ensure there was not an unexpected failure:

[snippet 9.1.1.b]
IOResult ioResult = notifier.Status();
if (ioResult == IOResult::Success)
{
// good
}
else
{
// bad
throw;
}
IOResult ioResult = notifier.Status();
if (ioResult == IOResult.Success)
{
// good
}
else
{
// bad
}

Assuming the file was loaded correctly, you can get information about the model by querying the associated Stream::ImportResultsKit.

[snippet 9.1.1.c]
Stream::ImportResultsKit importResultsKit = notifier.GetResults();
// get the default camera of the model
importResultsKit.ShowDefaultCamera(cameraKit);
// get the segment this model was loaded into
importResultsKit.ShowSegment(someSegment);
Stream.ImportResultsKit importResultsKit = notifier.GetResults();
// get the default camera of the model
importResultsKit.ShowDefaultCamera(out cameraKit);
// get the segment this model was loaded into
importResultsKit.ShowSegment(out someSegment);

NOTE: For HSF files, any user options contained within will be UTF8 encoded and stored as user data.

IMPORTANT: During the import process, if you did not use the Stream::ImportOptionsKit to specify a destination segment, Visualize will create a root segment and place the model there. In this case, to display the model it is necessary to call ShowSegment (as shown in the previous code snippet) in order to get the key of the segment where the model was loaded. After locating the model, it can be included into the tree for rendering.

Canceling the import

If the file import is taking too much time, the user changes his mind about loading the file, or your application detects it is running out of memory, you have the ability to cancel a file import.

[snippet 9.1.1.d]
notifier = Stream::File::Import(filename, importOptionsKit);
// cancel the import
notifier.Cancel();
// wait for the cancellation to finish
notifier.Wait();
// test for the IOResult
if (notifier.Status() != IOResult::Canceled)
; // if you get here, something unexpected happened

Canceling is not immediate. Once you cancel, a notice is posted that the import needs to be cancelled. The importer checks periodically to see if the notice has been posted, and when it sees it, it cancels itself.

9.1.2 Importing other file formats

In addition to HSF files, HOOPS Visualize can also natively import STL and OBJ files. The procedure follows the same pattern as HSF. As before, be sure to set the destination segment in the importer's options kit:

[snippet 9.1.2.a]
// importing STL file
STL::ImportOptionsKit stlOptionsKit = STL::ImportOptionsKit::GetDefault();
stlOptionsKit.SetSegment(mySegmentKey);
STL::ImportNotifier stlNotifier = STL::File::Import(stlFilename, stlOptionsKit);
stlNotifier.Wait();
// importing OBJ file
OBJ::ImportOptionsKit objOptionsKit;
objOptionsKit.SetSegment(mySegmentKey);
OBJ::ImportNotifier objNotifier = OBJ::File::Import(objFilename, objOptionsKit);
objNotifier.Wait();
// importing STL file
stlOptionsKit.SetSegment(mySegmentKey);
STL.ImportNotifier stlNotifier = STL.File.Import(stlFilename, stlOptionsKit);
stlNotifier.Wait();
// importing OBJ file
objOptionsKit.SetSegment(mySegmentKey);
OBJ.ImportNotifier objNotifier = OBJ.File.Import(objFilename, objOptionsKit);
objNotifier.Wait();

For MTL files, the OBJ importer opens and reads them in order to discover which material properties are present in the file. The file is closed when the import completes or is interrupted by an exception.

For information on how to load a file into HOOPS Visualize using HOOPS Exchange, see section 9.3. Integrating with HOOPS Publish is covered in section 9.4.

9.1.3 Importing 2D images

The examples from previous sections have all dealt with loading 3D CAD files. 2D images are loaded slightly differently. First of all, the process uses the Image namespace. Secondly, the result of the file load is an ImageKit. Normally the image is loaded from an external file, although it is possible to use a programmtically-defined or generated image as well. This is the process you would use to load an image to prepare it for use, for example, as a texture:

[snippet 9.1.3.a]
ImageKit imageKit;
try
{
imageKit = Image::File::Import(filename, iok);
}
catch (IOException ioe)
{
const char* problem = ioe.what(); // shows cause of the exception
throw;
}
ImageKit imageKit;
try
{
iok.SetFormat(Image.Format.Jpeg);
imageKit = Image.File.Import(filename, iok);
}
catch (IOException ioe)
{
String problem = ioe.Message; // shows cause of the exception
}

Visualize can load common image formats, including JPG, PNG, and TGA. The full list of supported file formats is provided in the appendix. It is also possible to save 2D images out of an ImageKit in a similar way. Note that the size and export format must be specified within the ImageKit itself.

[snippet 9.1.3.b]
Image::File::Export(filename, myImageKit);
HPS.Image.File.Export(filename, myImageKit);

Saving screenshots

In order to save a screenshot, you can skip the ImageKit entirely and pass a WindowKey as a parameter. If you do not specify the image size, the window size is used. If you do specify the image size, and it does not match the window size, the resulting image will be stretched to match the size you specify. This procedure is as follows:

[snippet 9.1.3.c]
Image::ExportOptionsKit export_options;
export_options.SetFormat(Image::Format::Png);
export_options.SetSize(800, 450);
Image::File::Export(filename, myWindowKey, export_options);
HPS.Image.ExportOptionsKit export_options = new HPS.Image.ExportOptionsKit();
export_options.SetFormat(HPS.Image.Format.Png);
export_options.SetSize(800, 450);
HPS.Image.File.Export(filename, myWindowKey, export_options);