EXISTS(nged)

NAME

exists - The *exists* command evaluates an expression and returns 1 if true, 0 if false. It serves roughly the same purpose for objects in a BRL-CAD database that the UNIX test command serves for files on a file system, with additional features specific to geometry.

On this page

SYNOPSIS
DESCRIPTION
PRIMARIES:
OPERATORS:
A Note on Expressions
EXAMPLES
DIAGNOSTICS
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

exists {expression} [expression]...

DESCRIPTION

exists evaluates boolean expressions about objects in the currently open database, returning 1 (true) or 0 (false). It is modelled on Unix-style test(1) commands (internally based on NetBSD’s test code), but tests objects rather than files.

Expressions are built from PRIMARIES and OPERATORS. A bare object name with no primary or operator returns true if the object exists in the database and is not a phony placeholder (same as -N).

On a parse error (e.g. missing operand, unmatched parenthesis) the command returns an error status and writes a diagnostic message rather than 0.

PRIMARIES:

-c object: Returns TRUE if object exists and is a combination.
-e object: Returns TRUE if object exists. This reports only the result of db_lookup without further checking, and is the most basic existence test.
-n object: Returns TRUE if object exists in the directory but is a phony placeholder (its d_addr is RT_DIR_PHONY_ADDR, meaning it has been added to the directory but not yet written to disk). Ordinary objects are never null.
-p object: Returns TRUE if object exists and is a geometric primitive (i.e. it has the solid flag set and is not a non-geometry object). Empty geometric primitives and 2D primitives like sketch pass this test.
-v object: Returns TRUE if object exists and its axis-aligned bounding box has non-zero volume. A sketch primitive (2D) does not pass this test; neither does a missing object.
object1 = object2: Returns TRUE if both objects exist and the serialised geometry bodies of both objects are identical (same length and same bytes). The object name is excluded from the comparison, so a direct copy of an object using cp will compare as equal.
object1 != object2: Returns TRUE if both objects exist and their serialised geometry bodies differ (different length or at least one differing byte).
object1 < object2: Returns TRUE if both objects exist and the size (in bytes) of the serialised geometry body of object1 is less than that of object2.
object1 > object2: Returns TRUE if both objects exist and the size (in bytes) of the serialised geometry body of object1 is greater than that of object2.
object1 -beq object2: Returns TRUE if both objects exist and the volumes of their bounding boxes are equal (within floating-point tolerance).
object1 -bne object2: Returns TRUE if both objects exist and the volumes of their bounding boxes are not equal.
object1 -bgt object2: Returns TRUE if both objects exist and the bounding-box volume of object1 is strictly greater than that of object2.
object1 -bge object2: Returns TRUE if both objects exist and the bounding-box volume of object1 is greater than or equal to that of object2.
object1 -blt object2: Returns TRUE if both objects exist and the bounding-box volume of object1 is strictly less than that of object2.
object1 -ble object2: Returns TRUE if both objects exist and the bounding-box volume of object1 is less than or equal to that of object2.

OPERATORS:

primaries can be combined with the following operators:

! expression: True if expression is false.
expression -a expression: The and operator - TRUE only if both expressions are true.
expression -o expression: The or operator - true if either expression is true.
( expression ): Evaluates to true if the expression inside the parentheses evaluates to true. Used to establish order of operations.

The -a operator has higher precedence than the -o operator.

A Note on Expressions

All primaries and operands must be expressed as separate arguments to exists. In practice, this means that there must be a space between each element in an exists expression. E.g. !(-c object1.s -a (object1.s -beq object2.s)) must be written as:

! ( -c object1.s -a ( object1.s -beq object2.s ) )

While this may seem like a rather verbose way of writing the expression, it greatly simplifies the parsing of the expression and is standard for virtually all test type commands.

EXAMPLES

The following are run from the MGED command prompt:

Example 1. Check whether an object exists

mged> exists object1.s
1

Example 2. Check if an object is a combination

mged> exists -c object1.r
1

Example 3. Use logical operators

mged> exists -c object1.r -a -e object1.s
1

Example 4. Compare bounding-box volumes

mged> exists big_sphere.s -bgt small_sphere.s
1

DIAGNOSTICS

Returns 1 (true) or 0 (false) on success, and writes a diagnostic message to the result string while returning an error status on parse failures (missing operands, unmatched parentheses, or unexpected tokens).

AUTHOR

BRL-CAD Team

COPYRIGHT

This software is Copyright (c) 2008-2026 United States Government as represented by the U.S. Army Research Laboratory. Portions Copyright 1990, 1993, 1994 The Regents of the University of California, per copyright and license information from OpenBSD and NetBSD. For more details see the copyright statements in exists.c.

BUG REPORTS

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