TLSpy Code
Brought to you by:
jedfrechette
Menu
▾
▴
Tree [a8ffc9] default tip / History
Jed Frechette
Jed Frechette
Jed Frechette <jed@lidarguys.com
Read Me
=============
README: TLSpy
=============
1 What is TLSpy?
================
TLSpy is a set of multi-platform Python tools for working with
Terrestrial Lidar Scanner (TLS) data. TLSpy's goal is to provide
a set of utilities for working with TLS data. TLSpy is released under
the terms of the GPL version 3.
TLSpy is still in the early stages of development and no official
releases have been made yet. Although initially conceived as a
plug-in driven framework, development has shifted towards providing
a number of small standalone utilities for terrestrial lidar
processing and analysis. The source code is available from our
version control repository.
2 Installation
==============
Until a release is made and proper installers can be provided users
should follow the Developer installation instructions under
section 2.2 below.
2.1 Requirements
----------------
A working Python installation is the first prerequisite for using TLSpy.
Current development uses Python 2.7 and we recommend users adopt this
version as well. In addition to a working Python installation the
following packages are also required.
setuptools http://peak.telecommunity.com/DevCenter/setuptools
In addition to the required packages individual tools may require
additional packages. Specific requirements are listed in the descriptions
below, however, the following packages are common requirements.
NumPy http://www.scipy.org
SciPy http://www.scipy.org
Matplotlib http://matplotlib.sourceforge.net
GDAL/OGR http://www.gdal.org
Traits http://code.enthought.com/projects/traits
Chaco http://code.enthought.com/projects/chaco
Mayavi http://code.enthought.com/projects/mayavi
TLSpy is developed and tested primarily on Linux, however,
it is likely to run on any platform where the above requirements
can be satisfied. Linux users will probably want to install the required
packages using their distributions package manager. Mac and Windows users,
however, may find it more convenient to install a Python bundle that includes
all of the required packages. The open-source Python(x,y) [1]_ and the free
for academic and personal use Enthought Python Distribution [2]_ are two such
bundles.
.. [1] http://pythonxy.com
.. [2] http://www.enthought.com/products/epd.php
2.2 Developers
--------------
A web interface for TLSpy's version control repository is available at:
http://sourceforge.net/p/tlspy/code/ci/tip/tree
Snapshots can be downloaded from the web interface, however developers
are strongly encouraged to track development using Mercurial. A working
copy can be checked out with the command::
hg clone http://hg.code.sf.net/p/tlspy/code tlspy
This will create a copy of TLSpy's repository in a directory called
``tlspy`` within your current directory. Consult Mercurial's
documentation for more details on interacting with the repository.
Next change to the directory containing your local copy of TLSpy and
build the project in place with setuptools::
cd tlspy
python setup.py develop
This should add links to TLSpy's source code in your Python site directory
and install the tlspy executable on your path.
3 Usage
=======
TLSpy consists of multiple independent components. The usage of each is
summarized below.
3.1 Stand-alone Utilities
-------------------------
The following utilities are installed by TLSpy. For more information
about these applications call them with the ``--help`` option.
Other scripts are included in the source code, however, they are
experimental and are not supported.
cam-rx
This application is used for calibrating the internal and external
parameters of photographs. It provides an interface for picking 2D
control points on the image and allows the user to import a list of
matching 3D control points defined in an external Cartesian coordinate
system. An addon for Blender (io_import_camx.py) that imports Cam-Rx
calibration files and uses them to setup cameras and UV textures is
also provided. In addition, a script for AgiSoft's PhotoScan is also
provided that exports calibrated cameras to the Cam-Rx format.
**Requirements:** Numpy, Traits, Chaco, OpenCV, pyexiv2.
extract_sop
Extract SOP matrices from a RiScan Pro project as PolyWorks compatible
matrices.
generate_tiles
The script ``generate_tiles`` uses polygons defined in a Shapefile
to split a large point cloud stored in a text file into smaller tiles.
**Requirements:** GDAL/OGR.
huge_translation
Manipulate huge translations for Polyworks point cloud text exports.
**Requirements:** Numpy
ima_summary
Extract a summary from IMAlign projects listed in a PolyWorks
workspace. **Requirements:** Numpy, Matplotlib, Traits
nn_dist
Calculate the distance between each point in a point cloud and its
nearest neighbor. **Requirements:** Numpy, Scipy, Matplotlib
optech_asc
The script ``optech_asc`` will check parsed Optech ILRIS scans in a
directory tree for suspicious ASC data that may indicate a hardware
failure or other data quality problems. **Requirements:** Numpy
ply2txt
Convert an ASCII Stanford .ply file into a tabular list of vertices
in a text file.
ptx2mat
The script ``ptx2mat`` is used for batch conversion of .ptx files to
MATLAB compatible .mat files. **Requirements:** Numpy
raw2cs
This script is a thin wrapper around dcraw, oiiotool, and exiftool
for converting camera raw files into images with sRGB or
scene-linear color spaces. **Requirements:** dcraw, oiiotool
*Recomendations:* exiftool
split_loops
Ingest a text file containing continuous scans of a target and
split it into individual images. **Requirements:** Numpy, ConfigObj
vdiff
The Mayavi script ``vdiff`` is used to visualize 3D differences in
position between pairs of points. **Requirements:** Numpy, Mayavi
3.2 PolyWorks Macros
--------------------
The following macros were developed for use with InnovMetric's PolyWorks
software. Unless otherwise noted, all macros were developed and tested
using version 11.
3.2.1 IMAlign Macros
````````````````````
The following macros were developed for use with IMAlign.
ima_data_file_transform.macro
Apply alignment matrices in a provided directory to data
objects with matching names in the current project.
ima_DIGITIZER_POS_toggle.macro
Toggle the Use/Ignore status of all DIGITIZER POS image
reference points.
ima_DIGITIZER_POS_tolerance.macro
Set the 3D tolerance of all DIGITIZER POS reference points in the
current project.
ima_import_named_image_pts.macro
Import named image reference points from a text file.
ima_import_TGO_global_pts.macro
Import global reference points with tolerances from a text file.
ima_repeating_best-fit.macro
Repeat best-fit alignment decreasing the Maximum Distance
by half after each iteration.
3.2.2 IMSurvey Macros
`````````````````````
The following macros were developed for use with IMSurvey.
ims_align_vector_to_z.macro
Align selected objects by transforming the specified vector so that it
is parallel to the z-axis.
ims_data_file_transform.macro
Apply alignment matrices in a provided directory to data
objects with matching names in the current project.
ims_export_data2txt.macro
Export all data objects to separate point cloud text files.
ims_export_matrices.macro
Export global alignment matrices for all data and reference objects
to specified directory.
ims_export_named_image_pts.macro
Export named image reference points to a text file.
ims_extract_circle_target.macro
Extract a reference point from a circular target consisting of a
white circle of known radius on a dark background.
ims_extract_sphere_target.macro
Extract a reference point from a spherical target of known radius.
ims_selection2origin.macro
Calculate the center of mass for the selected data points then
transform the center of mass and all selected data objects to
the origin.
ims_step.macro
Use a plane to iteratively step through slices of a data set. This
macro is just a prototype and needs to be edited before actual
production use.
ims_toggle_normals.macro
Toggle 'Ignore points without normals' for all data objects.
3.2.3 IMEdit Macros
```````````````````
The following macros were developed for use with IMEdit.
ime_compress_percentages.macro
Create copies of the selected polygonal models that have
had their polygon count reduced by the specified percentages.
ime_export_obj.macro
Export selected models to .obj. Optionally, the model can be exported
with +y as the vertical axis.
ime_poisson_surface.macro
Create and import a mesh from oriented points using Poisson Surface
Reconstruction. The macro requires the PoissonRecon tool from:
http://www.cs.jhu.edu/~misha/Code/PoissonRecon
