How vincentxgao/civil-tools works
Overall Project Type and Purpose
• This is a Python toolkit targeted at structural engineers. Its purpose is to integrate multiple functions such as:
• Loading building models from YJK-generated .ydb database files (YDBLoader)
• Generating various structural drawings (DXFGenerator)
• Creating report documents such as seismic review reports and stair calculation sheets (ReportGenerator)
• Plotting data figures and images (FigureGenerator)
• Managing constants for CAD, concrete, and steel properties (Const)
• It is essentially a domain-specific library (rather than a full-stack or web application), modularized by functionality for building modeling, visualization, and documentation.
File Structure to Identify Main Components
• The primary top-level package is “CivilTools” with sub-packages:
• Const: Likely holds constant definitions and helper utilities used across the toolkit.
• YDBLoader: Includes submodules for “BuildingDefine” (further broken down into Beam, Column, Geometry, GlobalResult, Section, Slab, StairPart) plus the SQLiteConnector for interacting with SQLite databases.
• DXFGenerator: Contains modules for generating various DXF drawings (basic drawings, detailed drawings, drawing attributes, and layer management).
• ReportGenerator: Contains modules for producing different types of reports (e.g., SeismicReport, StairCalculationReport, and individual building blocks like DocParagraph, DocPicture, and DocTable).
• FigureGenerator: Contains modules for producing plots (both using basic PNG and Matplotlib plots), including specialized tools like StairCalculationSheetPNGPlotter.
• Additionally, there are clearly organized tests confirming intended functionality, as well as standard Python packaging files (setup.py, requirements.txt).
How to Represent the Architecture
a. Main Components:
• YDBLoader Module
• Contains submodules for Building Definitions (Beam, Column, Geometry, Section, Slab, StairPart) and uses SQLiteConnector.
• It serves as the entry module for reading input “.ydb” files.
• DXFGenerator Module
• Responsible for generating technical drawings in DXF format
• Contains multiple drawing-related modules (BasicDXF, DetailDXF, etc.).
• ReportGenerator Module
• Generates structural reports (seismic reviews, stair calculation reports) by using predefined templates and document components.
• FigureGenerator Module
• Handles production of image-based outputs – charts and plots (PNG) – based on engineering data.
• Const (Constants Module)
• Provides engineering constants and helper routines specific to CAD, concrete, and steel.
b. Relationships and Data Flow:
• YDBLoader reads the .ydb building files and creates model objects that encapsulate building definitions.
• Those model objects (data structures for beams, columns, geometry, etc.) are then used by:
• ReportGenerator to generate calculation reports
• There is an implicit dependency from DXFGenerator and ReportGenerator back to data obtained via YDBLoader.
• The “Const” module is likely used by all other modules to maintain standard parameters (e.g., CAD settings, material properties).
c. Architectural Patterns and Design Principles:
• Modular structure: Each core functionality is encapsulated in its own module, making it easier to extend or modify independently.
• Separation of concerns: Input loading (YDBLoader), data visualization (DXFGenerator and FigureGenerator), and report generation (ReportGenerator) are clearly separated.
• Reusability: Submodules like those in YDBLoader (e.g., building definitions) are divided into components, reflecting an object-oriented approach that could easily be unit-tested (as seen in the tests directory).
d. Relevant Technologies & Frameworks:
• Python is the primary language.
• Likely third-party libraries for drawing (DXF handling), document generation (e.g., python-docx for reports), and plotting (Matplotlib or similar).
• SQLite integration for data management from .ydb files (via the SQLiteConnector submodule).
• Within YDBLoader, optionally nest or list its submodules (BuildingDefine with Beam, Column, Geometry, etc.) and indicate the SQLiteConnector.
• The YDBLoader module outputs structured building data that is consumed by both ReportGenerator and DXFGenerator (and possibly FigureGenerator).
• The “Const” module is accessed by multiple design modules.
• Rectangles for major functional modules (e.g., YDBLoader, DXFGenerator).
• External dependencies (for example, third-party libraries used for plotting or document generation) as small nodes connected to the corresponding module.
• Keep clear labels and directional flows to elucidate how data moves from ingestion to final output document/drawing.