TTK
•All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
Public Types | Public Member Functions | Protected Attributes | List of all members
ttk::PersistenceDiagram Class Reference
base

TTK processing package for the computation of persistence diagrams. More...

#include <PersistenceDiagram.h>

Inheritance diagram for ttk::PersistenceDiagram:
ttk::Debug ttk::BaseClass ttkPersistenceDiagram ttkPersistenceDiagramApproximation

Public Types

enum class  BACKEND {
  FTM = 0 , PROGRESSIVE_TOPOLOGY = 1 , DISCRETE_MORSE_SANDWICH = 2 , APPROXIMATE_TOPOLOGY = 3 ,
  PERSISTENT_SIMPLEX = 4
}
 

Public Member Functions

 PersistenceDiagram ()
 
void setBackend (const BACKEND be)
 
void setComputeMinSad (const bool data)
 
void setComputeSadSad (const bool data)
 
void setComputeSadMax (const bool data)
 
template<typename scalarType , typename triangulationType >
void augmentPersistenceDiagram (std::vector< PersistencePair > &persistencePairs, const scalarType *const scalars, const triangulationType *triangulation)
 Complete a ttk::DiagramType instance with scalar field values (useful for persistence) and 3D coordinates of critical vertices.
 
ttk::CriticalType getNodeType (ftm::FTMTree_MT *tree, ftm::TreeType treeType, const SimplexId vertexId) const
 
void sortPersistenceDiagram (std::vector< PersistencePair > &diagram, const SimplexId *const offsets) const
 
template<typename scalarType >
int computeCTPersistenceDiagram (ftm::FTMTreePP &tree, const std::vector< std::tuple< ttk::SimplexId, ttk::SimplexId, scalarType, bool > > &pairs, std::vector< PersistencePair > &diagram) const
 
template<typename scalarType , class triangulationType >
int execute (std::vector< PersistencePair > &CTDiagram, const scalarType *inputScalars, const size_t scalarsMTime, const SimplexId *inputOffsets, const triangulationType *triangulation, const std::vector< bool > *updateMask=nullptr)
 
template<typename scalarType , class triangulationType >
int executeFTM (std::vector< PersistencePair > &CTDiagram, const scalarType *inputScalars, const SimplexId *inputOffsets, const triangulationType *triangulation)
 
template<class triangulationType >
int executeProgressiveTopology (std::vector< PersistencePair > &CTDiagram, const SimplexId *inputOffsets, const triangulationType *triangulation)
 
template<typename scalarType , class triangulationType >
int executeApproximateTopology (std::vector< PersistencePair > &CTDiagram, const scalarType *inputScalars, const triangulationType *triangulation)
 
template<class triangulationType >
int executePersistentSimplex (std::vector< PersistencePair > &CTDiagram, const SimplexId *inputOffsets, const triangulationType *triangulation)
 
template<typename scalarType , class triangulationType >
int executeDiscreteMorseSandwich (std::vector< PersistencePair > &CTDiagram, const scalarType *inputScalars, const size_t scalarsMTime, const SimplexId *inputOffsets, const triangulationType *triangulation, const std::vector< bool > *updateMask=nullptr)
 
template<class triangulationType >
void checkProgressivityRequirement (const triangulationType *triangulation)
 
template<class triangulationType >
void checkManifold (const triangulationType *const triangulation)
 
void preconditionTriangulation (AbstractTriangulation *triangulation)
 
void setOutputMonotonyOffsets (void *data)
 
void setOutputOffsets (void *data)
 
void setOutputScalars (void *data)
 
void setDeltaApproximate (double data)
 
template<class triangulationType >
void checkProgressivityRequirement (const triangulationType *ttkNotUsed(triangulation))
 
- Public Member Functions inherited from ttk::Debug
 Debug ()
 
 ~Debug () override
 
virtual int setDebugLevel (const int &debugLevel)
 
int setWrapper (const Wrapper *wrapper) override
 
int printMsg (const std::string &msg, const debug::Priority &priority=debug::Priority::INFO, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cout) const
 
int printMsg (const std::vector< std::string > &msgs, const debug::Priority &priority=debug::Priority::INFO, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cout) const
 
int printErr (const std::string &msg, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cerr) const
 
int printWrn (const std::string &msg, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cerr) const
 
int printMsg (const std::string &msg, const double &progress, const double &time, const int &threads, const double &memory, const debug::LineMode &lineMode=debug::LineMode::NEW, const debug::Priority &priority=debug::Priority::PERFORMANCE, std::ostream &stream=std::cout) const
 
int printMsg (const std::string &msg, const double &progress, const double &time, const debug::LineMode &lineMode=debug::LineMode::NEW, const debug::Priority &priority=debug::Priority::PERFORMANCE, std::ostream &stream=std::cout) const
 
int printMsg (const std::string &msg, const double &progress, const double &time, const int &threads, const debug::LineMode &lineMode=debug::LineMode::NEW, const debug::Priority &priority=debug::Priority::PERFORMANCE, std::ostream &stream=std::cout) const
 
int printMsg (const std::string &msg, const double &progress, const debug::LineMode &lineMode=debug::LineMode::NEW, const debug::Priority &priority=debug::Priority::PERFORMANCE, std::ostream &stream=std::cout) const
 
int printMsg (const std::string &msg, const double &progress, const debug::Priority &priority, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cout) const
 
int printMsg (const std::vector< std::vector< std::string > > &rows, const debug::Priority &priority=debug::Priority::INFO, const bool hasHeader=true, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cout) const
 
int printMsg (const debug::Separator &separator, const debug::LineMode &lineMode=debug::LineMode::NEW, const debug::Priority &priority=debug::Priority::INFO, std::ostream &stream=std::cout) const
 
int printMsg (const debug::Separator &separator, const debug::Priority &priority, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cout) const
 
int printMsg (const std::string &msg, const debug::Separator &separator, const debug::LineMode &lineMode=debug::LineMode::NEW, const debug::Priority &priority=debug::Priority::INFO, std::ostream &stream=std::cout) const
 
void setDebugMsgPrefix (const std::string &prefix)
 
- Public Member Functions inherited from ttk::BaseClass
 BaseClass ()
 
virtual ~BaseClass ()=default
 
int getThreadNumber () const
 
virtual int setThreadNumber (const int threadNumber)
 

Protected Attributes

bool IgnoreBoundary {false}
 
ftm::FTMTreePP contourTree_ {}
 
dcg::DiscreteGradient dcg_ {}
 
PersistentSimplexPairs psp_ {}
 
DiscreteMorseSandwich dms_ {}
 
BACKEND BackEnd {BACKEND::DISCRETE_MORSE_SANDWICH}
 
ttk::ProgressiveTopology progT_ {}
 
ttk::ApproximateTopology approxT_ {}
 
int StartingResolutionLevel {0}
 
int StoppingResolutionLevel {-1}
 
bool IsResumable {false}
 
double TimeLimit {}
 
void * outputScalars_ {}
 
void * outputOffsets_ {}
 
void * outputMonotonyOffsets_ {}
 
double Epsilon
 
- Protected Attributes inherited from ttk::Debug
int debugLevel_
 
std::string debugMsgPrefix_
 
std::string debugMsgNamePrefix_
 
- Protected Attributes inherited from ttk::BaseClass
bool lastObject_
 
int threadNumber_
 
Wrapper * wrapper_
 

Additional Inherited Members

- Protected Member Functions inherited from ttk::Debug
int printMsgInternal (const std::string &msg, const std::string &right, const std::string &filler, const debug::Priority &priority=debug::Priority::INFO, const debug::LineMode &lineMode=debug::LineMode::NEW, std::ostream &stream=std::cout) const
 
int printMsgInternal (const std::string &msg, const debug::Priority &priority, const debug::LineMode &lineMode, std::ostream &stream=std::cout) const
 
int welcomeMsg (std::ostream &stream)
 
- Static Protected Attributes inherited from ttk::Debug
static COMMON_EXPORTS debug::LineMode lastLineMode = ttk::debug::LineMode::NEW
 

Detailed Description

TTK processing package for the computation of persistence diagrams.

Compute the persistence diagram of a function on a triangulation. TTK assumes that the input dataset is made of only one connected component.

Author
Guillaume Favelier guill.nosp@m.aume.nosp@m..fave.nosp@m.lier.nosp@m.@lip6.nosp@m..fr
Julien Tierny julie.nosp@m.n.ti.nosp@m.erny@.nosp@m.lip6.nosp@m..fr
Date
September 2016.

This package computes the persistence diagram of the extremum-saddle pairs of an input scalar field. The X-coordinate of each pair corresponds to its birth, while its smallest and highest Y-coordinates correspond to its birth and death respectively.

In practice, each extremity of a persistence pair is represented by its vertexId and critical type. Based on that, the persistence of the pair and its 2D embedding can easily be obtained.

Persistence diagrams are useful and stable concise representations of the topological features of a data-set. It is useful to fine-tune persistence thresholds for topological simplification or for fast similarity estimations for instance.

Related publication
"Computational Topology: An Introduction"
Herbert Edelsbrunner and John Harer
American Mathematical Society, 2010

Five backends are available for the computation:

1) FTM
Related publication
"Task-based Augmented Contour Trees with Fibonacci Heaps" Charles Gueunet, Pierre Fortin, Julien Jomier, Julien Tierny IEEE Transactions on Parallel and Distributed Systems, 2019

2) Progressive Approach
Related publication
"A Progressive Approach to Scalar Field Topology"
Jules Vidal, Pierre Guillou, Julien Tierny
IEEE Transactions on Visualization and Computer Graphics, 2021

3) Discrete Morse Sandwich (default)
Related publication
"Discrete Morse Sandwich: Fast Computation of Persistence Diagrams for Scalar Data -- An Algorithm and A Benchmark"
Pierre Guillou, Jules Vidal, Julien Tierny
IEEE Transactions on Visualization and Computer Graphics, 2023.
arXiv:2206.13932, 2023.
Fast and versatile algorithm for persistence diagram computation.

4) Approximate Approach
Related publication
"Fast Approximation of Persistence Diagrams with Guarantees"
Jules Vidal, Julien Tierny
IEEE Symposium on Large Data Visualization and Analysis (LDAV), 2021

5) Persistent Simplex
This is a textbook (and very slow) algorithm, described in "Algorithm and Theory of Computation Handbook (Second Edition) - Special Topics and Techniques" by Atallah and Blanton on page 97.

See also
ttkPersistenceDiagram.cpp for a usage example.

Online examples:

Definition at line 165 of file PersistenceDiagram.h.

Member Enumeration Documentation

◆ BACKEND

enum class ttk::PersistenceDiagram::BACKEND
strong
Enumerator
FTM 
PROGRESSIVE_TOPOLOGY 
DISCRETE_MORSE_SANDWICH 
APPROXIMATE_TOPOLOGY 
PERSISTENT_SIMPLEX 

Definition at line 168 of file PersistenceDiagram.h.

Constructor & Destructor Documentation

◆ PersistenceDiagram()

PersistenceDiagram::PersistenceDiagram ( )

Definition at line 8 of file PersistenceDiagram.cpp.

Member Function Documentation

◆ augmentPersistenceDiagram()

template<typename scalarType , typename triangulationType >
void ttk::PersistenceDiagram::augmentPersistenceDiagram ( std::vector< PersistencePair > &  persistencePairs,
const scalarType *const  scalars,
const triangulationType *  triangulation 
)

Complete a ttk::DiagramType instance with scalar field values (useful for persistence) and 3D coordinates of critical vertices.

Definition at line 373 of file PersistenceDiagram.h.

◆ checkManifold()

template<class triangulationType >
void ttk::PersistenceDiagram::checkManifold ( const triangulationType *const  triangulation)

Definition at line 748 of file PersistenceDiagram.h.

◆ checkProgressivityRequirement() [1/2]

template<class triangulationType >
void ttk::PersistenceDiagram::checkProgressivityRequirement ( const triangulationType *  triangulation)

◆ checkProgressivityRequirement() [2/2]

template<class triangulationType >
void ttk::PersistenceDiagram::checkProgressivityRequirement ( const triangulationType *  ttkNotUsedtriangulation)

Definition at line 732 of file PersistenceDiagram.h.

◆ computeCTPersistenceDiagram()

template<typename scalarType >
int ttk::PersistenceDiagram::computeCTPersistenceDiagram ( ftm::FTMTreePP &  tree,
const std::vector< std::tuple< ttk::SimplexId, ttk::SimplexId, scalarType, bool > > &  pairs,
std::vector< PersistencePair > &  diagram 
) const

Definition at line 331 of file PersistenceDiagram.h.

◆ execute()

template<typename scalarType , class triangulationType >
int ttk::PersistenceDiagram::execute ( std::vector< PersistencePair > &  CTDiagram,
const scalarType *  inputScalars,
const size_t  scalarsMTime,
const SimplexId *  inputOffsets,
const triangulationType *  triangulation,
const std::vector< bool > *  updateMask = nullptr 
)
Precondition
For this function to behave correctly in the absence of the VTK wrapper, ttk::preconditionOrderArray() needs to be called to fill the inputOffsets buffer prior to any computation (the VTK wrapper already includes a mechanism to automatically generate such a preconditioned buffer).
See also
examples/c++/main.cpp for an example use.

Definition at line 393 of file PersistenceDiagram.h.

◆ executeApproximateTopology()

template<typename scalarType , class triangulationType >
int ttk::PersistenceDiagram::executeApproximateTopology ( std::vector< PersistencePair > &  CTDiagram,
const scalarType *  inputScalars,
const triangulationType *  triangulation 
)

Definition at line 591 of file PersistenceDiagram.h.

◆ executeDiscreteMorseSandwich()

template<typename scalarType , class triangulationType >
int ttk::PersistenceDiagram::executeDiscreteMorseSandwich ( std::vector< PersistencePair > &  CTDiagram,
const scalarType *  inputScalars,
const size_t  scalarsMTime,
const SimplexId *  inputOffsets,
const triangulationType *  triangulation,
const std::vector< bool > *  updateMask = nullptr 
)

Definition at line 514 of file PersistenceDiagram.h.

◆ executeFTM()

template<typename scalarType , class triangulationType >
int ttk::PersistenceDiagram::executeFTM ( std::vector< PersistencePair > &  CTDiagram,
const scalarType *  inputScalars,
const SimplexId *  inputOffsets,
const triangulationType *  triangulation 
)

Definition at line 678 of file PersistenceDiagram.h.

◆ executePersistentSimplex()

template<class triangulationType >
int ttk::PersistenceDiagram::executePersistentSimplex ( std::vector< PersistencePair > &  CTDiagram,
const SimplexId *  inputOffsets,
const triangulationType *  triangulation 
)

Definition at line 442 of file PersistenceDiagram.h.

◆ executeProgressiveTopology()

template<class triangulationType >
int ttk::PersistenceDiagram::executeProgressiveTopology ( std::vector< PersistencePair > &  CTDiagram,
const SimplexId *  inputOffsets,
const triangulationType *  triangulation 
)

Definition at line 635 of file PersistenceDiagram.h.

◆ getNodeType()

CriticalType PersistenceDiagram::getNodeType ( ftm::FTMTree_MT *  tree,
ftm::TreeType  treeType,
const SimplexId  vertexId 
) const

Definition at line 12 of file PersistenceDiagram.cpp.

◆ preconditionTriangulation()

void ttk::PersistenceDiagram::preconditionTriangulation ( AbstractTriangulation *  triangulation)
inline

Definition at line 268 of file PersistenceDiagram.h.

◆ setBackend()

void ttk::PersistenceDiagram::setBackend ( const BACKEND  be)
inline

Definition at line 178 of file PersistenceDiagram.h.

◆ setComputeMinSad()

void ttk::PersistenceDiagram::setComputeMinSad ( const bool  data)
inline

Definition at line 182 of file PersistenceDiagram.h.

◆ setComputeSadMax()

void ttk::PersistenceDiagram::setComputeSadMax ( const bool  data)
inline

Definition at line 188 of file PersistenceDiagram.h.

◆ setComputeSadSad()

void ttk::PersistenceDiagram::setComputeSadSad ( const bool  data)
inline

Definition at line 185 of file PersistenceDiagram.h.

◆ setDeltaApproximate()

void ttk::PersistenceDiagram::setDeltaApproximate ( double  data)
inline

Definition at line 300 of file PersistenceDiagram.h.

◆ setOutputMonotonyOffsets()

void ttk::PersistenceDiagram::setOutputMonotonyOffsets ( void *  data)
inline

Definition at line 291 of file PersistenceDiagram.h.

◆ setOutputOffsets()

void ttk::PersistenceDiagram::setOutputOffsets ( void *  data)
inline

Definition at line 294 of file PersistenceDiagram.h.

◆ setOutputScalars()

void ttk::PersistenceDiagram::setOutputScalars ( void *  data)
inline

Definition at line 297 of file PersistenceDiagram.h.

◆ sortPersistenceDiagram()

void ttk::PersistenceDiagram::sortPersistenceDiagram ( std::vector< PersistencePair > &  diagram,
const SimplexId *const  offsets 
) const

Definition at line 43 of file PersistenceDiagram.cpp.

Member Data Documentation

◆ approxT_

ttk::ApproximateTopology ttk::PersistenceDiagram::approxT_ {}
protected

Definition at line 315 of file PersistenceDiagram.h.

◆ BackEnd

BACKEND ttk::PersistenceDiagram::BackEnd {BACKEND::DISCRETE_MORSE_SANDWICH}
protected

Definition at line 312 of file PersistenceDiagram.h.

◆ contourTree_

ftm::FTMTreePP ttk::PersistenceDiagram::contourTree_ {}
protected

Definition at line 306 of file PersistenceDiagram.h.

◆ dcg_

dcg::DiscreteGradient ttk::PersistenceDiagram::dcg_ {}
protected

Definition at line 307 of file PersistenceDiagram.h.

◆ dms_

DiscreteMorseSandwich ttk::PersistenceDiagram::dms_ {}
protected

Definition at line 309 of file PersistenceDiagram.h.

◆ Epsilon

double ttk::PersistenceDiagram::Epsilon
protected

Definition at line 326 of file PersistenceDiagram.h.

◆ IgnoreBoundary

bool ttk::PersistenceDiagram::IgnoreBoundary {false}
protected

Definition at line 305 of file PersistenceDiagram.h.

◆ IsResumable

bool ttk::PersistenceDiagram::IsResumable {false}
protected

Definition at line 319 of file PersistenceDiagram.h.

◆ outputMonotonyOffsets_

void* ttk::PersistenceDiagram::outputMonotonyOffsets_ {}
protected

Definition at line 325 of file PersistenceDiagram.h.

◆ outputOffsets_

void* ttk::PersistenceDiagram::outputOffsets_ {}
protected

Definition at line 324 of file PersistenceDiagram.h.

◆ outputScalars_

void* ttk::PersistenceDiagram::outputScalars_ {}
protected

Definition at line 323 of file PersistenceDiagram.h.

◆ progT_

ttk::ProgressiveTopology ttk::PersistenceDiagram::progT_ {}
protected

Definition at line 314 of file PersistenceDiagram.h.

◆ psp_

PersistentSimplexPairs ttk::PersistenceDiagram::psp_ {}
protected

Definition at line 308 of file PersistenceDiagram.h.

◆ StartingResolutionLevel

int ttk::PersistenceDiagram::StartingResolutionLevel {0}
protected

Definition at line 317 of file PersistenceDiagram.h.

◆ StoppingResolutionLevel

int ttk::PersistenceDiagram::StoppingResolutionLevel {-1}
protected

Definition at line 318 of file PersistenceDiagram.h.

◆ TimeLimit

double ttk::PersistenceDiagram::TimeLimit {}
protected

Definition at line 320 of file PersistenceDiagram.h.

The documentation for this class was generated from the following files:
Generated on Thu Sep 26 2024 06:50:21 for TTK by doxygen 1.9.8