Git Product home page Git Product logo

ftk's Introduction

FTK: The Feature Tracking Kit

FTK is a library that provides building blocks for feature tracking algorithms in scientific datasets. FTK is header-only and written in C++17.

Major components in FTK

  • Hypermesh: data structures for high-dimensional meshes and mesh elements including n-simplices, n-cubes, and n-prisms; utilities to generalize given 2D/3D structured/unstructured meshes into 3D/4D spacetime meshes

  • Numeric: root-find algorithms for inverse interpolations and parallel vector operators in n-simplices, n-cubes, and simplex-prisms; lightweight linear algebra utilities to support root-finding
  • CCL: connected component labeling algorithm for building feature tracking algorithms
  • Geometry: utilities to transform connect components to geometry for visualization and analysis
  • Tracking graph: data structures to record births, deaths, merges, and splits of features; visualization algorithms for tracking graphs
  • IO: interfaces to stage multiple timesteps of the inputs and to store outputs in key-value stores (LevelDB, RocksDB, and Mochi), file systems, and in situ staging areas

Download and Install

You may include FTK headers and call FTK functions directly from your C++ code, because FTK is header-only.

Checkout FTK source from Git

$ git clone https://github.com/hguo/ftk $FTK_SOURCE_DIR

Installation (optional)

You may install FTK to an designated path. The installation will also generate FTKConfig.cmake in the installation path, such that you can use find_package(FTK) to find and use FTK in your CMakeLists.txt

$ git clone https://github.com/hguo/ftk $FTK_SOURCE_DIR
$ mkdir $FTK_SOURCE_DIR/build && cd $FTK_SOURCE_DIR/build
$ cmake .. -DCMAKE_INSTALL_PREFIX=$FTK_INSTALL_DIR
$ make install

The installed files are organized as follows:

$ tree $FTK_INSTALL_DIR
.
├── include
│   ├── ftk
│   │   ├── algorithms
│   │   │   ├── bfs.hh
...
│   └── hypermesh
│       ├── ndarray.hh
│       ├── regular_mesh.hh
...
└── lib
    └── cmake
        └── FTKConfig.cmake

Include FTK in your CMake project

You may use the FTK installation in your own CMakeLists.txt file:

find_package(FTK REQUIRED)
include_directories (${FTK_INCLUDE_DIR})

When you configure your build, please specify FTK_DIR with CMake:

$ cmake -DFTK_DIR=$FTK_INSTALL_DIR/lib/cmake

Build Examples

FTK currently provides three examples, including 2D critical point tracking, 3D critical point tracking, and a demo for the tracking graph.

Dependencies

FTK examples optionally depend on the following packages

  • VTK >= 8.2, optional, or required if you would like to visualize trajectories with VTK
  • Qt5 >= 5.11.2, optional, or required if you would like to visualize trajectories with Qt/OpenGL windows
  • NetCDF >= 4.6.1, optional, or requried if you would like to load a 3D scalar

Build FTK examples

To build FTK examples without any dependences, please follow the following configuration:

$ cd $FTK_SOURCE_DIR/build
$ cmake .. -DFTK_BUILD_EXAMPLES=1
$ make

To build with Qt5, VTK, and NetCDF, you need additional arguments for cmake:

$ cd $FTK_SOURCE_DIR/build
$ cmake .. -DFTK_BUILD_EXAMPLES=1 -DCMAKE_PREFIX_PATH="/path/to/qt5/lib/cmake;/path/to/vtk/lib/cmake" -DNETCDF_DIR="/path/to/netcdf"
$ make

Run FTK examples

The followings are the guide to run the 2D critical point tracking example. We aim to track local maximum over time for the following scalar field:

$f(x,y,t)=cos(x\cos t - y\sin t) \sin(x\sin t + y\cos t),$

where $x$ and $y$ are 2D coordinates and $t$ is time. We discretize the $x,y$ domain into a $128\times 128$ regular grid and the time domain into 10 timesteps.

In this example, local maximum are defined as the loci of points that $(\frac{\partial f}{\partial x}, \frac{\partial f}{\partial x})=0$ and both eigenvalues of the Hessian of $f$ (in terms of $x$ and $y$) are negative. We use a sweep-and-trace algorithm to first localize local maximum and trace the maximum over space-time. We first mesh the scalar field with a 3D regular simplex mesh and check every 2-elements (faces) meets the criteria. We then do the connected component labeling; two faces are connected if each of them has a local maxima and share the same 3-element (tetrahedra). The trajectories are then constructured from the connected components.

You can run the example with following command, and the executable prints the trajectory:

$ ./examples/critical_point_tracking_2d/ex_critical_point_tracking_2d
We found 16 trajectories:
--Curve 0:
---x=(2.000000, 26.972244), t=5.869000, val=0.955384
---x=(2.056124, 26.857716), t=5.857716, val=0.958166
...
--Curve 15:
---x=(125.000000, 122.414673), t=1.241837, val=0.884089
---x=(124.709686, 122.709686), t=1.187109, val=0.912740
...

If you built the example with Qt, you can use the Qt/OpenGL based window to explore the trajectory. You can rotate the space with mouse and increase/decrease timesteps with the left/right keys. The color encodes the ID of different trajectories. Please use —qt argument to run the executable, and the example screenshot is as follows.

$ ./examples/critical_point_tracking_2d/ex_critical_point_tracking_2d --qt

If you built the example with VTK, you may also explore the trajectories with a VTK window by adding —vtk argument:

$ ./examples/critical_point_tracking_2d/ex_critical_point_tracking_2d --vtk

Applications that use FTK

  • vortexfinder2: Vortex finder for time-dependent Ginzburg-Landau superconductor simulation data

ftk's People

Contributors

hewenbin avatar hguo avatar lxaltria avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.