Quick Start
===========

Getting Started with Geobox python SDK
--------------------------------------

To begin using Geobox python SDK, you need to create a ``GeoboxClient`` object that authenticates with the Geobox API and provides access to different modules in the SDK.

Authentication
--------------

Direct Authentication
^^^^^^^^^^^^^^^^^^^^^

You can authenticate directly by passing your credentials to the ``GeoboxClient``:

.. code-block:: python

    from geobox import GeoboxClient
    client = GeoboxClient(username="username", password="password")

Once authenticated, you have access to the platform through the SDK:

.. code-block:: python

    layers = client.get_vectors()

Environment Variables
^^^^^^^^^^^^^^^^^^^^^

For better security and convenience, you can create a ``.env`` file and add your authentication information there, so you don't need to pass them directly to the ``GeoboxClient``.

Add these values to your ``.env`` file:

.. code-block:: bash

    GEOBOX_USERNAME=your_username
    GEOBOX_PASSWORD=your_password

With the environment variables set, you can initialize the client without parameters:

.. code-block:: python

    client = GeoboxClient()

For more authentication options, check ``.env.example`` and :meth:`geobox.api.GeoboxClient.__init__` for detailed information.

Example Usage
-------------

Upload and Publish a Dataset
----------------------------

Upload a dataset, publish it, check the publish task status, and get the published vector layer:

Sync:

.. code-block:: python

    from geobox import GeoboxClient
    from geobox.task import TaskStatus
    from geobox.file import PublishFileType
    
    client = GeoboxClient()

    # Upload a file
    file = client.upload_file(path=r'path/to/file')
    
    # Publish the file
    task = file.publish(layer_name='layer_name')
    
    # Wait until the publish task is finished and check the result
    if task.wait() == TaskStatus.SUCCESS:
        layer = task.output_asset  # vector layer, raster, or 3D model object


Async:

.. code-block:: python

    from geobox.aio import AsyncGeoboxClient
    from geobox.aio.file import PublishFileType
    from geobox.aio.task import TaskStatus
    
    async with AsyncGeoboxClient() as client:
        # Upload a file
        file = await client.upload_file(path=r'path/to/file')

        # Publish the file
        task = await file.publish(layer_name='layer_name')

        # Wait until the publish task is finished and check the result
        task_result = await task.wait() 
        if task_result == TaskStatus.SUCCESS:
            layer = await task.output_asset  # vector layer, raster, or 3D model object


Working with Vector Layers
--------------------------

Get a specific vector layer by searching for its name, then retrieve its features and fields:

Sync:

.. code-block:: python

    from geobox import GeoboxClient

    client = GeoboxClient()
    # Search for a layer by name
    layer = client.get_vectors(search='layer_name')[0]
    
    # Get features and fields
    features = layer.get_features()
    fields = layer.get_fields()


Async:

.. code-block:: python

    from geobox.aio import AsyncGeoboxClient

    async with AsyncGeoboxClient() as client:
        # Search for a layer by name
        layer = await client.get_vectors(search='layer_name')[0]

        # Get features and fields
        features = await layer.get_features()
        fields = await layer.get_fields()

For more information on working with vector layers, check `Vector Layer documentation <modules/vectorlayer.html#vector-layer>`_ and `Async Vector Layer documentation <async_modules/vectorlayer.html#vector-layer>`_.

Creating and Executing SQL Queries
----------------------------------

Create a query to extract data from a layer using SQL:

Sync:

.. code-block:: python

    from geobox import GeoboxClient
    from geobox.query import QueryParamType
    
    client = GeoboxClient()
    # Get a specific layer by UUID
    layer = client.get_vector(uuid='layer_uuid')
    
    # Create a new query
    query = client.create_query(name='feature_count')
    query.sql = 'SELECT COUNT(id) FROM layer'
    
    # Add parameters to the query
    query.add_param(name='layer', value=layer.uuid, type=QueryParamType.LAYER)
    
    # Execute the query
    query.execute()


Async:

.. code-block:: python

    from geobox.aio import AsyncGeoboxClient
    from geobox.aio.query import QueryParamType
    
    async with AsyncGeoboxClient() as client:
        # Get a specific layer by UUID
        layer = await client.get_vector(uuid='layer_uuid')

        # Create a new query
        query = await client.create_query(name='feature_count')
        query.sql = 'SELECT COUNT(id) FROM layer'

        # Add parameters to the query
        query.add_param(name='layer', value=layer.uuid, type=QueryParamType.LAYER)

        # Execute the query
        result = await query.execute()

For more information on queries, check `Query documentation <modules/query.html#query>`_ and `Async Query documentation <async_modules/query.html#query>`_.


Vector Processing Tools and Raster Analysis
-------------------------------------------

You can perform different analysis on vector layers and rasters.

Sync - Execute the vector tool:


.. code-block:: python

    from geobox import GeoboxClient
    
    client = GeoboxClient()
    # Get a specific layer by UUID
    layer = client.get_vector(uuid='layer_uuid')
    
    # add buffer to the layer
    # execute
    result = client.vector_tool.buffer(
        vector_uuid=layer.uuid,
        distance=1000
    ) 

or execute and save the result as a new layer:

.. code-block:: python

    # save as new layer
    task = client.vector_tool.buffer(
        vector_uuid=layer.uuid,
        distance=1000,
        output_asset='buffered_layer'
    ) 
    task.wait()
    output_layer = task.output_asset


Async - Execute the vector tool:

.. code-block:: python

    from geobox.aio import AsyncGeoboxClient
    
    async with AsyncGeoboxClient() as client:
        # Get a specific layer by UUID
        layer = await client.get_vector(uuid='layer_uuid')

        # add buffer to the layer
        # execute
        result = await client.vector_tool.buffer(
            vector_uuid=layer.uuid,
            distance=1000
        ) 

or execute and save the result as a new layer:

.. code-block:: python

        # save as new layer
        task = await client.vector_tool.buffer(
            vector_uuid=layer.uuid,
            distance=1000,
            output_asset='buffered_layer'
        )
        task.wait()
        output_layer = await task.output_asset