Using forestutils
#################


Installation
============
*You will need* Python_ *installed, version 3.4 or later.*

.. _Python: https://www.python.org

Run ``pip install forestutils``.  That's it!  You can now run ``forestutils``
from the commandline without any further configuration.


.. _usage:

Command-line usage
==================

See the output of ``forestutils --help`` for detailed information on
command arguments.

To summarise:  you supply an input filename, of a pointcloud in .ply_
format.  Optional arguments include output directory, whether to save
each tree to a seperate file, and so on.

.. .ply_: https://en.wikipedia.org/wiki/PLY_(file_format)

However, not every valid ``.ply`` file is a valid input for ``forestutils``
- in practise, the format is as flexible as ``.csv`` and the parser sacrifices
some flexibility for speed.

- If you are using pointclouds generated by Pix4D_, no changes are required.
  For multi-part pointclouds you can pass the name of ``*_part_1.ply`` and
  it will be treated as a single file (ensure the ``part_N_ply_offset.xyz``
  files are present for this).

.. _Pix4D: https://www.pix4d.com/

- For other pointcloud formats, simply open and resave in MeshLab_.
  This allows forestutils to defer the problem to a more robust program.
  It also confers second-hand 'compatibility' with a wider variety of 3D
  formats!

.. _MeshLab: https://en.wikipedia.org/wiki/MeshLab

- For LIDAR outputs, ``.las`` format is very common but unfortunately
  not supported at this time.  (If you have LIDAR you can probably afford
  to convert data formats though)

Any pointcloud output by forestutils is of course also a valid input,
and repeated processing (including size-reduction) should have a limited
impact on data completeness (tests show a 1-5% loss in some circumstances).