Tutorial 2 - Import Data

• Start xgrt.exe
• Click on "New Scene" - A new icon in the object browser named "Scene1" appears
• Doubleclick the "Scene1" object - The scene editor opens
• Select "Import" in the "File" menu - The import assistant window appears
  
  
  
  
• Click on "..." to open the file dialoque and select a 3D data file (of common type) for import. Supported types are ply, smf, obj, wrl, off, bmp/jpg/png (results in a flat point plane) and some more special custom types.
  Note: there may be features/functionalities in the files or subtypes which are not correctly imported at the moment. The importers are designed for most basic but no advanced definitions, e.g. textures or object grouping features of some file formats are not supported at the moment. (however, position data of the points should be loaded correctly in all cases.) See Note2 at the end of this tutorial if you want to implement your own importer types.
• If you have chosen a file of common type, the appropriate ImporterReader subtype is selected automatically. So all you have to do is to click on "Start Import" to start the process.
  
  
  
  
• Finally press the F5-Key to center the view on the object.
  
  
  
  

Import Assistant Window Details:

Left side, which is identical to the PCCPointCloudCreator command:

    

1. With this checkbox you can decide wether to create a new PointCloud object in the scenegraph or not, so the data will be imported either to a new pointcloud or to an already existing one. The following items 2. - 5. are just of interest if "Create New PointCloud" checkbox is enabled.
2. Insert the name of the new pointcloud here, including the scenegraph path.
3. Here you can select the type of the new pointcloud. The importer will automatically try to import to the selected cloud type.
   • Unstructured: The simplest type for small scenes, all data is kept in main memory without any structure
   • Parametric: Data in main memory, but structured by 2D parametric coordinates. May be used for heightfields or the like.
   • Hierarchical-In-Core: Hierarchically structured pointcloud type, all data in main memory. Needed for multiresolution rendering and accelerated point access in medium-sized scenes.
   • Hierarchical-Out-Of-Core: Hierarchically structured pointcloud type, data is swapped between hard disk and main memory. Allows multiresolution rendering and accelerated point access in extreme large scenes.
   • Unstructured In-Core Triangle-Mesh: Simple type for triangle meshes, all data is kept in main memory. Just works if imported data has face information.
4. This button opens the VertexDescriptor editor where you can change the attribute channels of the new pointcloud.
5. Parameter settings for hierarchical pointclouds only. You may retain them unchanged for the time being.

Right side, which is identical to the PCCImporter command:

    

1. Click on "..." or insert filename by hand as described above.
2. If a file of common type was chosen (see above for supported file types), the appropriate ImporterReader subtype is selected automatically. By clicking on "Edit" you can customize some settings of the selected reader, which is unnecessary for almost all types due to automatic detection. In addition to the common file types Microsoft research depth images (color_bmp+depth_bmp) are also supported, just chose the MSDepthImages reader subtype. Moreover you can import almost arbitrary ASCII data files by selecting the CustomASCII reader subtype, details are described below.
3. Insert the name of the target pointcloud including the scenegraph path here. This should be the same as the new pointcloud name on the left side of the assistant window or an existing pointcloud if the create checkbox is disabled. (automatic naming is not implemented so far)
4. Settings for parametric target pointclouds, allows to import the points with parametric coordinates specified in the file if checkbox is enabled.
   
   • param coords attribute channel: If there exists an attribute channel in the cloud with the given name, the parametric coordinates themselves are additionally written there.
   • x-coords scaling: Scaling factor for the parametric x-coordinates. If the coordinates in file are 10,20,30,... for example then you can specify 0.1 as scaling to write the points at target coordinates 1,2,3,...
   • y-coords scaling: Scaling factor for the parametric y-coordinates.
   • x-coords offset: Offset for the parametric x-coordinates.
   • y-coords offset: Offset for the parametric y-coordinates.
5. Finally click on "Start Import" to start the import process.

Custom ASCII Reader Details:

This reader is applicable for files where the point data is saved as ASCII text and every single line in the file is associated with exactly one point of the point set.

    

1. Here you can choose between some hardcoded pre-defined settings.
2. Use this selector if the first row of the ASCII-File specifies some information about the size of the point data set. Width and height are only important for parametric pointsets where they define the parameter domain. Unstructured pointset types always have width=1 and height=NumberOfPoints and the option "none" should do the trick in most cases.
   
   • none: No header with size information exists, the importer will stop at the end of the file. This option should work in most cases with unstructured target clouds.
   • user defined: Allows you to enter width and height by yourself. Use this for parametric input data if you know width and height and these are not specified in the file header. For unstructured input data use width=1 and height=NumberOfPoints. It's possible to import just the first part of a dataset with this, because import will stop when width and height are reached. Remember that these settings are just for the file reader, so you can import from parametric input to an unstructured target cloud without a problem.
   • width height: Use this if there are two integer values in the first line (after ignored lines, see below) of the ASCII file, specifying the size of the point set.
   • "widthtext" width "heighttext" height: As above, but there is a word like "width" or "height" before each value.
   • numPoints: There is only one value in the first line (after ignored lines, see below) of the ASCII file that specifies the total number of points without especially defining width or height.
3. skip: Allows to jump over some values or lines. Note: Wrong formatted or unrecognizable lines are always ignored by default!
   • ignore first # lines of file: Here you can enter a number of first lines in the file you want to be ignored, e.g. if you have some sort of object description at the beginning of the ASCII file or something like that. Attention: the position of size informations in the header (see above) is affected by this setting, so if the first 3 lines are ignored, the size information has to be in the 4th line.
   • ignore lines beginning with: Here you can enter multiple comment markers, telling the importer what lines to ignore. E.g. if you add "//" to the list (press return key to add a value), all lines beginning with "//" will be ignored. To remove an existing value select it and press the "remove" button.
   • ignore columns: Here you can enter multiple columns, which should be ignored. E.g. adding "0" and "2" to the list (press return key to add a value) will ignore the first and the third data column in the file. To remove an existing value select it and press the "remove" button.
4. columns in file separated by: Allows you to select or define a different column separator (press return key to add a value), e.g. if the values in the file are separated by semicolons instead of spaces.
5. VertexDescriptor format: Here you can specify how the point data is stored in the ASCII file. Every single line of the ASCII file corresponds to one vertex of the point set, whereas the columns contain the values of the vertex attributes. The attribute channels (considering dimension and datatype) are consecutively read out in the order they are defined in the VertexDescriptor list. E.g. if you have defined two attributes position 3 float and intensity 1 integer, the importer expects 3 float values and 1 integer value per line in the ASCII file, where the first three columns define the position and the last column defines some intensity information for the point. Remember that the target point cloud should have these attribute channels too.
   • Attributename: Enter a name for the attribute channel.
   • Dim: The dimension of the attribute channel.
   • Datatype: The datatype of the attribute channel.
   • Add: Adds the specified channel to the list.
   • Delete: Deletes the selected channel from the list.
   • Up/Down: Move the attribute up or down in the list.
6. generate example: Outputs an example, how the imported file should look like, according to the current settings. This is very useful to compare the importer settings with the real contents of your file.

Example:

If you have the following ASCII-file:

  This is a sample ASCII point object
  file to demonstrate the importer!
  The 5th and 6th column are irrelevant.
  width 200 height 382
  0 0.18869 -0.100183 -0.04781 123 45.6 0.552
  1 0.19349 -0.039143 -0.03249 123 45.6 0.514
  # that's a comment
  2 0.19882 -0.06613 -0.054168 123 45.6 0.493
  3 0.20712 -0.06515 -0.040523 123 45.6 0.501
  ...                                        

then your settings should be:

• file header: "width" width "height" height
• ignore first 3 lines
• ignore comment markers: #
• ignore columns: 4, 5
• VertexDescriptor:
   0 - number - 1 - int32
   1 - position - 3 - float32
   2 - intensity - 1 - float32
  

Note 1:
The VertexDescriptor of the target cloud should be compatible to the import-file to avoid loss of data. Therefore the attributes used in the import reader should also exist in the target point cloud with the same dimension and type. Data of attributes which are defined just in the importer but not in the target cloud will be thrown away, attribute-channels which are defined just in the target cloud but not in the importer will be filled with 0.

Note 2:
The importer architecture allows to connect different "readers" (responsible for reading point data from files) with different "adders" (responsible for adding the points to different types of target clouds/meshes). As the reader has to be chosen manually or automatically by file ending, the adder will automatically be selected depending on the target cloud/mesh type.
To implement your own custom importer take a look at the editor/importer/ folder in the source code. All you have to do is to add a new class derived from PointCloudImporterReader and write your code there. For details on the reader interface take a look at the existing subtypes, especially their public methods.