GCV(1)

NAME

gcv - geometry format converter

On this page

SYNOPSIS
DESCRIPTION
OPTIONS
IGES FILTER OPTIONS
EXAMPLES
SEE ALSO
AUTHOR
COPYRIGHT
BUG REPORTS

SYNOPSIS

gcv [options] [--input-format _fmt_] [--output-format _fmt_] _input_file_ _output_file_

gcv [options] -i _input_file_ -o _output_file_

gcv is the unified BRL-CAD geometry converter. It reads a model in one file format and writes it out in another, selecting the appropriate read and write filter plugins from libgcv based on the file format. Supported formats include the BRL-CAD database (.g), STEP, IGES, STL, and Wavefront OBJ, among others.

The input and output files may be given as the last two positional arguments, or named explicitly with -i and -o. When only one of -i or -o is used, the remaining positional argument supplies the other file.

The file format is normally inferred from the file extension. It may instead be stated with --input-format and --output-format, or with a multi-letter format prefix on the path itself in the form fmt:_path_ (e.g. step:model.stp). A single-letter prefix is not recognized as a format, so that Windows drive letters are not misinterpreted.

Per-filter options may be passed through to the read filter, the write filter, or both, allowing format-specific behavior to be tuned without gcv needing to know about each option.

OPTIONS

-h, --help [format]: Print help and exit. If a format is named, format-specific help is intended to be printed for it.
-? [format]: Same as -h.
-i file, --input file: Read geometry from file. The file must exist.
-o file, --output file: Write geometry to file. If file already exists, conversion output is appended where the write filter supports it.
--input-format format: Set the input file format explicitly (e.g. step, iges, stl, obj), overriding extension- and prefix-based detection.
--output-format format: Set the output file format explicitly.
-I opts, --input-only-opts opts: Pass opts only to the input (read) filter. Consumes arguments until the next top-level gcv option is encountered.
-O opts, --output-only-opts opts: Pass opts only to the output (write) filter. Consumes arguments until the next top-level gcv option is encountered.
-B opts, --input-and-output-opts opts: Pass opts to both the input and output filters. Consumes arguments until the next top-level gcv option is encountered.

IGES FILTER OPTIONS

The IGES reader and writer share their conversion implementation with iges-g(1) and g-iges(1). Native CSG, exact B-Reps, and NMG conversion remain available without changing BRL-CAD’s library interfaces.

The reader accepts --breps-only (solid and surface geometry, including native CSG), --drawings-only, --3d-drawings, --exact, --strict, --repair none|safe|best-effort, --relative-tolerance fraction, and --max-repair-tolerance mm through -I. By default it attempts both model geometry and drawings; a drawing-only file retains its model-space planes. The relative boundary repair target defaults to 0.0001 of the local bounding box diagonal. Strict mode rejects repaired or partial imports. Safe and best-effort imports also correct clearly inward or inconsistently oriented isolated closed BRep shells, using the same low-memory signed-volume check as iges-g. Open, nested, overlapping, and uncertain shells are left unchanged. Orientation corrections are diagnosed and recorded on the objects.

The writer preserves native CSG where representable and uses exact B-Reps for supported non-CSG primitives. Its -O options are --faceted, --trimmed-surfaces, --nurbs, and --flatten-brep, corresponding to the same export modes in g-iges. Tessellation is explicit for regions; existing polyhedral geometry retains the NMG export path. Output replaces the destination only after a complete IGES file has been written. A partial export reports failure even when a readable subset has been written. The filters honor IGES file units; a non-unit libgcv scale override is rejected rather than silently ignored.

EXAMPLES

Example 1. Convert a STEP file into a BRL-CAD database

gcv assembly.stp assembly.g

Reads the STEP file assembly.stp and writes a BRL-CAD database assembly.g. Both formats are detected from the file extensions, after which the result can be inspected with mged(1) or rendered with rt(1).

Example 2. Tune a filter while converting OBJ to a .g database

gcv -I --units mm model.obj model.g

Converts a Wavefront OBJ mesh to a BRL-CAD database, passing the --units mm option only to the OBJ read filter so that the source coordinates are interpreted as millimeters.

Example 3. Override detection with explicit formats

gcv --input-format step --output-format stl in.dat out.dat

Forces the input to be read as STEP and the output written as STL even though the .dat extensions give no hint of the formats involved.