Volumic Search Troubleshooting

The 3DSpace Index default configuration enables octree computation, which is a requirement to use volumic search.

In the database, the volumic search configuration is stored in the crawlerProperties (not in the config.xml file).

This task shows you how to:

Configure Octree Computation
Monitor Octree Building

Configure Octree Computation

You can configure octree computation to define its depth and precision.

You can manage the octree configuration by specifying the following parameters to the set system searchindex MQL command: octreesactivation, octreedepth, octreeprecision.

Examples:

MQL> set system searchindex params octreesactivation true;
MQL> set system searchindex params octreedepth 5;
MQL> set system searchindex params octreeprecision 100;
MQL> set system searchindex params octreesactivation true octreedepth 5 octreeprecision 100;


Parameter	Description
`octreesactivation`	Triggers the octree computation. Accepted values: `true`, `false`. Default: `true`.
`octreedepth`	Indexing implements an approximation involving the use of square 3D elements referred to as voxels (abbreviation for volumetric pixels). When 3DSpace Index indexes an item of data, it is successively divided into individual voxels. The depth setting allows you to specify the number of divisions computed. Accepted values: integer greater than 1 Default: `6`. Changing the default value may affect indexing and 3DSearch query performance. Decreasing the value: Generates bigger voxels. Limits memory consumption. Makes indexing and 3DSearch querying faster. However, 3D searching is less accurate since too much geometry is found, as voxels are larger. Increasing the value produces the opposite effect: Generates smaller voxels. Increases memory consumption. Leads to poor indexing and 3DSearch querying performance. However, 3D searching is more accurate since the smaller size of the voxels guarantees that only the required geometry is found when searching.
`octreeprecision`	The absolute precision limit is a safeguard used to prevent the generation of voxels, whose size is so small that they lead to unacceptable high memory consumption and degraded 3D searching performance. If you define the value to 5mm, then voxels cannot be smaller than 5mm. Accepted values: float greater than 0 Size is in millimeters. Default: `10`mm.

Monitor Octree Building

You can monitor octree building in the index by verifying the logs and using the scripts described below.

Specific octree logs are available both MQL and FCS sides:

$MATRIXINSTALL/logs/logOctreeMQL.log for MQL.
$TOMCATNoCAS/logs/logOctreeFCS.log for FCS.

You can also find information about octree in the *SLF4J_BOS* and *SLF4J_mql* logs. However, these files are harder to read as they log other information.

Context: The following procedure does not list all possible options. To know more about these scripts, use -help or -h.

The examples below are for Linux, they may slightly differ on MS Windows.

Important: Use these scripts in an On-Premise environment only.

To identify the missing octree, run: identifyRepWithMissingOctrees.sh|bat
Note: To ignore Reps for which the octree computation failed and that are useless to retry, use the following options: -ignoreEmptyCGRsOrNoTriangles, -ignoreEmptyCGRs, -ignoreCGRsWithNoTriangles. For more information, use -h with this script.

This script calls the Business Analytics Server search-api to retrieve information about objects in the index that have missing octree. Run it from a machine that has access to the Business Analytics Server search-api.

The script sends the output of this call to a directory that the resendToEventMonitor.sh|bat script can then use to recompute the octree, as detailed in step 3.

Example: By specifying serverhome:
```
./identifyRepWithMissingOctrees.sh 
-outfolder /home/data/RTV/crawldir
-cloudviewPort 19010 -host ve4888.3ds.com -protocol http 
-serverhome /home/data/RTV/R424install/server
```
Where:
- outfolder is the output directory that will collect the script results.
- http://ve4888.3ds.com:19010search-api
- serverhome gives the installation path.
Note: On Windows, there is no need to specify serverhome because the path is retrieved from the relative path automatically.

Example: By specifying a JDK and a class path:
```
./identifyRepWithMissingOctrees.sh 
-JDKPath INSTALL/jdk 
-cloudviewPort 19010 -host ve4888.3ds.com –protocol
-classPath "SERVERHOME/linux_a64/docs/javaserver/*:SERVERHOME/linux_a64/docs/javacommon/*"
```
Where:
- JDKPath is the server JDK directory.
- http://ve4888.3ds.com:19010 refers to the address of the Business Analytics Server search-api
- classPath gives the paths of the installation jars.
Note: On Windows, there is no need to specify JDKPath/classPath because the path is retrieved from the relative path automatically.
To know the number of missing octree, run: estimateNumberOfMissingOctrees.sh|bat
This script is similar to identifyRepWithMissingOctrees.sh|bat but it does not retrieve information about the objects (no file output, only information printed on screen). It performs a synthesis and quickly returns an estimate of the number of objects in the index with missing octree. It takes similar parameters as the identifyRepWithMissingOctrees.sh|bat script, but does not need an output directory.
To recompute the missing octree, run: resendToEventMonitor.sh|bat
This script takes as input the output directory of the identifyRepWithMissingOctrees.sh|bat script.

Important: Run it on a machine with matrix access, as it relies on mxmrun.sh|exe.

Example:
```
./resendToEventMonitor.sh -user creator 
-crawlfolder /home/data/RTV/crawldir
-serverhome /home/data/RTV/R424install/server
```
Where:
- /home/data/RTV/crawldir comes from the output of the identifyRepWithMissingOctrees.sh|bat script.
- creator is the matrix user.
- serverhome is a mandatory option to specify the installation path.
Note: On Windows, there is no need to specify serverhome because the path is retrieved from the relative path automatically.

This script does not perform any indexing by itself. It sends the indexing jobs with the missing octree to the event-monitor queue. The next indexing operation will process them, when you run the start searchindex mode partial MQL command.