## 1. Project Overview & Quickstart (OpenDroneMap/ODM) ## File: README.md An open source command line toolkit for processing aerial drone imagery. ODM turns simple 2D images into: - Classified Point Clouds - 3D Textured Models - Georeferenced Orthorectified Imagery - Georeferenced Digital Elevation Models The application is available for Windows, Mac and Linux and it works from the command line, making it ideal for power users, scripts and for integration with other software. If you would rather not type commands in a shell and are looking for a friendly user interface, check out [OpenDroneMap Desktop](https://opendronemap.org/download). ## Quickstart The easiest way to run ODM is via docker. To install docker, see [docs.docker.com](https://docs.docker.com). Once you have docker installed and [working](https://docs.docker.com/get-started/#test-docker-installation), you can get ODM by running from a Command Prompt / Terminal: ```bash docker pull opendronemap/odm ``` Run ODM by placing some images (JPEGs, TIFFs or DNGs) in a folder named “images” (for example `C:\Users\youruser\datasets\project\images` or `/home/youruser/datasets/project/images`) and simply run from a Command Prompt / Terminal: ```bash # Windows docker run -ti --rm -v c:/Users/youruser/datasets:/datasets opendronemap/odm --project-path /datasets project ``` ```bash # Mac/Linux docker run -ti --rm -v /home/youruser/datasets:/datasets opendronemap/odm --project-path /datasets project ``` You can pass [additional parameters](https://docs.opendronemap.org/arguments/) by appending them to the command: ```bash docker run -ti --rm -v /datasets:/datasets opendronemap/odm --project-path /datasets project [--additional --parameters --here] ``` For example, to generate a DSM (`--dsm`) and increase the orthophoto resolution (`--orthophoto-resolution 2`) : ```bash docker run -ti --rm -v /datasets:/datasets opendronemap/odm --project-path /datasets project --dsm --orthophoto-resolution 2 ``` ## Viewing Results When the process finishes, the results will be organized as follows: |-- images/ |-- img-1234.jpg |-- ... |-- opensfm/ |-- see mapillary/opensfm repository for more info |-- odm_meshing/ |-- odm_mesh.ply # A 3D mesh |-- odm_texturing/ |-- odm_textured_model.obj # Textured mesh |-- odm_textured_model_geo.obj # Georeferenced textured mesh |-- odm_georeferencing/ |-- odm_georeferenced_model.laz # LAZ format point cloud |-- odm_orthophoto/ |-- odm_orthophoto.tif # Orthophoto GeoTiff You can use the following free and open source software to open the files generated in ODM: - .tif (GeoTIFF): [QGIS](http://www.qgis.org/) - .laz (Compressed LAS): [CloudCompare](https://www.cloudcompare.org/) - .obj (Wavefront OBJ), .ply (Stanford Triangle Format): [MeshLab](http://www.meshlab.net/) > **Note:** Opening the .tif files generated by ODM in programs such as Photoshop or GIMP might not work (they are GeoTIFFs, not plain TIFFs). Use [QGIS](http://www.qgis.org/) instead. ## API ODM can be made accessible from a network via [NodeODM](https://github.com/OpenDroneMap/NodeODM). ## Documentation See http://docs.opendronemap.org for tutorials and more guides. ## Forum We have a vibrant [community forum](https://community.opendronemap.org/). You can [search it](https://community.opendronemap.org/search?expanded=true) for issues you might be having with ODM and you can post questions there. We encourage users of ODM to participate in the forum and to engage with fellow drone mapping users. ## Windows Setup ODM can be installed natively on Windows. Just download the latest setup from the [releases](https://github.com/OpenDroneMap/ODM/releases) page. After opening the ODM Console you can process datasets by typing: ```bash run C:\Users\youruser\datasets\project [--additional --parameters --here] ``` ## GPU Acceleration ODM has support for doing SIFT feature extraction on a GPU, which is about 2x faster than the CPU on a typical consumer laptop. To use this feature, you need to use the `opendronemap/odm:gpu` docker image instead of `opendronemap/odm` and you need to pass the `--gpus all` flag: ```bash docker run -ti --rm -v c:/Users/youruser/datasets:/datasets --gpus all opendronemap/odm:gpu --project-path /datasets project --feature-type sift ``` When you run ODM, if the GPU is recognized, in the first few lines of output you should see: ``` [INFO] Writing exif overrides [INFO] Maximum photo dimensions: 4000px [INFO] Found GPU device: Intel(R) OpenCL HD Graphics [INFO] Using GPU for extracting SIFT features ``` The SIFT GPU implementation is CUDA-based, so should work with most NVIDIA graphics cards of the GTX 9xx Generation or newer. If you have an NVIDIA card, you can test that docker is recognizing the GPU by running: ```bash docker run --rm --gpus all nvidia/cuda:10.0-base nvidia-smi ``` If you see an output that looks like this: ``` Fri Jul 24 18:51:55 2020 +-----------------------------------------------------------------------------+ | NVIDIA-SMI 440.82 Driver Version: 440.82 CUDA Version: 10.2 | |-------------------------------+----------------------+----------------------+ | GPU Name Persistence-M| Bus-Id Disp.A | Volatile Uncorr. ECC | | Fan Temp Perf Pwr:Usage/Cap| Memory-Usage | GPU-Util Compute M. | ``` You're in good shape! See https://github.com/NVIDIA/nvidia-docker and https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker for information on docker/NVIDIA setup. ## Video Support Starting from version 3.0.4, ODM can automatically extract images from video files (.mp4, .mov, .lrv, .ts). Just place one or more video files into the `images` folder and run the program as usual. Subtitles files (.srt) with GPS information are also supported. Place .srt files in the `images` folder, making sure that the filenames match. For example, `my_video.mp4` ==> `my_video.srt` (case-sensitive). ## Developers Help improve our software! We welcome contributions from everyone, whether to add new features, improve speed, fix existing bugs or add support for more cameras. Check our [code of conduct](https://github.com/OpenDroneMap/documents/blob/master/CONDUCT.md), the [contributing guidelines](https://github.com/OpenDroneMap/documents/blob/master/CONTRIBUTING.md) and [how decisions are made](https://github.com/OpenDroneMap/documents/blob/master/GOVERNANCE.md#how-decisions-are-made). ### Installation and first run #### Dependencies Install [pixi](https://pixi.sh), (or use the [devcontainer](https://containers.dev/)): **MSVC and the Windows SDK come from a host install** of Visual Studio 2022 or Build Tools ([conda-forge Windows native notes](https://conda-forge.org/docs/how-to/advanced/windows/notes-on-native-code/)): - Desktop development with C++ - Windows 10/11 SDK #### Build and test ```bash pixi install --locked pixi run build pixi run test pixi run smoke ``` #### Process a dataset Process a dataset (from the repo root, with a pixi shell or `pixi run`): ```bash pixi run odm -- --project-path ~/datasets mydataset # or, after: eval "$(pixi shell-hook)" ./run.py --project-path ~/datasets mydataset ``` GPU builds use the `gpu` environment: `pixi install -e gpu && pixi run -e gpu build`. ## Advanced ### Build Docker images from source CPU image (matches CI): ```bash pixi run docker-build ``` GPU image: ```bash pixi run docker-build -- --gpu ``` These stamp the image with the OCI labels (revision, version, created) and tag it `opendronemap/odm:latest` (`:gpu`) on master, or `opendronemap/odm:` off master. Pass a custom tag or extra `docker build` flags after `--`, e.g. `pixi run docker-build -- -t my_odm_image --no-cache`. If you have questions, join the developer's chat at https://community.opendronemap.org/c/developers-chat/21 1. Try to keep commits clean and simple 2. Submit a pull request with detailed changes and test results 3. Have fun! ## Credits ODM makes use of [several libraries](https://github.com/OpenDroneMap/ODM/blob/master/pixi.toml) and other awesome open source projects to perform its tasks. Among them we'd like to highlight: - [OpenSfM](https://github.com/mapillary/OpenSfM) - [OpenMVS](https://github.com/cdcseacave/openMVS/) - [PDAL](https://github.com/PDAL/PDAL) - [Entwine](https://entwine.io/) - [MVS Texturing](https://github.com/nmoehrle/mvs-texturing) - [GRASS GIS](https://grass.osgeo.org/) - [GDAL](https://gdal.org/) - [PoissonRecon](https://github.com/mkazhdan/PoissonRecon) ## Citation > _OpenDroneMap Authors_ ODM - A command line toolkit to generate maps, point clouds, 3D models and DEMs from drone, balloon or kite images. **OpenDroneMap/ODM GitHub Page** 2020; [https://github.com/OpenDroneMap/ODM](https://github.com/OpenDroneMap/ODM) ## Trademark See [Trademark Guidelines](https://github.com/OpenDroneMap/documents/blob/master/TRADEMARK.md) --- ## File: contrib/visveg/readme.md # Visible Vegetation Indexes This script produces a Vegetation Index raster from a RGB orthophoto (odm_orthophoto.tif in your project) ## Requirements * rasterio (pip install rasterio) * numpy python package (included in ODM build) ## Usage ``` vegind.py index positional arguments: The RGB orthophoto. Must be a GeoTiff. index Index identifier. Allowed values: ngrdi, tgi, vari ``` Output will be generated with index suffix in the same directory as input. ## Examples `python vegind.py /path/to/odm_orthophoto.tif tgi` Orthophoto photo of Koniaków grass field and forest in QGIS: The Triangular Greenness Index output in QGIS (with a spectral pseudocolor): Visible Atmospheric Resistant Index: Normalized green-red difference index: ## Bibliography 1. Hunt, E. Raymond, et al. "A Visible Band Index for Remote Sensing Leaf Chlorophyll Content At the Canopy Scale." ITC journal 21(2013): 103-112. doi: 10.1016/j.jag.2012.07.020 (https://doi.org/10.1016/j.jag.2012.07.020) --- ## File: contrib/time-sift/README.md # Plugin Time-SIFT This script does Time-SIFT processing with ODM. Time-SIFT is a method for multi-temporal analysis without the need to co-registrate the data. > D. Feurer, F. Vinatier, Joining multi-epoch archival aerial images in a single SfM block allows 3-D change detection with almost exclusively image information, ISPRS Journal of Photogrammetry and Remote Sensing, Volume 146, 2018, Pages 495-506, ISSN 0924-2716, doi: 10.1016/j.isprsjprs.2018.10.016 (https://doi.org/10.1016/j.isprsjprs.2018.10.016) ## Requirements * ODM ! :-) * subprocess * json * os * shutil * pathlib * sys * argparse * textwrap ## Usage ### Provided example Download or clone [this repo](https://forge.inrae.fr/Denis.Feurer/timesift-odm-data-example.git) to get example data. Then execute ``` python Timesift_odm.py datasets --end-with odm_filterpoints ``` It should make the Time-SIFT processing on the downloaded example data, stopping after the filtered dense clouds step. In the destination dir, you should obtain new directories, ```0_before``` and ```1_after``` at the same level as the ```time-sift-block``` directory. These new directories contain all the results natively co-registered. You can then use [CloudCompare](https://cloudcompare.org/) to compute distance between the ```datasets/0_before/odm_filterpoints/point_cloud.ply``` and the ```datasets/1_after/odm_filterpoints/point_cloud.ply``` and obtain this image showing the difference between the two 3D surfaces. Here, two soil samples were excavated as can be seen on the image below. ### Your own data In your dataset directory (usually ```datasets```, but you can have chosen another name) you have to prepare a Time-SIFT project directory (default name : ```time-sift-block```, *can be tuned via a parameter*) that contains : * ```images/``` : a subdirectory with all images of all epochs. This directory name is fixed as it is the one expected by ODM * ```images_epochs.txt``` : a file that has the same format as the file used for the split and merge ODM function. This file name *can be tuned via a parameter*. The ```images_epochs.txt``` file has two columns, the first column contains image names and the second contains the epoch name as follows ``` DSC_0368.JPG 0_before DSC_0369.JPG 0_before DSC_0370.JPG 0_before DSC_0389.JPG 1_after DSC_0390.JPG 1_after DSC_0391.JPG 1_after ``` Your directory, before running the script, should look like this : ``` $PWD/datasets/ └── time-sift-block/ ├── images/ └── images_epochs.txt ``` At the end of the script you obtain a directory by epoch (at the same level as the Time-SIFT project directory). Each directory is processed with images of each epoch and all results are natively co-registered due to the initial sfm step done with all images. ``` $PWD/datasets/ ├── 0_before/ ├── 1_after/ └── time-sift-block/ ``` --- ## File: contrib/resize/README.md # Resize Resize a dataset (and optional GCP file). Resizes images, keeps Exif data. The EXIF width and height attributes will be updated accordingly also. ODM GCP files are scaled also. Usage: ``` pip install -r requirements.txt python3 resize.py -i images/ -o resized/ 25% python3 resize.py -i images/1.JPG -o resized.JPG 25% python3 resize.py -i gcp_list.txt -o resized_gcp_list.txt ``` Originally forked from https://github.com/pierotofy/exifimageresize --- ## File: contrib/pc2dem/README.md # Point Cloud To DEM Convert point clouds (LAS, LAZ, PLY, and any other format compatible with [PDAL](https://pdal.io/stages/readers.html)) to GeoTIFF elevation models. This tool includes methods to perform efficient and scalable gapfill interpolation and is the same method used by ODM's processing pipeline. It is offered here as a standalone module for processing individual point clouds. ## Usage ``` docker run -ti --rm -v /home/youruser/folder_with_point_cloud:/input opendronemap/odm python3 /code/contrib/pc2dem/pc2dem.py /input/point_cloud.las [flags] ``` The result (`dsm.tif` or `dtm.tif`) will be stored in the same folder as the input point cloud. See additional `flags` you can pass at the end of the command above: ``` usage: pc2dem.py [-h] [--type {dsm,dtm}] [--resolution RESOLUTION] [--gapfill-steps GAPFILL_STEPS] point_cloud Generate DEMs from point clouds using ODM's algorithm. positional arguments: point_cloud Path to point cloud file (.las, .laz, .ply) optional arguments: -h, --help show this help message and exit --type {dsm,dtm} Type of DEM. Default: dsm --resolution RESOLUTION Resolution in m/px. Default: 0.05 --gapfill-steps GAPFILL_STEPS Number of steps used to fill areas with gaps. Set to 0 to disable gap filling. Starting with a radius equal to the output resolution, N different DEMs are generated with progressively bigger radius using the inverse distance weighted (IDW) algorithm and merged together. Remaining gaps are then merged using nearest neighbor interpolation. Default: 3 ``` --- ## File: contrib/orthorectify/README.md # Orthorectification Tool This tool is capable of orthorectifying individual images (or all images) from an existing ODM reconstruction. ## Usage After running a reconstruction using ODM: ``` docker run -ti --rm -v /home/youruser/datasets:/datasets opendronemap/odm --project-path /datasets project ``` You can run the orthorectification module by running: ``` docker run -ti --rm -v /home/youruser/datasets:/datasets opendronemap/odm bash /code/contrib/orthorectify/run.sh /datasets/project ``` This will start the orthorectification process for all images in the dataset. See additional flags you can pass at the end of the command above: ``` usage: orthorectify.py [-h] [--dem DEM] [--no-alpha NO_ALPHA] [--interpolation {nearest,bilinear}] [--outdir OUTDIR] [--image-list IMAGE_LIST] [--images IMAGES] [--threads THREADS] [--skip-visibility-test SKIP_VISIBILITY_TEST] dataset Orthorectification Tool positional arguments: dataset Path to ODM dataset optional arguments: -h, --help show this help message and exit --dem DEM Absolute path to DEM to use to orthorectify images. Default: odm_dem/dsm.tif --no-alpha NO_ALPHA Don't output an alpha channel --interpolation {nearest,bilinear} Type of interpolation to use to sample pixel values.Default: bilinear --outdir OUTDIR Output directory where to store results. Default: orthorectified --image-list IMAGE_LIST Path to file that contains the list of image filenames to orthorectify. By default all images in a dataset are processed. Default: img_list.txt --images IMAGES Comma-separated list of filenames to rectify. Use as an alternative to --image- list. Default: process all images. --skip-visibility-test SKIP_VISIBILITY_TEST Skip visibility testing (faster but leaves artifacts due to relief displacement) ``` ## Roadmap Help us improve this module! We could add: - [ ] GPU support for faster processing - [ ] Merging of multiple orthorectified images (blending, filtering, seam leveling) - [ ] Faster visibility test - [ ] Different methods for orthorectification (direct) --- ## File: contrib/ndvi/README.md # NDVI This script produces a NDVI raster from a CIR orthophoto (odm_orthophoto.tif in your project) ## Requirements * python_gdal package from apt * numpy python package (included in ODM build) ## Usage ``` ndvi.py [-h] [--overwrite] N N positional arguments: The CIR orthophoto. Must be a GeoTiff. N NIR band number N Vis band number The output file. Also must be in GeoTiff format optional arguments: -h, --help show this help message and exit --overwrite, -o Will overwrite output file if it exists. ``` **Argument order matters! NIR first, then VIS** ## Examples: Use the [Seneca](https://github.com/OpenDroneMap/odm_data_seneca) dataset for a good working CIR. The band order for that set is NIR-G-B, so you will want to use bands 1 and 2 for this script. After running ODM, the command goes as follows: `python ndvi.py /path/to/odm_orthophoto.tif 1 2 /path/to/ndvi.tif` The output in QGIS (with a spectral pseudocolor): --- ## File: contrib/mergepreview/README.md # Merge Preview Quickly projects drone images on a map by using georeferencing, camera angles and a global DTM. The images are then merged using ODM's split-merge algorithms. Quality is obviously not good, works only for nadir-only images and requires the images to have gimbal/camera angle information (not all drones provide this information). Usage: ``` # Install DDB (required for geoprojection) curl -fsSL https://get.dronedb.app -o get-ddb.sh sh get-ddb.sh # Run python3 mergepreview.py -i images/*.JPG --size 25% ``` ## Example [Sheffield Park](https://community.opendronemap.org/t/sheffield-park-1/58) images processed with this script. ## Disclaimer This script is highly experimental. We welcome contributions to improve it. --- ## File: contrib/mask-duplicator/README.md # Semi-automated Masking for 360 images For usage with 360 images and Open Drone Map (ODM) to mask out the tripod/user/camera mount. 360 models in ODM can be made from 360 images, but unless you mask out the camera mount there will be repeated artifacts along the camera path. ODM supports image masking but requires a mask for each image. Since the 360 camera is generally on a fixed mount (bike helmet, moving tripod, etc), you can make one mask and then duplicate this for all images, but this is tedious to do by hand. This snippet takes the file path of a single image mask and duplicates it for all images in the dataset. After creating the masks, process the original images and the masks together in ODM you'll get a clean model with the camera mount artifacts eliminated. Before using this code snippet, open one of your 360 images in an image editor and mask out the helmet or tripod, etc at the bottom of your image. Save this image as a png and then use it as the mask image that will be duplicated for all images in the dataset. See https://docs.opendronemap.org/masks/ for more details on mask creation. --- ## File: contrib/grass/README.md # GRASS scripts # odm_grass Generates contour and textured relief maps. ## Requirements * Compile and install GRASS 7 version or higher, https://grasswiki.osgeo.org/wiki/Compile_and_Install * Environment variables: * PYTHONHOME set to the location of Python * PYTHONPATH set to the location of GRASS Python libs * PATH includes GRASS bin and lib directories * GISBASE set to the location of GRASS ## Usage python odm_grass.py Output is `/odm_georeferencing/odm_contour.shp` and `/odm_orthophoto/odm_relief.tif`. ## 2. Official Technical Reference & Guides (OpenDroneMap/ODM-docs) # OpenDroneMap Docs Contribute to [OpenDroneMap](https://docs.opendronemap.org)'s documentation!!! Anyone is welcome to share their knowledge and improve our documentation. 🎉 And it's pretty simple too! # "But I don't know if I can contribute" Even if you think your contribution might not be valuable, it might be for other users! If you discovered something remotely useful to you, it probably is very useful to others! :) Tips, tricks, hacks, datasets, lessons learned, best practices, every bit helps. We want to know! Share it. # How To Make Your First Contribution If you don't have a GitHub account, [register](https://github.com/join?source=header-home) first. It's free and GitHub is awesome !!! Once you have an account there are two ways to contribute. One is quick for small changes, the second takes a bit longer to setup but makes writing long parts of documentation much quicker. # The Quick Method Browse to https://github.com/OpenDroneMap/docs/tree/publish/source. Each row in the table corresponds to a page in the documentation. Tap on the file name, in the second (2nd) column from left. Press the "Edit" icon. Make your changes, then scroll down and tap the "Propose Changes" button. When the next page is displayed, tap the "Create pull request" button. Wait for your changes to be approved! That's it! You may want to read the English Style Guide for github https://github.com/raywenderlich/english-style-guide. # The Pro Method For quick changes the method above is quick and fast. But if you want to write docs like a pro, in your own text editor of choice, follow these steps. Depending on your operating system, you should follow these steps to create a local copy of the documentation. This way you can modify and check the results before sending them for review. You may want to read the English Style Guide for github https://github.com/raywenderlich/english-style-guide. ## Step 1. Make a Copy (fork) This Repository Press the "Fork" button at the top of this page. ## Step 2. Install Git and Python 3 As there is an issue with python3.13 [(https://github.com/ethereum/s……olidity/issues/15811) with ](https://github.com/ethereum/solidity/issues/15811) python3.12 at most should be used. ### Linux: ```bash sudo apt-get install -y git python3 python3-pip ``` ### MacOS We recommend to use [Brew](https://brew.sh/) for installing Python3. ```bash brew install python3 ``` Git comes preinstalled on MacOS. ### Windows Download Git from https://git-scm.com/download/win and Python 3 from https://www.python.org/downloads/windows/ ## Step 3. Make A Local Copy of The Documentation Open a Terminal (or a command prompt). In Windows you open a command prompt by pressing the Window Key and typing "Command Prompt" then Enter. Then run (replacing "yourusername" with your GitHub username): ```bash git clone https://github.com/yourusername/docs ``` If it's your first time using git, also run: ``` git config --global user.name "Your Name" git config --global user.email "your@email.com" ``` With your information. So that we can credit the contributions to you. ## Step 4. Get The Documentation Running From the same Terminal (or command prompt) run the following: ``` cd docs/ python3.12 -m venv .venv # Linux/Mac source .venv/bin/activate # Windows .venv\scripts\activate pip install -r requirements.txt ``` After running `source .venv/bin/activate` there should be some indication that the Python virtual environment is active (see the `(.venv)` that appears at the start of terminal prompt in the screengrab below). **Note:** The next time you can `cd` into the docs folder and just run `source .venv/bin/activate`. There should be no need to rerun the `pip install` and `python3 -m venv .venv` commands. Note: If you've installed `sphinx` on your system, you may run into issues with commands using that version instead of the version inside your virtualenv. Then if there are no errors, run: ``` make livehtml ``` Note that if OpenDroneMap Desktop or another application is running on port 8000 you should temporarily stop it while you edit the documentation. ## Step 5. Start Editing You can now open a web browser to http://localhost:8000 and see the documentation! You can use a text editor to edit the .rst files in the "source" folder (for example, Visual Studio Code). As soon as you make a change to one of the files, your web browser will reload the documentation with the new changes! ## Step 6. Publish Your Changes Open a Terminal (or command prompt) and type: ```bash cd docs/ git commit -a -m "A description of my changes" git push origin publish ``` You will be prompted for your GitHub credentials. ## Step 7. Open a Pull Request Open https://github.com/OpenDroneMap/docs and you'll see a box asking you to open a pull request. Open a pull request by filling in a description of your changes and you're set! Somebody will review your changes and your contribution will be live on https://docs.opendronemap.org once approved. # Options and Flags Any additions or edits to the **Options and Flags** on https://docs.opendronemap.org/arguments/ need to happen to the `/source/arguments_edit/*.rst` files. The `/source/arguments.rst` file is a list of all options and flags currently available in the ODM code. It is automatically created by running `scripts/extract_odm_strings.py` (you can use `make autogenerate` to run the script) and should not be manually edited. To change the descriptions within the list, the ODM code must be modified. Any manual changes to this file will be overwritten when it is next autogenerated. The script also autogenerates a file for each argument with any information available in the ODM code. These `*.rst` files are in `/source/arguments/` and should not be manually edited. The script creates a blank `*.rst` file for each argument in `/source/arguments_edit/`. Additional details may be added to these file and will be merged with the information available in the ODM code when the documentation site is published. # Translations ## Contributing translations Transifex has a getting [started guide for translators](https://docs.transifex.com/getting-started-1/translators) that will walk you through the steps to setup an account. The ODM documentation Transifex project can be found at: https://app.transifex.com/americanredcross/opendronemap_docs/ The documentation uses a formatting known as [reStructuredTest (reST)](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html) to add links, formatting, and other styling. reST uses plain text to annotate the documentation and identify to the system how to process the different page items. Unfortunately, the translation management process doesn't hide the reST markup. It is important that you keep the reST markup when translating. There are special characters used for: - [Italic](https://github.com/OpenDroneMap/docs#italic) - [Bold](https://github.com/OpenDroneMap/docs#bold) - [Links](https://github.com/OpenDroneMap/docs#link) - [Code](https://github.com/OpenDroneMap/docs#code) (Additionally, code snippets should NOT be translated - only translate the surrounding words.) ### Italic ```plain An `italic section of text` will have a single backtick on either side. An *italic section of text* may also have a single asterisk on either side. ``` Italic text needs to have a space before, then a backtick or grave accent (\`) that touches the first character of the italic text, then the italic text, then a backtick or grave accent (\`) that touches the last character of the italic text, then a space. The backticks may also be asterisks. ### Bold ```plain A **bold section of text** will have double asterisks on either side. ``` Bold text needs to have a space before, then a double asterisk (`**`) that touches the first character of the bold text, then the bold text, then a double asterisk (`**`) that touches the last character of the bold text, then a space. ### Link ```plain Check out the `ODM documentation `_! ``` Links need to have a space before, then a backtick or grave accent (\`), then the text that will become the link on the page (in the above example: "ODM documentation"), then a space, then a less than symbol (`<`), then the complete URL, then a greater than symbol and underscore (`>_`). ### Code Code snippets need to have a space before, then a double backtick or grave accent (\`\`) that touches the first character of the code text, then the code text, then a double backtick or grave accent (\`\`) that touches the last character of the code text, then a space. **NOTE:** Code snippets may be referring to specific software commands and so often should NOT be translated. ## Managing the translation process This project uses [Transifex](https://www.transifex.com/) and the [`transifex-client`](https://docs.transifex.com/client/introduction) tool to help people contribute translations. The `transifex-client` tool is included in the requirements.txt file and should be installed on your system during setup when you run `pip install -r requirements.txt`. You need to configure your account. For this, you need to create an API Token for your user to access this service through the command line. This can be done under your Transifex [User’s Settings](https://www.transifex.com/user/settings/api/). Set it up to use the token: ``` tx init --token $TOKEN --skipsetup ``` If there are **new** English `.rst` source files, you can map them by updating the `./.tx/config` file. After updating the individual argument files with `make autogenerate`, you can run ``` make updatepot make updatelangpo make pushlang make pulllang ``` To add a new language, do it through the Transifex interface and then add a new line to the Makefile `deploy` command. ## The Travis CI build failed... 😞 Don't panic! Unfortunately, Transifex doesn't protect the reST notation that Sphinx uses for things like formatting and links. It's possible that during translation, some of the syntax was broken. Start up your Python virtual environment if it's not already with `source venv/bin/activate` and then run `make allerr`. This does the same thing as `make deploy` but removes the nit-picky mode so that it logs all errors and doesn't stop the build after hitting the first one. You can also run the build for just one specific language, for example: ``` sphinx-build -b dirhtml -D language='sw' source "_build/html/sw/" ``` You should see output in your console such as: ``` Warning, treated as error: /path/to/my/project/OpenDroneMap/docs/source/multispectral.rst:25::1:Inline interpreted text or phrase reference start-string without end-string. ``` Look at the source file and line that is mentioned. In this case the file is `source/multispectral.rst` and the line is the number after the colon after the filename (`25`). Looking at the file we see that line 25 is the last line and the "Help edit these docs!" link. Go to Transifex, go to the resource, and go to the string. The warning/error message should help you understand what went wrong. In this case the link syntax wasn't matched correctly. Fix and save the translation. Pull the language down (for example, `tx pull -l sw`) and then try the build again. ### Questions? Reach out to https://community.opendronemap.org, we'll help you get up and running with your first contribution if you get stuck! #### Repository Notes Travis-CI docs for [Building a Python Project](https://docs.travis-ci.com/user/languages/python/) and [GitHub Pages Deployment](https://docs.travis-ci.com/user/deployment/pages/). Personal access token with 'public_repo - Access public repositories' permissions created and used it in `travis encrypt GH_TOKEN=my_github_token --add env.matrix` as described in the [Travis-CI docs](https://docs.travis-ci.com/user/environment-variables#Encrypting-environment-variables).