Tutorial

Geometric Search is a very straightforward product. In this tutorial I’m going to show you how to get some models indexed and how to search against these models. We’ll start with a few models that I’ve uploaded:

../_images/all_three.png

These are the three images I’m going to be working with for this tutorial. They’ll be called ‘testcube’, ‘donut’ and ‘klein bottle’ respectively. The shapes are different enough that we should be able to easily see how Geometric Search works.

I’ve uploaded these three models and gotten back a URI. You can learn more about how to upload models to 3Diax in 3DIAX API Reference. The URIs are as follows:

model URIs
Model Model URI
testcube https://models.authentise.com/model/4462ae47-f5b6-42a5-9ef1-67fe98fe963a/
donut https://models.authentise.com/model/77fc10b1-a4da-4732-9c2a-b3e2854247e5/
klein bottle https://models.authentise.com/model/29301921-2dcd-4281-bb3f-ed3fd31c38ad/

These will be important because the Geometric Search service relies on model URIs to do its work. Geometric Search doesn’t expect you to move model data around yourself - that would be extremely inconvenient since they may be many hundreds of megabytes in size. Instead you use URIs as a pointer to a model and keep the data very light and fast.

The first thing we need to do to get working with Geometric Search is to get our models indexed. We make three web requests of this form:

POST https://geometricsearch.authentise.com/indexed-model/
Content-Type: application/json

{
    "name"          : "testcube",
    "description"   : "The testcube model for the Geometric Search tutorial",
    "model_uri"     : "https://models.authentise.com/model/4462ae47-f5b6-42a5-9ef1-67fe98fe963a/"
}

This request may take some time as the model is analyzed and broken down into its overall signature. The response to the request will be a 204 with a Location header that is a URI to the resource representing that this model has been indexed. I’m not going to show each of the three requests here, but after I’ve indexed my 3 models I have the following URIs

indexed URIs
Model index URI
testcube https://cerebro.authentise.com/indexed-model/535ff942-4a2f-467f-9f9f-fa8f3a7e2e0a/
donut https://cerebro.authentise.com/indexed-model/7a025db8-97fd-4845-9b1b-3910d03bed78/
klein bottle https://cerebro.authentise.com/indexed-model/3720033e-b7eb-4620-b493-ef9713d9f7a6/

Now I’m ready to try out some searches. I’ve got another model that looks like this:

../_images/cube_15.png

This is pretty similar to my testcube - it’s just 15mm to a side rather than 10mm. It’s designed to be a very reliable example of two models that are similar. I can perform a search for similar models with:

GET https://geometricsearch.authentise.com/similar-models/?
    filter[model]=https://models.authentise.com/model/637cc74f-76e6-4354-ac8e-f1586135c17b/&
    filter[tolerance]=3&
    filter[number_of_results]=20&
    filter[min_percentage]=30
Content-Type: application/json

{'resources': [{
    'max_percentage': '130',
    'min_percentage': '30',
    'model': 'https://models.authentise.com/model/637cc74f-76e6-4354-ac8e-f1586135c17b/',
    'number_of_results': '20',
    'results': [{
        'distance': 0.0,
        'model': 'https://models.authentise.com/model/4462ae47-f5b6-42a5-9ef1-67fe98fe963a/',
        'scale_factor': 0.6666
    }],
    'tolerance': '3'
}]}

The request above includes several paramters as query arguments to our URL. I have avoided escaping them for readability - your request should URL-encode all of the characters that need escaping. There’s several paramters included

  1. model - The URI of the model we are searching against
  2. tolerance - A value between 1 and 3 that indicates the amount of tolerance to allow to consider something a match
  3. number_of_results - The number of results to return to limit the amount of data transferred and the speed of the search
  4. min_percentage - The minimum amount of correlation between a match and the search model to consider a ‘hit’

The results are returned embedded in a resources object. Several parameters are included from the original query so that the user can validate that their parameters were understood correctly. Finally is the list of results. In our example here we’ve matched just one of our models - the testcube. The results show the scaling factor between our searched model and the match. In this case if we scale our searched for model by 0.6666 we’ll get our indexed test-cube model.

You’ll want to try uploading your own models and using different parameters to test how to best match models in your use case. Tightening the tolerance by setting it to 1 or 2 will weed out models that aren’t very similar to your target model. Increasing the min_percentage will similarly remove models that aren’t close enough to the model.

As usual you can find full details on how to use the Geometric Search module in Reference