NAME

#

pict.tree - Compute the 0th and (n-1)th persistent-homology merge trees of an N-dimensional picture

SYNOPSIS

#

homcloud-pict-tree
    [-h] [-V] [--license] -m MODE [-t THRESHOLD] [--gt GT]
    [--lt LT] [-s] [--metric METRIC] [-T TYPE] [-O OUTPUT_TYPE]
    -o OUTPUT
    [input ...]

This program can also be invoked as python3 -m homcloud.cli.pict.tree.

ALIAS

#

homcloud-pict-tree

DESCRIPTION

#

This program computes the persistence-diagram merge trees (union-find style “PH trees”) for the 0th degree and the (n-1)th degree of an N-dimensional picture, in one pass, and writes them to OUTPUT. Merge trees additionally record, for every birth-death pair, which pixels merged into which (via parent/children links and each node’s volume), unlike a plain persistence diagram.

-m selects how the input picture is turned into a filtration before the merge trees are computed:

• -m black-base / -m white-base binarize the picture (same binarization/threshold options as homcloud-pict-binarize-nd, under the “for binarize” group below) and then build the merge trees from the distance transform of the binarized picture.
• -m sublevel / -m superlevel build the merge trees directly from the picture’s pixel values (same meaning as in homcloud-pict-pixel-levelset-nd), without binarization.

OPTIONS

#

-h, --help            show this help message and exit
-V, --version         show program's version number and exit
--license             show license and exit
-m MODE, --mode MODE  mode (white-base or black-base for binarize,
                      superlevel or sublevel for levelset)

for binarize:
  -t THRESHOLD, --threshold THRESHOLD
                      threshold for binarization (default: 128)
  --gt GT             lower threshold
  --lt LT             upper threshold
  -s, --ensmall       ensmall binarized picture
  --metric METRIC     metric used to enlarge binarized image
                      (manhattan(default), euclidean, etc.)

for input and output:
  -T TYPE, --type TYPE
                      input data format (text2d, text_nd(default),
                      picture2d, picture3d, npy)
  -O OUTPUT_TYPE, --output-type OUTPUT_TYPE
                      output file format (json, msgpack, pdgm(default))
  -o OUTPUT, --output OUTPUT
                      output file

The “for binarize” options only apply when -m is black-base or white-base; they are ignored for sublevel/superlevel.

INPUT FILE FORMAT

#

Same formats as homcloud-pict-binarize-nd: text2d, text_nd, picture2d, picture3d, and npy. See that document for the detailed format description.

OUTPUT FORMAT

#

-O pdgm (default)

#

A .pdgm file (bitmap-tree filtration type) containing:

• the ordinary persistence-diagram pairs for degree 0 and for degree (n-1), where n is the dimension of the input picture, and

• a bitmap_phtrees chunk per degree, readable via homcloud.pdgm_format.PDGMReader, that maps each (non-boundary) merge-tree node id to:

  {
      "id": int,
      "birth-time": float,
      "death-time": float,
      "birth-pixel": pixel or null,
      "death-pixel": pixel or null,
      "volume": array of pixel,   /* all pixels merged into this node */
      "parent": int or null,
      "children": array of int
  }
  

  This is the same chunk format that homcloud-pict-show-volume-2d reads to draw volumes.

-O json / -O msgpack

#

A JSON (or msgpack-encoded) object:

{
    "dim": int,               /* dimension of the input picture */
    "sign-flipped": bool,     /* true when -m superlevel */
    "lower": mergetree,       /* degree-0 merge tree */
    "upper": mergetree        /* degree-(dim-1) merge tree */
}

mergetree: {
    "degree": int,
    "nodes": { "<node-id>": node, ... }
}

node has the same fields as listed in the pdgm case above.

EXAMPLES

#

# Binarize a 3D picture (black-base) and compute both merge trees as a pdgm file
homcloud-pict-tree -m black-base -t 100 -T picture3d -o tree.pdgm slice*.png

# Build merge trees directly from a sublevel filtration of an npy volume, as JSON
homcloud-pict-tree -m sublevel -T npy -O json -o tree.json volume.npy