1# GDAL Raster to GeoTIFF Workflow Sandbox 2This repository is an example of how Sandboxed API can be used with GDAL C Raster API to implement the creation of the GeoTIFF dataset inside the sandbox. 3 4## Workflow details 5Implemented workflow consists of a few steps: 61. Register needed drivers inside the sandbox 72. Get specific driver by name (GTiff) 83. Map output file inside the sandbox and create a GeoTIFF dataset backed by this file 94. Set affine transformation coefficients if needed 105. Set projection reference string if needed 116. Write raster bands data to the dataset using RasterIO 12 1. Set No data value if needed 137. Clean up data and close the dataset 14 15## Implementation details 16This project consists of a CMake file that shows how you can connect Sandboxed API and GDAL, a raster data parser using unsandboxed GDAL to generate sample input for the sandboxed workflow, sample sandbox policy that could work with GeoTIFF files without any violations, command-line utility that uses sandboxed GDAL to implement the workflow and GoogleTest unit tests to compare raster data of original datasets with the raster data of datasets that have been created inside the sandbox. 17 18## Build GDAL sandbox 19Because GDAL doesn't use CMake or Bazel it's required to have a static build of libgdal and libproj. Moreover, proj.db file path is required to be able to map it inside the sandbox and use it internally for some of the projections. 20 21### Build GDAL and PROJ from sources 22To get the latest version of both GDAL and PROJ you will need to build them from sources. To make a clean installation you can use the build folder as an installation path, with this approach you won't affect any system files and will be able to easily delete everything later. 23First, you will need to build PROJ, which is used internally in the GDAL. You can't use the libproj-dev package because it contains an outdated version, while GDAL requires a more recent one. 24To [install PROJ from sources](https://proj.org/install.html#compilation-and-installation-from-source-code) you can do the following: 25``` 26mkdir build && cd build 27wget https://download.osgeo.org/proj/proj-7.1.1.tar.gz 28tar xvzf proj-7.1.1.tar.gz 29mkdir proj_build 30cd proj-7.1.1 31./configure --prefix=/path/to/build/proj_build 32make -j8 33make install 34make check 35``` 36The static version of libproj will be available at `proj_build/lib/libproj.a`. 37Then, you can start [GDAL installation](https://trac.osgeo.org/gdal/wiki/BuildingOnUnix): 38``` 39cd build 40git clone https://github.com/OSGeo/gdal 41mkdir gdal_build 42cd gdal/gdal 43./configure --prefix=/path/to/build/gdal_build --with-proj=/path/to/build/proj_build 44make -j8 45make install 46``` 47To verify that everything is installed correctly you can run gdalinfo utility. 48``` 49cd ../../gdal_build/bin/ 50./gdalinfo --version 51``` 52The static version of libgdal will be available at `gdal_build/lib/libgdal.a`. 53You will need to specify paths to those static libraries as the CMake arguments to build the project. Also, the Sandboxed API generator needs `gdal.h` header, which is located at `build/gdal/gdal/gcore/gdal.h`. 54 55### Build sandboxed GDAL 56To build the examples from this repository you can use CMake in the following way: 57``` 58mkdir build 59cd build 60cmake .. -G Ninja -DSAPI_ROOT=/path/to/sapi 61``` 62This build expects `lib/` folder with both `libgdal.a` and `libproj.a` to be present near the source files. 63Also, you need to have `gdal.h` header so Sandboxed API generator could parse it, the default expected path to it is `/usr/local/include`. 64Finally, you could enable tests with the `-DENABLE_TESTS=ON` option for the CMake. 65You can specify those paths as a CMake argument, so the complete example looks like this: 66``` 67mkdir build 68cd build 69cmake .. -G Ninja -DSAPI_ROOT=/path/to/sapi \ 70-DGDAL_HEADER_PREFIX=/path/to/gdal/header \ 71-DLIBGDAL_PREFIX=/path/to/libgdal_static_build \ 72-DLIBPROJ_PREFIX=/path/to/libproj_static_build \ 73-DENABLE_TESTS=ON 74``` 75After CMake build is completed, you can run `ninja` to build the executables. 76 77## Examples 78PROJ uses `proj.db` database to work correctly with different transformations and you will need to map it to the sandbox manually to be able to retrieve it in the restricted environment. After the installation you can find `proj.db` in `/path/to/proj/share/proj/proj.db`. 79 80You can use environment variables to set path to proj: 81``` 82export PROJ_DB_PATH=/path/to/proj.db 83``` 84The code will check this variable and if it represents a valid file it will be mounted inside the sandbox. 85Alternatively, if there is no such environment variable program will try to use the default path `/usr/local/share/proj/proj.db`. 86There is a simple command-line utility that takes path to the GeoTIFF file and absolute path to the output file as arguments, parses raster data from the input file and, re-creates the same GeoTIFF file (except some metadata) inside the sandbox. 87 88You can run it in the following way: 89``` 90./raster_to_gtiff path/to/input.tif /absolute/path/to/output.tif 91``` 92After that, you can compare both files using the `gdalinfo` utility. 93Also, there are unit tests that automatically convert a few files and then compare input and output raster data to make sure that they are equal. 94To run tests your CMake build must use `-DENABLE_TESTS=ON`, then you can run tests using `ctest`. 95Note that it will also run Sandboxed API related tests. To run tests manually you will need to specify a few environmental variables and then run `tests` executable. 96``` 97export TEST_TMPDIR=/tmp/ 98export TEST_SRCDIR=/path/to/project/source 99``` 100 101All test data is from [osgeo samples](http://download.osgeo.org/geotiff/samples/). 102