{"id":13548053,"url":"https://github.com/Kitware/TeleSculptor","last_synced_at":"2025-04-02T20:31:38.629Z","repository":{"id":17020486,"uuid":"19784494","full_name":"Kitware/TeleSculptor","owner":"Kitware","description":"TeleSculptor: Aerial Photogrammetry Application powered by KWIVER","archived":false,"fork":false,"pushed_at":"2024-05-22T15:21:20.000Z","size":41600,"stargazers_count":617,"open_issues_count":42,"forks_count":150,"subscribers_count":51,"default_branch":"master","last_synced_at":"2025-03-27T17:15:11.425Z","etag":null,"topics":["aerial-imagery","c-plus-plus","gui-application","kitware","kwiver","photogrammetry"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Kitware.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-05-14T15:14:37.000Z","updated_at":"2025-03-25T16:45:34.000Z","dependencies_parsed_at":"2024-11-03T16:42:19.106Z","dependency_job_id":null,"html_url":"https://github.com/Kitware/TeleSculptor","commit_stats":null,"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kitware%2FTeleSculptor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kitware%2FTeleSculptor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kitware%2FTeleSculptor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kitware%2FTeleSculptor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kitware","download_url":"https://codeload.github.com/Kitware/TeleSculptor/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246888086,"owners_count":20850195,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aerial-imagery","c-plus-plus","gui-application","kitware","kwiver","photogrammetry"],"created_at":"2024-08-01T12:01:05.090Z","updated_at":"2025-04-02T20:31:33.620Z","avatar_url":"https://github.com/Kitware.png","language":"C++","readme":".. image:: doc/images/TeleSculptor_Logo.png\n   :width: 1024px\n   :alt: TeleSculptor\n\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nTeleSculptor Overview\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTeleSculptor is a cross-platform desktop application for photogrammetry.\nIt was designed with a focus on aerial video, such as video collected from UAVs,\nand handles geospatial coordinates and can make use of metadata, if available,\nfrom GPS and IMU sensors.  However, the software can also work with\nnon-geospatial data and with collections of images instead of metadata.\nTeleSculptor uses Structure-from-Motion techniques to estimate camera parameters\nas well as a sparse set of 3D landmarks.  It uses Multiview Stereo techniques\nto estimate dense depth maps on key frame and then fuses those depth maps\ninto a consistent surface mesh which can be colored from the source imagery.\n\nTeleSculptor can be installed from precompiled binaries for Linux, MacOS, and\nWindows included at the bottom of the\n`latest release`_ page by following the instructions in the Installation_ section.\nInstructions on how to use the TeleSculptor GUI can be found in\nthe `User Guide`_. A computer with at\nleast 16GB of RAM is recommended for processing most datasets.\n\nMore advanced users who wish to build the project from source should proceed to the\n`Building TeleSculptor`_ section.\n\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nBackground\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTeleSculptor provides a graphical user interface with Qt_, 3D visualization\nwith VTK_, and photogrammetry algorithms with KWIVER_. This project was\npreviously called MAP-Tk (Motion-imagery Aerial Photogrammetry Toolkit).\nThe MAP-Tk name is still scattered throughout the source code.\nMAP-Tk started as an open source C++ collection of libraries and tools for\nmaking measurements from aerial video.  The TeleSculptor application was added\nto the project later. The original software framework and algorithm were then\nrefactored into KWIVER and then expanded to address broader computer vision\nproblems.  While KWIVER is now a more broad set of tools, TeleSculptor remains\nan application focused on photogrammetry.\n\nThe advantage of the KWIVER software architecture (previously MAP-Tk) is that\nit is highly modular and provides an algorithm abstraction layer\nthat allows seamless interchange and run-time selection of algorithms from\nvarious other open source projects like OpenCV, VXL, Ceres Solver, and PROJ4.\nThe core KWIVER library (vital) and tools are light-weight with minimal\ndependencies (C++ standard library, and Eigen_).  TeleSculptor is written to\ndepend only on the KWIVER \"vital\" library.  Additional capabilities are\nprovided by KWIVER arrows (plugin modules) that use third party libraries\nto implement various abstract algorithm interfaces defined in the KWIVER vital\nlibrary.  This means that new plugins can be dropped into TeleSculptor to\nenable alternative or new functionality by adjusting some settings in a\nconfiguration file.  While TeleSculptor provides a default workflow that works\nout of the box, it is not just an end user tool.  It is designed to be highly\nconfigurable to support research into to algorithms and new problem domains.\n\nThe screenshots below show TeleSculptor\nrunning on example videos from the `VIRAT Video Dataset`_,\n`CLIF 2007 Dataset`_, and other public data sets.  More information about this\nexample data can be found in the `examples \u003cexamples\u003e`_ directory.\n\nWhile the initial software implementation relies on batch post-processing\nof aerial video, our intent is to move to an online video stream processing\nframework and optimize the algorithm to run in real-time.\n\n\n.. image:: /doc/screenshot/telesculptor_screenshot_macos.png\n   :alt: MacOS Screenshot\n.. image:: /doc/screenshot/telesculptor_screenshot_windows.png\n   :alt: Windows Screenshot\n.. image:: /doc/screenshot/telesculptor_screenshot_linux.png\n   :alt: Linux Screenshot\n\n\nInstallation\n============\nIf you have downloaded an installer from the\n`latest release`_\nyou can simply install TeleSculptor according to the instructions for your\noperating system described below. If you are building TeleSculptor from source\nyou should proceed to `Building TeleSculptor`_ to create the installer before\ncompleting the installation.\n\n**Windows:** run the installer executable (exe) and follow the prompts in the\ninstaller dialog. Administrative permission is required.\n\n**Mac:** open the disk image (dmg), accept the license terms, then drag the\nTeleSculptor application into the Applications folder.\n\n**Linux:** open a bash/cmd shell and run the self extracting installer script\n(sh). You can view additional installation options using\n``./TeleSculptor-\u003cversion\u003e-Linux-x86_64.sh --help``\n\nThe remainder of this document is aimed at developers who wish to build the\nproject from source.  For end users looking for instruction on running the GUI\napplication please read the `User Guide`_.\n\n\nBuilding TeleSculptor\n=====================\n\nTeleSculptor requires C++11 compliant compiler\n(e.g. GCC 4.8.1, Clang 3.3, Visual Studio 2015).\nTeleSculptor uses CMake (www.cmake.org) for easy cross-platform compilation. The\nminimum required version of CMake is 3.9.5, but newer versions are recommended.\n\nBuilding\n--------\nThe build is directed by CMake to ensure it can be built on various platforms.\nThe code is built by a CMake 'superbuild', meaning as part of the build,\nCMake will download and build any dependent libraries needed by TeleSculptor.\nThe build is also out of source, meaning the code base is to be separate from\nthe build files.  This means you will need two folders, one for the source code\nand one for the build files.\nHere is the quickest way to build via a cmd/bash shell.\n\nBefore building on Linux systems you must install the following packages:\n\n.. code-block :: bash\n\n  sudo apt-get install build-essential libgl1-mesa-dev libxt-dev\n  sudo apt-get libx11-xcb-dev libxcb1-dev libxcb-glx0-dev libxkbcommon-x11-dev\n  sudo apt-get install libexpat1-dev libgtk2.0-dev liblapack-dev\n\nOn Linux, to optionally build with Python and to build the user documentation,\nyou will also need to install the following:\n\n.. code-block :: bash\n\n  sudo apt-get install python3-dev python3-sphinx python3-sphinx-rtd-theme\n\nSet up the folder structure and obtain the source files. This can be done with\ngit or by downloading the files and extracting them. Then setup the folder(s)\nto build the binary files.\n\n.. code-block :: bash\n\n  mkdir telesculptor\n  cd telesculptor\n\n  ## Place the code in a directory called src\n  # Using git, clone into a new directory called src\n  git clone https://github.com/Kitware/TeleSculptor.git src\n  # Or unzip into a new directory called src\n  unzip \u003cfile name\u003e.zip src\n\n  ## Create the folder where we will build the binaries\n  mkdir builds\n  cd builds\n  # Instead of just one builds folder you can to make subfolders here for\n  # different builds, for example: builds/debug and builds/release.\n  # Each folder would then be built following the steps below but with different\n  # configuration options\n\nGenerate the makefile/msvc solution to perform the superbuild using cmake.\nA description of the configuration options can be found in `CMake Options`_.\n\n.. code-block :: bash\n\n  # From the build directory provide cmake the path to the source directory,\n  # which can be relative or absolute.\n  # Specify configurable options by prefacing them with the -D flag\n  cmake -DCMAKE_BUILD_TYPE:STRING=Release ../src\n  # Alternatively, you can use the 'ccmake' command line tool allows for\n  # interactively selecting CMake options. This can be installed with\n  # 'sudo apt-get install cmake-curses-gui'\n  ccmake ../src\n  # As a final option, you can use the the CMake GUI you can set the source and\n  # build directories accordingly and then press the \"Configure\" and “Generate”\n  # buttons\n\nBuild the installer target/project\n\n.. code-block :: bash\n\n  # On Linux/OSX/MinGW\n  make\n  # Once the Superbuild is complete, the telesculptor makefile will be placed in\n  # the build/external/telesculptor-build directory\n\n  # For MSVC\n  # Open the TeleSculptor-Superbuild.sln, choose your build configuration,\n  # from the 'Build' menu choose 'Build Solution'\n  # When the build is complete you may close this solution.\n  # To edit TeleSculptor code, open the\n  # build/external/telesculptor-build/TeleSculptor.sln\n\nYou have now built a TeleSculptor installer similar to what is provided in the\n`latest release`_ section. To install TeleSculptor on you machine, follow the\ninstructions above in `Installation`_.\n\nCMake Options\n-------------\n\n================================== ===================================================\n``CMAKE_BUILD_TYPE``               The compiler mode, usually ``Debug`` or ``Release``\n``TELESCULPTOR_ENABLE_CUDA``       Enable GPU acceleration with CUDA\n``TELESCULPTOR_ENABLE_PYTHON``     Enable Python bindings in KWIVER\n``TELESCULPTOR_ENABLE_MANUALS``    Turn on building the user documentation\n``TELESCULPTOR_ENABLE_TESTING``    Build the unit tests\n``TELESCULPTOR_SUPERBUILD``        Build as a superbuild (build Fletch and KWIVER)\n================================== ===================================================\n\nMulit-Configuration Build Tools\n'''''''''''''''''''''''''''''''\n\nBy default the CMAKE_BUILD_TYPE is set to Release.\n\nSeparate directories are required for Debug and Release builds, requiring CMake\nto be run for each.\n\nEven if you are using a Multi-Configuration build tool (like MSVC) to build\nDebug you must select the Debug CMAKE_BUILD_TYPE. (On Windows in order to debug\na project all dependent projects must be build with Debug information.)\n\nFor MSVC users wanting a RelWithDebInfo build we recommend you still choose\nRelease for the superbuild.  Release and RelWithDebInfo are compatible with each\nother, and Fletch will build its base libraries as Release.  MSVC solutions will\nprovide both Release and RelWithDebInfo configuration options. You will need to\nopen the ``\u003cbuild/directory\u003e/external/kwiver-build/KWIVER.sln`` and build this\nsolution with the RelWithDebInfo configuration.\n\n\nTeleSculptor\n''''''''''''\n\nThe TeleSculptor GUI application is enabled by default,\nand all dependencies will be built by the Superbuild.\n\nDocumentation\n'''''''''''''\n\nIf ``TELESCULPTOR_ENABLE_MANUALS`` is enabled, and CMake finds all dependencies,\nthen the user manuals are built as part of the normal build process under the target\n\"manuals\".  The GUI manual can be viewed from inside the GUI by choosing the\n\"TeleSculptor User Manual\" action from the \"Help\" menu.\n\nTo build the user manual(s), you need:\n\n* Python\n    version 3.4 or greater\n    http://www.python.org/\n\n* Docutils\n    version 0.11 or greater\n    http://docutils.sourceforge.net/\n\n(At present, only the GUI has a user manual.  Other manuals may be added in the\nfuture.)\n\nTesting\n'''''''\n\nContinuous integration testing is provided by CDash_.\nOur `MAP-Tk dashboard \u003chttps://open.cdash.org/index.php?project=MAPTK\u003e`_\nhosts nightly build and test results across multiple platforms including\nWindows, Mac, and Linux.\n\nAnyone can contribute a build to this dashboard using the\n`dashboard script \u003cCMake/dashboard-scripts/TeleSculptor_common.cmake\u003e`_\nprovided.  Follow the instructions in the comments.\n\n`Travis CI`_ is also used for continued integration testing.\nTravis CI is limited to a single platform (Ubuntu Linux), but provides\nautomated testing of all topic branches and pull requests whenever they are\ncreated.\n\n============================= =============\nTravis CI **master** branch:  |CI:master|_\nTravis CI **release** branch: |CI:release|_\n============================= =============\n\nAdvanced Build\n--------------\n\nTeleSculptor is built on top of the KWIVER_ toolkit, which is in turn built on\nthe Fletch_ super build system.  As mentioned above, to make it easier to build\nTeleSculptor, a \"super-build\" is provided to build both KWIVER and Fletch.\nBut, if you wish, you may point the TeleSculptor build to use your own KWIVER\nbuilds.\n\nIf you would like TeleSculptor to use a prebuilt version of KWIVER, specify the\nkwiver_DIR flag to CMake.  The kwiver_DIR is the KWIVER build directory root,\nwhich contains the kwiver-config.cmake file.\n\n.. code-block :: bash\n\n    $ cmake ../../src -DCMAKE_BUILD_TYPE=Release -Dkwiver_DIR:PATH=\u003cpath/to/kwiver/build/dir\u003e\n\nYou must ensure that the specified build of KWIVER was built with at least the following options set:\n\nThe required KWIVER flags can be found in this file : `\u003cCMake/telesculptor-external-kwiver.cmake\u003e`_\n\nThe required Fletch flags can be found in this file : `\u003cCMake/telesculptor-external-fletch.cmake\u003e`_\n\nOverview of Directories\n=======================\n\n======================= ========================================================\n``CMake``               contains CMake helper scripts\n``config``              contains reusable default algorithm configuration files\n``doc``                 contains release notes, manuals, and other documentation\n``examples``            contains pointers to example public datasets to use\n``gui``                 contains the visualization GUI source code and headers\n``gui/icons``           contains the visualization GUI icon resources\n``maptk``               contains the maptk library source and headers\n``packaging``           contains support files for CPack packaging\n``scripts``             contains Python helper scripts\n``plugins/blender``     contains Python plug-ins for Blender\n``plugins/sketchup``    contains Ruby plug-ins for SketchUp\n``tests``               contains testing framework and tests for each module\n======================= ========================================================\n\n\nGetting Help\n============\n\nTeleSculptor is a component of Kitware_'s collection of open source computer\nvision tools and part of the KWIVER_ ecosystem. Please join the\n`kwiver-users \u003chttp://public.kitware.com/mailman/listinfo/kwiver-users\u003e`_\nmailing list to discuss or to ask for help with using TeleSculptor.\nFor less frequent announcements about TeleSculptor and other KWIVER components,\nplease join the\n`kwiver-announce \u003chttp://public.kitware.com/mailman/listinfo/kwiver-announce\u003e`_\nmailing list.\n\n\nAcknowledgements\n================\n\nThe authors would like to thank AFRL/Sensors Directorate for their support\nof this work via SBIR Contract FA8650-14-C-1820. This document is approved for\npublic release via 88ABW-2015-2555.\n\n\n.. Appendix I: References\n.. ======================\n\n.. _VIRAT Video Dataset: http://www.viratdata.org/\n.. _CLIF 2007 Dataset: https://www.sdms.afrl.af.mil/index.php?collection=clif2007\n.. _Bundler: http://www.cs.cornell.edu/~snavely/bundler/\n.. _CDash: http://www.cdash.org/\n.. _Eigen: http://eigen.tuxfamily.org/\n.. _Fletch: https://github.com/Kitware/fletch\n.. _Kitware: http://www.kitware.com/\n.. _KWIVER: http://www.kwiver.org/\n.. _Qt: https://www.qt.io/\n.. _Travis CI: https://travis-ci.com/\n.. _VisualSFM: http://ccwu.me/vsfm/\n.. _VTK: https://vtk.org/\n.. _latest release: https://github.com/Kitware/TeleSculptor/releases/latest\n.. _User Guide: https://telesculptor.readthedocs.io/en/latest/\n\n.. Appendix II: Text Substitutions\n.. ===============================\n\n.. |\u003e=| unicode:: U+02265 .. greater or equal sign\n\n.. |CI:master| image:: https://travis-ci.com/Kitware/TeleSculptor.svg?branch=master\n.. |CI:release| image:: https://travis-ci.com/Kitware/TeleSculptor.svg?branch=release\n\n.. _CI:master: https://travis-ci.com/Kitware/TeleSculptor\n.. _CI:release: https://travis-ci.com/Kitware/TeleSculptor\n","funding_links":[],"categories":["Toolbox","C++","\u003ca name=\"cpp\"\u003e\u003c/a\u003eC++","others","SFM","OpenSource SfM (Structure from Motion)","Photogrammetric software"],"sub_categories":["Libraries","Project\u0026code","UAV Trajectory Optimization for model completeness"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKitware%2FTeleSculptor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKitware%2FTeleSculptor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKitware%2FTeleSculptor/lists"}