bot.h

Go to the documentation of this file.

/*                        B O T . H
 * BRL-CAD
 *
 * Copyright (c) 1993-2026 United States Government as represented by
 * the U.S. Army Research Laboratory.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public License
 * version 2.1 as published by the Free Software Foundation.
 *
 * This library is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this file; see the file named COPYING for more
 * information.
 */
/** @addtogroup rt_bot */
/** @{ */
/** @file rt/primitives/bot.h */
 
#ifndef RT_PRIMITIVES_BOT_H
#define RT_PRIMITIVES_BOT_H
 
#include "common.h"
#include "vmath.h"
#include "bu/ptbl.h"
#include "bn/tol.h"
#include "nmg.h"
#include "rt/geom.h"
#include "rt/defines.h"
#include "rt/tol.h"
#include "rt/view.h"
#include "rt/soltab.h"
 
__BEGIN_DECLS
#ifdef USE_OPENCL
/* largest data members first */
struct clt_bot_specific {
    cl_ulong offsets[5]; /* header, bvh, tris, norms. */
    cl_uint ntri;
    cl_uchar orientation;
    cl_uchar flags;
    cl_uchar pad[2];
};
 
struct clt_tri_specific {
    cl_double v0[3];
    cl_double v1[3];
    cl_double v2[3];
    cl_int surfno;
    cl_uchar pad[4];
};
#endif
 
/* Shared between bot and ars at the moment */
struct bot_specific {
    unsigned char bot_mode;
    unsigned char bot_orientation;
    unsigned char bot_flags;
    size_t bot_ntri;
    fastf_t *bot_thickness;
    struct bu_bitv *bot_facemode;
    void *bot_facelist; /* head of linked list */
    void **bot_facearray;       /* head of face array */
    void *tie; /* FIXME: horrible blind cast, points to one in rt_bot_internal */
 
#ifdef USE_OPENCL
    struct clt_bot_specific clt_header;
    struct clt_tri_specific *clt_triangles;
    cl_double *clt_normals;
#endif
};
 
 
// this is really close to struct tri_specific in plane.h
// TODO: see if that ever gets serialized, and if it doesn't
// then change that to this - memory coherency win
// sizeof(triangle_s) should be 15/16 * (4/8) bytes
typedef struct _triangle_s {
    point_t A;
    vect_t AB;
    vect_t AC;
    vect_t face_norm;
    fastf_t face_norm_scalar;
    fastf_t *norms;
    size_t face_id;
} triangle_s;
 
// BoT specific editing info
struct rt_bot_edit {
    int bot_verts[3];           /* vertices for the BOT solid */
};
 
/* bot.c */
RT_EXPORT extern size_t rt_bot_get_edge_list(const struct rt_bot_internal *bot,
                                             size_t **edge_list);
RT_EXPORT extern int rt_bot_edge_in_list(const size_t v1,
                                         const size_t v2,
                                         const size_t edge_list[],
                                         const size_t edge_count0);
RT_EXPORT extern int rt_bot_plot(struct bu_list         *vhead,
                                 struct rt_db_internal  *ip,
                                 const struct bg_tess_tol *ttol,
                                 const struct bn_tol    *tol,
                                 const struct bview *info);
RT_EXPORT extern int rt_bot_plot_poly(struct bu_list            *vhead,
                                      struct rt_db_internal     *ip,
                                      const struct bg_tess_tol *ttol,
                                      const struct bn_tol       *tol);
RT_EXPORT extern int rt_bot_find_v_nearest_pt2(const struct rt_bot_internal *bot,
                                               const point_t    pt2,
                                               const mat_t      mat);
RT_EXPORT extern int rt_bot_find_e_nearest_pt2(int *vert1, int *vert2, const struct rt_bot_internal *bot, const point_t pt2, const mat_t mat);
RT_EXPORT extern fastf_t rt_bot_propget(struct rt_bot_internal *bot,
                                        const char *property);
RT_EXPORT extern int rt_bot_vertex_fuse(struct rt_bot_internal *bot,
                                        const struct bn_tol *tol);
RT_EXPORT extern int rt_bot_face_fuse(struct rt_bot_internal *bot);
RT_EXPORT extern int rt_bot_condense(struct rt_bot_internal *bot);
RT_EXPORT extern int rt_bot_smooth(struct rt_bot_internal *bot,
                                   const char *bot_name,
                                   struct db_i *dbip,
                                   fastf_t normal_tolerance_angle);
RT_EXPORT extern int rt_bot_flip(struct rt_bot_internal *bot);
RT_EXPORT extern int rt_bot_sync(struct rt_bot_internal *bot);
 
/**
 * Build a compact BOT from replacement faces whose vertex indices reference
 * the source BOT.  face_sources maps every replacement face to its original
 * source face, allowing thickness, face mode, normals, and texture UVs to be
 * preserved.  Replacement triangles must retain the corner ordering of their
 * source faces; face_sources identifies faces but does not describe a separate
 * corner permutation.  The caller owns the returned BOT.
 *
 * Returns NULL for malformed input or an invalid vertex or face reference.
 */
RT_EXPORT extern struct rt_bot_internal *rt_bot_gc(
        const struct rt_bot_internal *bot, const int *faces,
        const int *face_sources, size_t face_count);
 
/**
 * Build a compact BOT from selected input faces.  face_indices identifies the
 * original faces, in output order, so all per-face and per-corner data can be
 * preserved and remapped along with the referenced vertices.  This is the
 * convenience form of rt_bot_gc for unchanged source faces.  The caller owns
 * the returned BOT.
 *
 * Returns NULL for malformed input or an invalid face reference.
 */
RT_EXPORT extern struct rt_bot_internal *rt_bot_subset(
        const struct rt_bot_internal *bot, const int *face_indices,
        size_t face_count);
 
/**
 * Split a BOT into edge-connected triangle components.  A connected BOT
 * returns an allocated empty list.  On success with multiple components, each
 * list entry owns a compact BOT preserving all source face-indexed data.
 * Returns NULL on malformed input or another processing failure.
 */
RT_EXPORT extern struct rt_bot_list * rt_bot_split(struct rt_bot_internal *bot);
RT_EXPORT extern struct rt_bot_list * rt_bot_patches(struct rt_bot_internal *bot);
 
/** Free a BOT list.  If fbflag is non-zero, also free each contained BOT. */
RT_EXPORT extern void rt_bot_list_free(struct rt_bot_list *headRblp,
                                       int fbflag);
 
RT_EXPORT extern void rt_bot_internal_free(struct rt_bot_internal *bot);
 
RT_EXPORT extern int rt_bot_same_orientation(const int *a,
                                             const int *b);
 
RT_EXPORT extern int rt_bot_tess(struct nmgregion **r,
                                 struct model *m,
                                 struct rt_db_internal *ip,
                                 const struct bg_tess_tol *ttol,
                                 const struct bn_tol *tol);
 
RT_EXPORT extern struct rt_bot_internal * rt_bot_merge(size_t num_bots, const struct rt_bot_internal * const *bots);
 
 
/* defined in bot.c */
/* TODO - these global variables need to be rolled in to the rt_i structure */
RT_EXPORT extern int rt_bot_sort_faces(struct rt_bot_internal *bot,
                                       size_t tris_per_piece);
RT_EXPORT extern int rt_bot_decimate(struct rt_bot_internal *bot,
                                     fastf_t max_chord_error,
                                     fastf_t max_normal_error,
                                     fastf_t min_edge_length);
 
 
/* Decimate the input Bot using feature_size to determine the target scale of
 * geometric detail that is preserved in the output mesh.
 *
 * Geometrically, it represents the smallest meaningful feature or minimum
 * detail size that should be retained. During decimation, edges, vertices, and
 * triangles representing features smaller than feature_size are candidates for
 * removal or simplification, while larger features are preserved. Thus,
 * increasing feature_size produces a coarser mesh with fewer, larger
 * triangles, removing fine details; decreasing it retains more of the original
 * geometry and fine features. In essence, feature_size acts as a filter for
 * the geometric fidelity of the simplified mesh.
 *
 * feature_size is transformed internally into a collapse cost threshold, so
 * it does not directly specify the output triangle size.  As a safety
 * postcondition, every referenced output vertex is nevertheless required to
 * lie within feature_size of the original surface.  A candidate that violates
 * that limit is rejected and the input BOT is left unchanged.  The detailed
 * output topology remains an implementation detail, so calling codes may see
 * different meshes between library versions for the same feature_size.
 * Face provenance is retained through the operation so plate thickness, face
 * mode, normals, and texture UVs remain associated with their source faces.
 */
RT_EXPORT extern size_t rt_bot_decimate_gct(struct rt_bot_internal *bot, fastf_t feature_size);
 
/* Function to convert plate mode BoT to volumetric BoT */
RT_EXPORT extern int rt_bot_plate_to_vol(struct rt_bot_internal **obot, struct rt_bot_internal *bot, int round_outer_edges, int quiet_mode, fastf_t max_area_delta, fastf_t min_tri_threshold);
 
 
 
/* Container to hold various settings we may need to control the bot repair
 * process.  May also be updated in the future to contain diagnostic info
 * to report back to the caller - this struct is expected to change in
 * response to the evolving setting needs of the repair process as various
 * algorithms are explored.
 */
struct rt_bot_repair_info {
    fastf_t max_hole_area;
    fastf_t max_hole_area_percent;
    int strict;
 
    // Info about generated output
    int output_nonmanifold;
    int output_lint_fail;
    fastf_t output_volume;
    unsigned int output_data_loss;
};
 
#define RT_BOT_REPAIR_LOST_NORMALS 0x01
#define RT_BOT_REPAIR_LOST_UVS     0x02
 
/* For now the default upper hole size limit will be 5 percent of the mesh
 * area, but calling codes should not rely on that value to remain consistent
 * between versions.
 *
 * By default, don't return a mesh that can't pass the lint solid raytracing
 * tests.  This isn't always desirable - sometimes manifold is enough even if
 * the mesh is not otherwise well behaved - so it is an user settable param.
 */
#define RT_BOT_REPAIR_INFO_INIT {0.0, 5.0, 1, 0, 0, 0.0, 0};
 
/* Function to attempt repairing a non-manifold BoT.  Returns 1 if ibot was
 * already manifold (obot will contain NULL), 0 if a manifold BoT was created
 * (*obot will be the new manifold BoT) and -1 for other cases to indicate
 * error.  Only RT_BOT_SOLID inputs are accepted.  Merge-only repairs preserve
 * source normals and texture UVs.  Repairs that create or alter faces cannot
 * in general map that data to the result; output_data_loss reports which data
 * was cleared in those cases.
 */
RT_EXPORT extern int rt_bot_repair(struct rt_bot_internal **obot, struct rt_bot_internal *ibot, struct rt_bot_repair_info *i);
 
/* Test whether a bot is "inside-out".  This function is aware of
 * CCW vs CW BoT orientation settings, and will interpret the
 * results of the test accordingly.  The idea is for this function
 * to return "1" in the same situations that would result in an
 * OpenGL shaded drawing of the BoT showing black faces due to
 * incorrect orientation. */
RT_EXPORT extern int rt_bot_inside_out(struct rt_bot_internal *bot);
 
/* Test whether a solid BoT has faces that are <tol distance away when shooting
 * "into" the solid.  This is (at the moment) a ray interrogation based test,
 * so it is not absolutely guaranteed to find all near self-intersections.
 *
 * It is intended to catch situations such as boolean operations on meshes
 * producing exceedingly thin volumes.
 *
 * Returns 1 if a problem is found, else 0.  If ofaces is non-NULL, store the
 * indices of the specific faces found to be problematic. */
RT_EXPORT extern int rt_bot_thin_check(struct bu_ptbl *ofaces, struct rt_bot_internal *bot, struct rt_i *rtip, fastf_t tol, int verbose);
 
/* Test whether a solid BoT has faces that produce raytrace segments with
 * thickness in the range [VUNITIZE_TOL, BN_TOL_DIST).  Such segments are
 * returned by the BoT raytracer but would be discarded by the CSG boolweave
 * tolerance filter, indicating a potential divergence between the BoT and
 * the original CSG description (the CSG raytracer would report MISS while
 * the BoT solid reports HIT).
 *
 * The typical cause is a subtractor primitive that protrudes just a sub-
 * tolerance distance past a base face, creating a phantom thin cap in the
 * facetized mesh that is too thin to survive the CSG boolweave.
 *
 * Faces already flagged by rt_bot_thin_check (segment thickness < VUNITIZE_TOL,
 * i.e. true mesh degeneracies) are in a disjoint thickness range and are not
 * reported here.
 *
 * Returns 1 if a problem is found, else 0.  If ofaces is non-NULL, store the
 * indices of the specific faces found to be problematic. */
RT_EXPORT extern int rt_bot_csg_miss_check(struct bu_ptbl *ofaces, struct rt_bot_internal *bot, struct rt_i *rtip, int verbose);
 
/* Function to remove a set of faces from a BoT and produce a new BoT */
RT_EXPORT struct rt_bot_internal *
rt_bot_remove_faces(struct bu_ptbl *rm_face_indices, const struct rt_bot_internal *obot);
 
/* Function to copy an rt_bot_internal structure */
RT_EXPORT struct rt_bot_internal *
rt_bot_dup(const struct rt_bot_internal *bot);
 
/** @} */
 
__END_DECLS
 
#endif /* RT_PRIMITIVES_BOT_H */
 
/*
 * Local Variables:
 * tab-width: 8
 * mode: C
 * indent-tabs-mode: t
 * c-file-style: "stroustrup"
 * End:
 * ex: shiftwidth=4 tabstop=8
 */