.. _geometric-search-tutorial:

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:

.. image:: 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 :ref:`3diax-reference`. The URIs are as follows:

.. csv-table:: model URIs
   :header: "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:

.. sourcecode:: javascript

    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

.. csv-table:: indexed URIs
    :header: "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:

.. image:: 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:

.. sourcecode:: javascript

    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.

You can find full details on how to use the Geometric Search module by contacting support@authentise.com.