↓ Skip to main content
HomCloud

NAME
#

pict.show_volume_2d - Draw optimal-volume pixels on a 2D picture from a merge-tree pdgm file

SYNOPSIS
#

homcloud-pict-show-volume-2d
    [-h] [-V] -d DEGREE [-f FILTER]
    [-v VECTORIZED_HISTOGRAM_MASK] [-H HISTOINFO] [-B]
    [-D] [--volume] [--birth-color BIRTH_COLOR]
    [--death-color DEATH_COLOR] [--volume-color VOLUME_COLOR]
    [--alpha ALPHA] [-S MARKER_SIZE] [-o OUTPUT]
    picture diagram

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

ALIAS
#

homcloud-pict-show-volume-2d

DESCRIPTION
#

This program draws, on top of a 2D picture, the birth/death pixels and/or the volume pixels of every birth-death pair recorded in a merge-tree .pdgm file produced by homcloud-pict-tree.

picture is the original picture file, and diagram is a .pdgm file written by homcloud-pict-tree (which stores a bitmap_phtrees chunk for degree 0 and for degree (n-1) of the input picture). -d must be 0 or n-1, matching one of those two degrees.

Nodes whose death time equals their birth time, or whose death time is missing (essential/boundary nodes), are skipped.

-f/--filter can be given multiple times to select only the nodes that satisfy all of the given predicates, e.g. -f "lifetime > 5.0". The supported predicate targets are lifetime, birth, and death, and the supported operators are >, <, >=, <=, and ==.

Alternatively, -v/--vectorized-histogram-mask together with -H/--histoinfo selects nodes by a 0/1 mask vector produced from a vectorized histogram (see homcloud-vectorize-PD); both options must be given together.

OPTIONS
#

-h, --help            show this help message and exit
-V, --version         show program's version number and exit
-d DEGREE, --degree DEGREE
                      degree of PH
-f FILTER, --filter FILTER
                      filters (ex: "lifetime > 5.0")
-v VECTORIZED_HISTOGRAM_MASK, --vectorized-histogram-mask VECTORIZED_HISTOGRAM_MASK
                      0-1 vector textfile for mask
-H HISTOINFO, --histoinfo HISTOINFO
                      vectorize histogram information (both -v and -H are
                      required)
-B, --birth           plot birth pixels
-D, --death           plot death pixels
--volume              plot volume pixels
--birth-color BIRTH_COLOR
                      birth pixel color
--death-color DEATH_COLOR
                      death pixel color
--volume-color VOLUME_COLOR
                      volume pixels color
--alpha ALPHA         alpha value for volume pixels
-S MARKER_SIZE, --marker-size MARKER_SIZE
                      marker size (default: 1)
-o OUTPUT, --output OUTPUT
                      output filername

--birth-color, --death-color, and --volume-color accept a color in #rrggbb hex form (e.g. #ff0000). --alpha (default: 0.5) blends --volume-color with the original pixel color for each volume pixel when --volume is given.

OUTPUT
#

If -o is given, the annotated picture is saved to that path. If -o is not given, the picture is drawn in memory but not displayed or saved anywhere, so the program effectively does nothing visible; always pass -o in practice.

EXAMPLE
#

homcloud-pict-tree -m black-base -t 100 -T picture2d -o tree.pdgm slice.png
homcloud-pict-show-volume-2d -d 0 -B -D --volume -f "lifetime > 3.0" -o annotated.png slice.png tree.pdgm