TREETOPGM(1) Version 1.1 TREETOPGM(1)
File Utilities File Utilities
22nd January, 1998
NAME
treetopgm - make a listing from `find' into a graphical tree
SYNOPSIS
treetopgm > output.pgm
or
treetopgm -t > output.tga
or
treetopgm -m > output.mrf
Usually, you use find(1) to produce a hierarchy to convert into the
graphical tree (and sort(1) to sort it), for example:
find . -type d -print | sort -f | treetopgm > output.pgm
DESCRIPTION
Treetopgm reads a list such as that produced by `find' on standard
input, and outputs (on standard output) a graphical tree showing the
directory (or dir. and file) hierarchy as a tree of interconnected
boxes. The tree is output as a bitmap, specifically a pgm file. (See
pgm(5) for a description of the format.) Most picture viewers can view
pgm files.
OPTIONS
-m output an mrf file rather than a pgm file. Since mrf only
supports 1-bit mono files, the box's shading is lost. Mrf should
usually give the smallest files of the three output options (half
the size of TGA is not uncommon), but is not very widely
supported at the time of writing.
-t output a compressed Targa (TGA) file rather than a pgm file.
These files tend to take up over 90% less disk space than the
equivalent pgm.
The facility to output TGA or mrf files, although it doesn't logically
belong in the program, was added due to the prohibitively large memory
use conversion utils tend to require for the large files treetopgm can
output. (This feature is a miswart - inconsistent with the `do one
thing well' software tools philosophy, but a practical kludge given
the circumstances.)
The TGA file output is type 9, a run-length encoded palette-based
file. It should be viewable on any viewer which supports TGA files.
I'm not sure if xv supports TGA or not, but zgv and xli do. As for
mrf, zgv v3.0 can view mrf files but (at the time of writing) few if
any other viewers can. (This could conceivably have changed by the
time you read this though, so it's best to check for yourself.)
Only output files smaller than 65536 pixels across can be output in
TGA format. This can be a problem for large trees. If you use `-t'
- 1 - Formatted: August 19, 2008
TREETOPGM(1) Version 1.1 TREETOPGM(1)
File Utilities File Utilities
22nd January, 1998
with output wider than 65535 pixels, treetopgm falls back on using pgm
instead (and warns you about this). Many file formats are limited to
16-bit picture dimensions like this; see the DEALING WITH LARGE OUTPUT
FILES section for details. Mrf uses 32-bit picture dimensions and so
doesn't have this restriction.
USING (AND ABUSING) THE PROGRAM
As mentioned above, treetopgm is usually used to print directory
trees, and some variant of the example use given in the SYNOPSIS
section will usually do what you want in this regard. But, you can
also use it for any kind of `find -print' output, including full
`find' listings with files as well as dirs. The only potential
problems with this are that the tree (and thus the pgm file) rapidly
gets large if there are many files to a directory, and that there is
no way to tell the difference between a file and an empty directory.
(This is true of the `find' output itself, of course, but it becomes
more obvious in the treetopgm output.)
In fact, there's no reason why you should be restricted to output from
`find'. (Hence `abusing' in the section title. :-)) You can use
anything you want as input to treetopgm, provided it conforms to the
`find -print' format. After suitable grinding with sed(1), awk(1), or
perl(1), just about any hierarchy could be translated into this
format, and then converted to a graphical tree with treetopgm.
I'm not sure what applications this could have. One thing which
springs to mind is something to show the hierarchy of C++ classes, but
clearly you'd need to have another program to do the hard work in that
case (not being a C++ fan, I don't know what's available to do this).
Another is grinding output from `cflow', which, though a little
tricky, is far from impossible. (In fact, I've written an `awk' script
to do this latter conversion. It's included with treetopgm; do
something like this:
cflow -x foo.c | awk -f altcflow.awk | treetopgm >output.pgm
to produce a pgm using it. The output tends to look nicer if you use
the `-x' option to cflow, as above. Note that `altcflow.awk' isn't
installed anywhere by `make install', so if you want to use it be sure
to keep a copy handy!)
To make clear what I mean by the `find -print' format, and also to
point out how treetopgm parses it, the next section contains a
description.
INPUT FORMAT, AND PARSING
This section describes the input format, and how it's parsed. These
terms are used:
- 2 - Formatted: August 19, 2008
TREETOPGM(1) Version 1.1 TREETOPGM(1)
File Utilities File Utilities
22nd January, 1998
node a single point in the tree - for usual `find -print' output, this
would be a directory (or a file).
subnode
a node N levels lower down the tree.
root the top node of the tree, which all others are children of.
header
the name of the root node (the first input line, minus any
trailing `/').
So, on with the description:
There must always be at least one line, representing the name of the
root node. If this ends in a `/', it is disregarded. The remaining
string, the `header', is stripped from the remaining lines before
further parsing.
So, for the remaining lines, after the header has been removed, the
following happens. The initial `/' is removed, then the line is
treated as a `/'-separated path to a subnode, and any nodes not
already created along this path are created. This determines the
left-to-right order of nodes such that the Right Thing is done for
sorted input, but equally, means that unsorted input is acceptable
too.
That's it. Quite simple really. Though somehow, it didn't seem that
simple when I was writing it... :-)
DEALING WITH LARGE OUTPUT FILES
There can be some problems when the output exceeds certain limits; not
to do with treetopgm itself, which uses dynamic allocation everywhere,
but with further processing you may wish to do with the pgm file
output.
Conversion to some picture formats is impossible with pictures wider
than 65535 pixels. (You can sometimes get output this wide, when
displaying large or oddly-shaped trees - usually, it's due to a
combination of the two.) Formats known to have this restriction are
GIF, JPEG/JFIF, TGA, and PCX. Formats known to not have the problem
are PBM/PGM/PPM, BMP, PNG, and mrf. (I don't know about other
formats.) If you do end up with a pgm this wide, you'll have to use
one of the latter formats - I recommend either PNG or mrf, if your
software supports one of them.
The trees output by treetopbm compress very well even with crude
compression techniques like RLE, so converting to another format can
often be a good idea if you don't happen to have enough disk space for
- 3 - Formatted: August 19, 2008
TREETOPGM(1) Version 1.1 TREETOPGM(1)
File Utilities File Utilities
22nd January, 1998
the pgm. Using treetopgm's built-in TGA or mrf conversion with `-t' or
`-m' is an easy way to do this.
The other major problem tends to be one of memory. Treetopgm tells you
how many kilobytes the pgm it's outputting is - but consider that many
conversion utils, especially ones converting to palette-based formats,
will read in the whole image before doing anything, often in 24-bit
format. You can see the problem that can arise if you don't have much
memory.
Here's a real-world example. I tried to generate a tree of my home
directory, which was about 7100k in pgm format, in PNG format by
piping it through pnmtopng(1). This meant that, at one point,
(7100*4) = 28400k, just under 28Mb, of memory was needed on my machine
simultaneously. I currently have a ram+swap total of 26972k, so this
simply wasn't possible. Often, if you have the disk space, you can
just use a temporary file to store the pgm rather than using a
pipeline, which saves you 25% of the memory usage. But if this isn't
enough, and you can't find a less greedy conversion utility, you're
stuck up a certain creek without a rowing implement. :-(
That said, one easy way to cut the file size by 86% is to convert the
pgm to a pbm file. This is 1-bit mono, but that doesn't lose you much.
You can convert a pgm output by treetopgm with:
cat output.pgm | pgmtopbm -th -v 0.5 >output.pbm
Pgmtopbm doesn't take up very much memory, so using the above
`pgmtopbm' invocation at the end of a pipeline shouldn't be a problem.
And, of course, you can always use treetopgm's `-t' or `-m' options to
generate a TGA or mrf file without requiring any conversion utils at
all. This compresses straight from the in-memory pixmap, and takes no
more memory than treetopgm does ordinarily. (But as mentioned above,
the TGA output can only work for files no wider than 65535 pixels due
to the limitations of the format.)
MISCELLANEOUS
To use a coloured box interior rather than the light-grey normally
used, pipe the treetopgm output through `ppmchange', specifically,
something like `ppmchange \#e0e0e0 wheat1' to use `wheat1' as the
colour. You can use any colour name in X11's /usr/lib/X11/rgb.txt
database, or an RGB colour. See the ppmchange(1) man page for details.
Note that as you might expect, the output from ppmchange is a ppm
file, and it'll therefore be three times the size of the equivalent
pgm file!
Unless you have a fairly small directory tree, or have a lot of
memory, don't bother piping `find / -type d -print' into treetopgm. On
- 4 - Formatted: August 19, 2008
TREETOPGM(1) Version 1.1 TREETOPGM(1)
File Utilities File Utilities
22nd January, 1998
my machine, this needs about 30Mb. But the real problem with such
large files is what a pain they are to navigate. Use a more specific
path instead, or limit the depth of the search to `n' dir. levels with
the `-maxdepth n' option to `find' (this is generally better if all
you want is an overview, in any case).
To see how big a file treetopgm would generate without generating it,
do (under sh, bash, etc.) `... | treetopgm 2>&1 | head -1' - under csh
and tcsh, do `... | treetopgm |& head -1'. (On zsh, both forms work.)
The advantage of these over simply redirecting the output to /dev/null
is that since `head' only reads one line then exits, treetopgm stops
after outputting that one line, and never generates the pgm at all.
For large files, this is very much faster.
BUGS
The tree produced is not space-optimised. In some (rare, I believe)
circumstances, you may end up with vast wide open spaces which needn't
have been there; even for more normal cases, you end up with the odd
bit of wasted space. I am reluctant to `fix' this, as the current
behaviour is nicely deterministic.
For dirs with many subdirs, the connecting lines can just become a
horrible black mess. There's nothing I can really do about this
without using masses of vertical space, which would make the output
much bigger than it already is!
The tilde char (`~') looks quite bizarre in the font used for the
text. (It's tough to represent it in characters that small.)
Only flat-ascii `node' names are correctly represented, with chars
other than printable ascii mapped to underscore (`_'). This means no
Latin-1 support (nor Unicode, for that matter). Sorry.
Treetopbm will probably give rather odd output if given invalid or
malformed input. (But, this shouldn't be a problem.)
ACKNOWLEDGEMENTS
I would never have written this utility had I not seen Sun's file
manager for `Open Windows', which uses (it did at the time I used it,
anyway, it may or may not do now) a similar display to show dir.
hierarchies. Treetopgm may not produce output as nice as that, but
seeing it was inspirational, even if it took me over three years to
get around to attempting something like it!
Also, Phil Hughes' natty `dtree' program (and the article describing
it) in the September 1996 Linux Journal got me thinking about the
display of directory trees, so that deserves a mention.
AUTHOR
- 5 - Formatted: August 19, 2008
TREETOPGM(1) Version 1.1 TREETOPGM(1)
File Utilities File Utilities
22nd January, 1998
Russell Marks.
SEE ALSO
find(1), pgm(5), mrf(5), zgv(1), xv(1), xli(1)
Zgv, xv and xli are viewers capable of viewing pgm files directly. If
you lack a viewer capable of this and need to convert the pgm to some
other format, or wish to grind the file in other ways, use the pbmplus
or netpbm toolkit. (At the time of writing, I believe netpbm is better
and more current.)
- 6 - Formatted: August 19, 2008
|
