#' @section Uniqueness:
#'
#' By default the tree IDs are numbered from 1 to n, n being the number of trees found. The problem
#' with such incremental numbering is that, while it ensures a unique ID is assigned for each tree in
#' a given point-cloud, it also guarantees duplication of tree IDs in different tiles or chunks when
#' processing a `LAScatalog`. This is because each file is processed independently of the others and potentially
#' in parallel on different computers. Thus, the index always restarts at 1 on each file or chunk. Worse,
#' in a tree segmentation process, a tree that is located exactly between 2 files will have two different
#' IDs for its two halves.
#'
#' This is why we introduced some uniqueness strategies that are all imperfect and that should be seen
#' as experimental. Please report any troubleshooting. Using a uniqueness-safe strategy ensures that
#' trees from different files will not share the same IDs. Moreover, it also means that two halves of a tree
#' on the edge of a processing chunk will be assigned the same ID.
#'
#' \describe{
#' \item{incremental}{Number from 0 to n. This method **does not** ensure uniqueness of the IDs. This
#' is the legacy method.}
#' \item{gpstime}{This method uses the gpstime of the highest point of a tree (apex) to create a
#' unique ID. This ID is not an integer but a 64-bit decimal number which is suboptimal but at
#' least it is exepected to be unique **if the gpstime attribute is consistent across files**.
#' If inconsistencies with gpstime are reported (for example gpstime records the week time and was
#' reset to 0 in a coverage that takes more than a week to complete), there is a (low) probability to get
#' ID attribution errors.}
#' \item{bitmerge}{This method uses the XY coordinates of the highest point (apex) of a tree to
#' create a single number with a bitwise operation. First, XY coordinates are converted to integers using the
#' scales and offsets of the point-cloud. Then the ID is computed with X * 2^32 + Y to combine twice the 32-bits
#' of information into a 64-bit number. For example, if the apex is at (10.32, 25.64)
#' with a scale factor of 0.01 and an offset of 0, the integer coordinates are X = 1032 and Y = 2564
#' and the ID is 4432406252036. Such methods return a 64-bit integer but because 64-bit integers do
#' not exist in R it is converted to a 64-bit decimal number that is guaranteed to be unique
#' **if all files have the same offsets and scale factors**.}
#' }
#'
#' All the proposed options are suboptimal because they either do not guarantee uniqueness in all cases
#' (inconsistencies in the collection of files), or they imply that IDs are based on non-integers or
#' meaningless numbers. But at the very least we expect this to work for simple cases.
#' @md
