LiDARHandler Class Reference

Collaboration diagram for LiDARHandler:

Classes
struct	PointFilter
struct	PointRow

Public Member Functions
	LiDARHandler ()
	Construct a new LiDARHandler::LiDARHandler object.
	LiDARHandler (const LiDARHandler &pOther)=delete
LiDARHandler &	operator= (const LiDARHandler &pOther)=delete
	~LiDARHandler ()
	Destroy the LiDARHandler::LiDARHandler object.
bool	OpenDB (const std::string &szDBPath)
	Initializes the LiDARHandler by opening the SQLite database and preparing the query.
bool	CloseDB ()
	Closes the currently open LiDAR database.
std::vector< PointRow >	GetLiDARData (const PointFilter &stPointFilter)
	Retrieves LiDAR data points from the database based on the specified filter.
bool	InsertLiDARData (const std::vector< geoops::Waypoint > &vPoints)
bool	IsDBOpen ()
	Checks if the database is currently open.

Private Member Functions
template<typename T >
void	AddRangeFilter (std::vector< std::string > &vClauses, std::vector< std::function< void(sqlite3_stmt *, int &)> > &vBinders, const char *pColumn, const std::optional< PointFilter::Range< T > > &stdOptRange)
	Adds a range filter to the SQL query clauses and binders.

Private Attributes
sqlite3 *	m_pSQLDatabase
sqlite3_stmt *	m_pSQLStatement
bool	m_bIsDBOpen
std::shared_mutex	m_muQueryMutex

Constructor & Destructor Documentation

LiDARHandler()

LiDARHandler::LiDARHandler

(

)

Construct a new LiDARHandler::LiDARHandler object.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-07-13

{
    // Initialize member variables.
    m_pSQLDatabase  = nullptr;
    m_pSQLStatement = nullptr;
    m_bIsDBOpen     = false;
}

~LiDARHandler()

LiDARHandler::~LiDARHandler

(

)

Destroy the LiDARHandler::LiDARHandler object.

Author

ClayJay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om), Eli Byrd (edbgk.nosp@m.k@ms.nosp@m.t.edu)

Date

2025-05-20

{
    this->CloseDB();    // Ensure the database is closed on destruction.
}

Here is the call graph for this function:

Member Function Documentation

OpenDB()

bool LiDARHandler::OpenDB

(

const std::string &

szDBPath

)

Initializes the LiDARHandler by opening the SQLite database and preparing the query.

This method opens the specified SQLite database file and prepares the internal SQL statement used to query nearby point records. It must be called before any queries are made using GetNearbyPoints().

Parameters

szDBPath

Relative or absolute path to the SQLite database file. If a relative path is provided, it must be relative to the directory from which the final executable is launched (i.e., the current working directory).

Returns

true - If the database was successfully opened and the SQL statement prepared.

false - If there was an error opening the database or preparing the SQL statement.

Note

If the database file cannot be found or accessed, an error message will be printed via Quill Logger and this function will return false.

Author

ClayJay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-07-13

{
    // Acquire a write lock on the mutex to ensure thread safety.
    std::unique_lock<std::shared_mutex> lkWriteLock(m_muQueryMutex);
 
    // Check if the database is already open.
    if (m_bIsDBOpen)
    {
        // Submit logger message.
        LOG_WARNING(logging::g_qSharedLogger, "Database is already open. Closing existing connection before opening a new one.");
        // Release lock before calling CloseDB to avoid deadlock.
        lkWriteLock.unlock();
        this->CloseDB();
        lkWriteLock.lock();
    }
 
    // Attempt to open the SQLite database.
    int nReturnCode = sqlite3_open(szDBPath.c_str(), &m_pSQLDatabase);
    if (nReturnCode != SQLITE_OK)
    {
        // Submit logger message.
        LOG_ERROR(logging::g_qSharedLogger, "Failed to open database at '{}': {}", szDBPath, sqlite3_errmsg(m_pSQLDatabase));
        // Return false on failure.
        return false;
    }
 
    // Set the database open flag to true.
    m_bIsDBOpen = true;
 
    // Log success.
    LOG_INFO(logging::g_qSharedLogger, "Successfully opened database at '{}'.", szDBPath);
 
    return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

CloseDB()

bool LiDARHandler::CloseDB

(

)

Closes the currently open LiDAR database.

Returns

true - If the database was successfully closed.

false - If there was an error closing the database.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-07-13

{
    // Acquire a write lock on the mutex to ensure thread safety.
    std::unique_lock<std::shared_mutex> lkWriteLock(m_muQueryMutex);
 
    // Handle the closing of the database and sqlite statement.
    if (m_bIsDBOpen)
    {
        // Finalize the prepared statement if it exists. This is necessary because
        // failing to do so can result in memory leaks. This just frees resources.
        if (m_pSQLStatement)
        {
            int nReturnCode = sqlite3_finalize(m_pSQLStatement);
            if (nReturnCode != SQLITE_OK)
            {
                // Submit logger message.
                LOG_ERROR(logging::g_qSharedLogger, "Failed to finalize SQL statement: {}", sqlite3_errmsg(m_pSQLDatabase));
                // Return false on failure.
                return false;
            }
            m_pSQLStatement = nullptr;    // Reset the statement pointer.
        }
 
        // Close the database connection.
        int nReturnCode = sqlite3_close(m_pSQLDatabase);
        if (nReturnCode != SQLITE_OK)
        {
            // Submit logger message.
            LOG_ERROR(logging::g_qSharedLogger, "Failed to close database: {}", sqlite3_errmsg(m_pSQLDatabase));
            // Return false on failure.
            return false;
        }
 
        // Reset the database pointer and update the open flag.
        m_pSQLDatabase = nullptr;    // Reset the database pointer.
        m_bIsDBOpen    = false;      // Update the database open flag.
    }
 
    return true;
}

Here is the caller graph for this function:

GetLiDARData()

std::vector< LiDARHandler::PointRow > LiDARHandler::GetLiDARData

(

const PointFilter &

stPointFilter

)

Retrieves LiDAR data points from the database based on the specified filter.

Parameters

stPointFilter

- The filter criteria to apply when querying LiDAR data.

Returns

std::vector<LiDARHandler::PointRow> - A vector of PointRow structures containing the queried LiDAR data points.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-07-13

{
    // Acquire a read lock on the mutex to ensure thread safety.
    std::shared_lock<std::shared_mutex> lkReadLock(m_muQueryMutex);
 
    // Record the start time for performance measurement.
    std::chrono::time_point<std::chrono::high_resolution_clock> tmStartTime = std::chrono::high_resolution_clock::now();
 
    if (!m_bIsDBOpen)
    {
        LOG_ERROR(logging::g_qSharedLogger, "Database is not open.");
        return {};
    }
 
    // Build dynamic WHERE clauses and binders.
    std::vector<std::string> vClauses;
    std::vector<std::function<void(sqlite3_stmt*, int&)>> vBinders;
    int nParamIndex = 1;
 
    // Spatial bounds are always present (using R-Tree index).
    vClauses.emplace_back("idx.min_x BETWEEN ? AND ?");
    vBinders.emplace_back(
        [&](sqlite3_stmt* sqlSTMT, int& nIndex)
        {
            sqlite3_bind_double(sqlSTMT, nIndex++, stPointFilter.dEasting - stPointFilter.dRadius);
            sqlite3_bind_double(sqlSTMT, nIndex++, stPointFilter.dEasting + stPointFilter.dRadius);
        });
    vClauses.emplace_back("idx.min_y BETWEEN ? AND ?");
    vBinders.emplace_back(
        [&](sqlite3_stmt* sqlSTMT, int& nIndex)
        {
            sqlite3_bind_double(sqlSTMT, nIndex++, stPointFilter.dNorthing - stPointFilter.dRadius);
            sqlite3_bind_double(sqlSTMT, nIndex++, stPointFilter.dNorthing + stPointFilter.dRadius);
        });
 
    // Optional classification filter.
    // OPTIMIZATION: We filter against the joined 'Classifications' table (c.label).
    if (stPointFilter.szClassification && !stPointFilter.szClassification->empty())
    {
        vClauses.emplace_back("c.label = ?");
        vBinders.emplace_back([&](sqlite3_stmt* sqlSTMT, int& nIndex)
                              { sqlite3_bind_text(sqlSTMT, nIndex++, stPointFilter.szClassification->c_str(), -1, SQLITE_STATIC); });
    }
 
    // Add optional filters for metrics.
    this->AddRangeFilter(vClauses, vBinders, "p.normal_x", stPointFilter.dNormalX);
    this->AddRangeFilter(vClauses, vBinders, "p.normal_y", stPointFilter.dNormalY);
    this->AddRangeFilter(vClauses, vBinders, "p.normal_z", stPointFilter.dNormalZ);
    this->AddRangeFilter(vClauses, vBinders, "p.slope", stPointFilter.dSlope);
    this->AddRangeFilter(vClauses, vBinders, "p.rough", stPointFilter.dRoughness);
    this->AddRangeFilter(vClauses, vBinders, "p.curvature", stPointFilter.dCurvature);
    this->AddRangeFilter(vClauses, vBinders, "p.trav_score", stPointFilter.dTraversalScore);
 
    // Construct final SQL query string.
    std::ostringstream stdOSS;
 
    // OPTIMIZATION:
    // 1. Select 'z.label' and 'c.label' to get human-readable text.
    // 2. LEFT JOIN to handle cases where IDs might not map (prevents data loss).
    stdOSS << "SELECT p.id, p.easting, p.northing, p.altitude, z.label, c.label,"
           << " p.normal_x, p.normal_y, p.normal_z, p.slope, p.rough, p.curvature, p.trav_score"
           << " FROM ProcessedLiDARPoints_idx AS idx"
           << " JOIN ProcessedLiDARPoints AS p ON p.id = idx.id"
           << " LEFT JOIN Zones AS z ON p.zone_id = z.id"
           << " LEFT JOIN Classifications AS c ON p.class_code = c.code"
           << " WHERE ";
 
    // Append all clauses to the SQL query.
    for (size_t siIter = 0; siIter < vClauses.size(); ++siIter)
    {
        if (siIter > 0)
            stdOSS << " AND ";
        stdOSS << vClauses[siIter];
    }
 
    // Final SQL query string.
    const std::string szSQLQuery = stdOSS.str();
 
    // Prepare SQL statement.
    sqlite3_stmt* sqlSTMT = nullptr;
    int nRC               = sqlite3_prepare_v2(m_pSQLDatabase, szSQLQuery.c_str(), -1, &sqlSTMT, nullptr);
    if (nRC != SQLITE_OK)
    {
        LOG_ERROR(logging::g_qSharedLogger, "Failed to prepare SQL: {}", sqlite3_errmsg(m_pSQLDatabase));
        return {};
    }
 
    // Bind parameters.
    for (std::function<void(sqlite3_stmt*, int&)>& binder : vBinders)
    {
        binder(sqlSTMT, nParamIndex);
    }
 
    // Execute and collect results.
    std::vector<PointRow> vResults;
    while ((nRC = sqlite3_step(sqlSTMT)) == SQLITE_ROW)
    {
        PointRow stRow;
        stRow.nID       = sqlite3_column_int(sqlSTMT, 0);
        stRow.dEasting  = sqlite3_column_double(sqlSTMT, 1);
        stRow.dNorthing = sqlite3_column_double(sqlSTMT, 2);
        stRow.dAltitude = sqlite3_column_double(sqlSTMT, 3);
 
        // --- SEGFAULT FIX START ---
        // Retrieve Zone (Column 4). Check for NULL (if LEFT JOIN failed).
        const char* pszZone = reinterpret_cast<const char*>(sqlite3_column_text(sqlSTMT, 4));
        stRow.szZone        = pszZone ? pszZone : "Unknown";
 
        // Retrieve Classification (Column 5). Check for NULL.
        const char* pszClass   = reinterpret_cast<const char*>(sqlite3_column_text(sqlSTMT, 5));
        stRow.szClassification = pszClass ? pszClass : "Unclassified";
        // --- SEGFAULT FIX END ---
 
        stRow.dNormalX        = sqlite3_column_double(sqlSTMT, 6);
        stRow.dNormalY        = sqlite3_column_double(sqlSTMT, 7);
        stRow.dNormalZ        = sqlite3_column_double(sqlSTMT, 8);
        stRow.dSlope          = sqlite3_column_double(sqlSTMT, 9);
        stRow.dRoughness      = sqlite3_column_double(sqlSTMT, 10);
        stRow.dCurvature      = sqlite3_column_double(sqlSTMT, 11);
        stRow.dTraversalScore = sqlite3_column_double(sqlSTMT, 12);
 
        vResults.push_back(stRow);
    }
 
    // Finalize SQL statement.
    if ((nRC = sqlite3_finalize(sqlSTMT)) != SQLITE_OK)
    {
        LOG_ERROR(logging::g_qSharedLogger, "Failed to finalize statement: {}", sqlite3_errmsg(m_pSQLDatabase));
        return {};
    }
 
    // Record the end time for performance measurement.
    std::chrono::time_point<std::chrono::high_resolution_clock> tmEndTime = std::chrono::high_resolution_clock::now();
    double dQueryTime                                                     = std::chrono::duration<double>(tmEndTime - tmStartTime).count();
 
    if (dQueryTime > 0.2)
    {
        LOG_WARNING(logging::g_qSharedLogger, "Query took {:.2f} seconds to execute.", dQueryTime);
    }
    else
    {
        LOG_DEBUG(logging::g_qSharedLogger, "Query took {} seconds to execute.", dQueryTime);
    }
 
    if (vResults.empty())
    {
        LOG_WARNING(logging::g_qSharedLogger, "Query returned no results.");
    }
 
    return vResults;
}

Here is the call graph for this function:

Here is the caller graph for this function:

IsDBOpen()

bool LiDARHandler::IsDBOpen

(

)

Checks if the database is currently open.

Returns

true - If the database is open.

false - If the database is not open.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-07-14

{
    // Acquire a read lock on the mutex to ensure thread safety.
    std::shared_lock<std::shared_mutex> lkReadLock(m_muQueryMutex);
    // Return the database open status.
    return m_bIsDBOpen;
}

Here is the caller graph for this function:

AddRangeFilter()

template<typename T >

void LiDARHandler::AddRangeFilter ( std::vector< std::string > &  vClauses, std::vector< std::function< void(sqlite3_stmt *, int &)> > &  vBinders, const char *  pColumn, const std::optional< PointFilter::Range< T > > &  stdOptRange  )

private

Adds a range filter to the SQL query clauses and binders.

Template Parameters

T	- The data type of the range values.

Parameters

vClauses	- The vector of SQL clauses to which the range filter will be added.
vBinders	- The vector of binders for the SQL statement.
pColumn	- The name of the column to apply the range filter on.
stdOptRange	- The optional range to filter by. If it is not set, no filter will be added.

Author

clayjay3 (clayt.nosp@m.onra.nosp@m.ycowe.nosp@m.n@gm.nosp@m.ail.c.nosp@m.om)

Date

2025-07-14

{
    // If the range is set, add the filter clause and binder.
    if (stdOptRange)
    {
        // Add the range filter clause based on the type of T.
        if constexpr (std::is_floating_point<T>::value)
        {
            // Only use >= by default for floats
            vClauses.emplace_back(std::string(pColumn) + " >= ?");
            vBinders.emplace_back([&](sqlite3_stmt* sqlSTMT, int& nIndex) { sqlite3_bind_double(sqlSTMT, nIndex++, stdOptRange->tMin); });
        }
        else
        {
            // Use BETWEEN for ints or guaranteed bounded ranges
            vClauses.emplace_back(std::string(pColumn) + " BETWEEN ? AND ?");
            vBinders.emplace_back(
                [&](sqlite3_stmt* sqlSTMT, int& nIndex)
                {
                    sqlite3_bind_double(sqlSTMT, nIndex++, stdOptRange->tMin);
                    sqlite3_bind_double(sqlSTMT, nIndex++, stdOptRange->tMax);
                });
        }
    }
}

Here is the caller graph for this function:

---

The documentation for this class was generated from the following files:

• src/handlers/LiDARHandler.h
• src/handlers/LiDARHandler.cpp