## Name

rtarea — Calculate exposed and presented surface areas

## Synopsis

`rtarea` [`options`...] `model.g` `objects`...

## DESCRIPTION

The rtarea command calculates the exposed, presented and centers of surface areas of specified geometry objects from a particular view. The summary output includes details for individual regions, assemblies (combinations that contain regions), and summarized totals.

The exposed area corresponds to what a human observer would see looking at the object(s) in question, if all the objects were non-transparent. For example, say rays were cast towards two cubes, each one of which is a region, one in front of the other, grouped into an assembly, with the ray direction pointed into the page:

    |----------------| Rear Cube
    |                |
    |                |
    |        |--------------| Front Cube
    |        |       |      |
    |        |       |      |
    |--------|-------|      |
             |              |
             |              |
             |--------------|

The exposed area of the Front Cube corresponds to the total area of the sheet, since it is not occluded by any other object:

    |----------------| Rear Cube
    |                |
    |                |
    |        |--------------| Front Cube
    |        |**************|
    |        |**************|
    |--------|**************|
             |**************|
             |**************|
             |--------------|

The Rear Cube, on the other hand, IS occluded by the Front Cube and would thus report only a fraction of its area as exposed:

    |----------------| Rear Cube
    |****************|
    |****************|
    |********|--------------| Front Cube
    |********|       |      |
    |********|       |      |
    |--------|-------|      |
             |              |
             |              |
             |--------------|

An object that combines both of these sheets would thus report as its exposed area the sum of the exposed areas of the individual sheets:

    |----------------| Rear Cube
    |****************|
    |****************|
    |****************|------| Front Cube
    |***********************|
    |***********************|
    |--------|**************|
             |**************|
             |**************|
             |--------------|

Presented area, unlike exposed area, does not take occlusion into account. It is the equalivent of taking each object and considering it in isolation. So for the previous case of two sheets of metal, the Front Cube would report the same area:

    |----------------| Rear Cube
    |                |
    |                |
    |        |--------------| Front Cube
    |        |**************|
    |        |**************|
    |--------|**************|
             |**************|
             |**************|
             |--------------|

the Rear Cube, on the other hand, ALSO reports its full area:

    |----------------| Rear Cube
    |****************|
    |****************|
    |****************-------| Front Cube
    |****************|      |
    |****************|      |
    |--------|-------|      |
             |              |
             |              |
             |--------------|

When reporting the presented area of the group, there is a subtle point - rtarea does not count area covered by multiple regions multiple times when totaling the presented area. So for the group containing both cubes, the presented area is NOT the cumulative area of both regions' presented areas but the area of the union of those two areas. In this case, that works out to be the same as the exposed area.

    |----------------| Rear Cube
    |****************|
    |****************|
    |****************|------| Front Cube
    |***********************|
    |***********************|
    |--------|**************|
             |**************|
             |**************|
             |--------------|

It should be noted that rtarea only counts surfaces with a surface normal that has a component looking back in the direction of the ray. So, for example, a cube with only one face looking "back toward" the ray will not report area from other faces as "presented", since their surface normals will indicate they are not surfaces being presented to the ray.

WARNING: Rtarea may not correctly report area or center when instancing is done at the group level. Using xpush can be a workaround for this problem.

The model geometry is the list of objects in the input database model.g.

`-X #`

  Sets rtarea debug flags to a (hexadecimal) number. A flag value of 1 causes 3-D plot output to be written to stdout. All solid RPPs are plotted as grey boxes, and the walk path is in alternating blue and green segments. A flag value of 2 adds red segments for all attempted steps, as well as the final steps. A flag value of 3 adds some debugging prints to stderr in addition to the plots. This is useful for immediate path review, e.g., `rtarea -X 1 ... | tiris`

`-x #`

  Sets librt debug flags to a (hexadecimal) number.

`-n #`

  Number of steps.

The rtarea program employs librt(3) for the geometry interrogation.

## ADDITIONAL OPTIONS

To configure its behavior, rtarea makes use of the `-c` option.

Note that this approach is necessitated by the fact that librt (3) has used up nearly the entire alphabet. A transition to GNU-style long option names is planned.

`-c "set compute_centers=#"`

  and

`-c "set cc=#"`

  determine whether area centers should be computed and reported. Valid values are 1 (on) and 0 (off). The default is off.

## EXAMPLES

Example 1. Rtarea processing of example.g

The command `rtarea example.g all` computes the area for model 'example.g' group 'all'.

The command `rtarea -c "set cc=1" example.g all` computes the area and centers for model 'example.g' group 'all'.

## SEE ALSO

mged(1), rt(1), pix-fb(1), librt(3), pix(5).

## DIAGNOSTICS

Numerous error conditions are possible. Descriptive messages are printed on stderr.

## COPYRIGHT

This software is Copyright (c) 1987-2011 United States Government as represented by the U.S. Army Research Laboratory. All rights reserved.

## BUG REPORTS

Reports of bugs or problems should be submitted via electronic mail to <bugs@brlcad.org>.