Commit 5c18e55c authored by Morten Ofstad's avatar Morten Ofstad Committed by Morten Ofstad
Browse files

Added getting-started guide and set up example code to compile.

parent aa1d5cd0
Pipeline #495 passed with stages
in 18 minutes and 4 seconds
...@@ -58,6 +58,7 @@ add_custom_command(OUTPUT ${SPHINX_INDEX_FILE} ...@@ -58,6 +58,7 @@ add_custom_command(OUTPUT ${SPHINX_INDEX_FILE}
DEPENDS DEPENDS
# Other docs files you want to track should go here (or in some variable) # Other docs files you want to track should go here (or in some variable)
${CMAKE_CURRENT_SOURCE_DIR}/index.rst ${CMAKE_CURRENT_SOURCE_DIR}/index.rst
${CMAKE_CURRENT_SOURCE_DIR}/getting-started.rst
MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py MAIN_DEPENDENCY ${SPHINX_SOURCE}/conf.py
COMMENT "Generating documentation with Sphinx") COMMENT "Generating documentation with Sphinx")
......
.. _getting-started:
Getting Started Tutorial
************************
This tutorial walks you through opening an existing VDS and requesting a slice of data from it.
Opening a VDS
-------------
To open a VDS we set up the :cpp:struct:`OpenOptions` for the object store the VDS is in, we will use AWS for this tutorial so we need to set up the :cpp:struct:`AWSOpenOptions`:
.. code-block:: cpp
OpenVDS::AWSOpenOptions options;
options.region = TEST_AWS_REGION;
options.bucket = TEST_AWS_BUCKET;
options.key = TEST_AWS_OBJECTID;
We will then call :cpp:func:`Open` to get the :cpp:type:`VDSHandle`:
.. code-block:: cpp
OpenVDS::Error error;
OpenVDS::VDSHandle handle = OpenVDS::Open(options, error);
if(error.code != 0)
{
std::cerr << "Could not open VDS: " << error.string << std::endl;
exit(1);
}
If everything went well we can now get the :cpp:class:`VolumeDataAccessManager` that we will use to request data from the VDS and the :cpp:class:`VolumeDataLayout` that we can use to get information about the layout of the VDS:
.. code-block:: cpp
OpenVDS::VolumeDataAccessManager *accessManager = OpenVDS::GetAccessManager(handle);
OpenVDS::VolumeDataLayout *layout = OpenVDS::GetLayout(handle);
Using the VolumeDataLayout
-------------
We can now use the VolumeDataLayout to find the inline number in the middle of the dataset and transform that inline number to an index in the VDS data:
.. code-block:: cpp
const int sampleDimension = 0, crosslineDimension = 1, inlineDimension = 2;
OpenVDS::VolumeDataAxisDescriptor inlineAxisDescriptor = layout->GetAxisDescriptor(inlineDimension);
int inlineNumber = int((inlineAxisDescriptor.GetCoordinateMin() + inlineAxisDescriptor.GetCoordinateMax()) / 2);
int inlineIndex = inlineAxisDescriptor.CoordinateToSampleIndex((float)inlineNumber);
The VolumeDataLayout can be used to find out which data channels are available, the names and units of channels and axes, the estimated value range and data types for the channels and the metadata of the VDS (containing e.g. the UTM coordinates).
Requesting a slice of data from a VDS
-------------
To request data we need to set up the index region that we want to read:
.. code-block:: cpp
int voxelMin[OpenVDS::Dimensionality_Max] = { 0, 0, 0, 0, 0, 0};
int voxelMax[OpenVDS::Dimensionality_Max] = { 1, 1, 1, 1, 1, 1};
voxelMin[sampleDimension] = 0;
voxelMax[sampleDimension] = layout->GetDimensionNumSamples(sampleDimension);
voxelMin[crosslineDimension] = 0;
voxelMax[crosslineDimension] = layout->GetDimensionNumSamples(crosslineDimension);
voxelMin[inlineDimension] = inlineIndex;
voxelMax[inlineDimension] = inlineIndex + 1;
Then we can make the request for data:
.. code-block:: cpp
std::vector<float> buffer(layout->GetDimensionNumSamples(sampleDimension) * layout->GetDimensionNumSamples(crosslineDimension));
int64_t iRequestID = accessManager->RequestVolumeSubset(buffer.data(), layout, OpenVDS::Dimensions_012, 0, 0, voxelMin, voxelMax, OpenVDS::VolumeDataChannelDescriptor::Format_R32);
Because all requests in OpenVDS are asynchronous we need to wait for the request to complete before we can access the data in the buffer:
.. code-block:: cpp
bool success = accessManager->WaitForCompletion(iRequestID);
The complete code for this tutorial can be found in examples/GettingStarted.
...@@ -7,10 +7,10 @@ Welcome to OpenVDS's documentation! ...@@ -7,10 +7,10 @@ Welcome to OpenVDS's documentation!
=================================== ===================================
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
:caption: Contents: :caption: Contents:
getting-started
Indices and tables Indices and tables
================== ==================
...@@ -20,7 +20,7 @@ Indices and tables ...@@ -20,7 +20,7 @@ Indices and tables
* :ref:`search` * :ref:`search`
API Reference API Reference
==== =============
.. doxygenclass:: OpenVDS::VolumeDataAccessManager .. doxygenclass:: OpenVDS::VolumeDataAccessManager
:members: :members:
add_subdirectory(SliceDump) add_subdirectory(SliceDump)
add_subdirectory(GettingStarted)
add_executable(getting-started main.cpp)
target_link_libraries(getting-started openvds)
set_target_properties(getting-started PROPERTIES FOLDER examples)
target_compile_definitions(getting-started PRIVATE -DTEST_AWS_REGION="${TEST_AWS_REGION}")
target_compile_definitions(getting-started PRIVATE -DTEST_AWS_BUCKET="${TEST_AWS_BUCKET}")
target_compile_definitions(getting-started PRIVATE -DTEST_AWS_OBJECTID="${TEST_AWS_OBJECTID}")
copyDllForTarget(getting-started)
#include <OpenVDS/OpenVDS.h>
#include <OpenVDS/VolumeDataLayout.h>
#include <OpenVDS/VolumeDataAccess.h>
#include <iostream>
int main(int argc, char *argv[])
{
OpenVDS::AWSOpenOptions options;
options.region = TEST_AWS_REGION;
options.bucket = TEST_AWS_BUCKET;
options.key = TEST_AWS_OBJECTID;
OpenVDS::Error error;
OpenVDS::VDSHandle handle = OpenVDS::Open(options, error);
if(error.code != 0)
{
std::cerr << "Could not open VDS: " << error.string << std::endl;
exit(1);
}
OpenVDS::VolumeDataAccessManager *accessManager = OpenVDS::GetAccessManager(handle);
OpenVDS::VolumeDataLayout *layout = OpenVDS::GetLayout(handle);
const int sampleDimension = 0, crosslineDimension = 1, inlineDimension = 2;
OpenVDS::VolumeDataAxisDescriptor inlineAxisDescriptor = layout->GetAxisDescriptor(inlineDimension);
int inlineNumber = int((inlineAxisDescriptor.GetCoordinateMin() + inlineAxisDescriptor.GetCoordinateMax()) / 2);
int inlineIndex = inlineAxisDescriptor.CoordinateToSampleIndex((float)inlineNumber);
int voxelMin[OpenVDS::Dimensionality_Max] = { 0, 0, 0, 0, 0, 0};
int voxelMax[OpenVDS::Dimensionality_Max] = { 1, 1, 1, 1, 1, 1};
voxelMin[sampleDimension] = 0;
voxelMax[sampleDimension] = layout->GetDimensionNumSamples(sampleDimension);
voxelMin[crosslineDimension] = 0;
voxelMax[crosslineDimension] = layout->GetDimensionNumSamples(crosslineDimension);
voxelMin[inlineDimension] = inlineIndex;
voxelMax[inlineDimension] = inlineIndex + 1;
std::vector<float> buffer(layout->GetDimensionNumSamples(sampleDimension) * layout->GetDimensionNumSamples(crosslineDimension));
int64_t iRequestID = accessManager->RequestVolumeSubset(buffer.data(), layout, OpenVDS::Dimensions_012, 0, 0, voxelMin, voxelMax, OpenVDS::VolumeDataChannelDescriptor::Format_R32);
bool success = accessManager->WaitForCompletion(iRequestID);
}
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment