From c8a58f0636f56bc676084b3facbd8ea6bfe8caff Mon Sep 17 00:00:00 2001 From: CellarKid Date: Wed, 25 Feb 2026 22:11:17 +0100 Subject: [PATCH] docs: update READMEs --- README.md | 69 +++++++++++++-- sketchgetdp/bitmap_tracer/README.md | 74 +++++----------- sketchgetdp/svg_to_getdp/README.md | 126 ++++++++++++++-------------- 3 files changed, 145 insertions(+), 124 deletions(-) diff --git a/README.md b/README.md index 6f82083..b90c45c 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,70 @@ # SketchGetDP -Translates photographed hand-drawn shapes and/or SVG files to Gmsh geometries, ready to be used within a GetDP simulation. +**From Hand-Drawn Sketches to Electromagnetic Simulations** + +SketchGetDP translates photographed hand-drawn shapes and SVG files into Gmsh geometries ready for GetDP simulation. It's designed for engineers, researchers, and students working with accelerator magnet cross-sections. + +## 🎯 Overview + +SketchGetDP provides two complementary tools that turn your drawings into simulation results: + +- **Bitmap Tracer** – Converts photos of hand-drawn sketches (JPEG, PNG) into SVG vector graphics +- **SVG to GetDP** – Analyzes SVG sketches to create meshes and run electromagnetic simulations + +> ⚠️ **Note**: The Bitmap Tracer and SVG to GetDP components are still being integrated. Currently, corner detection for freehand lines and color mapping between the two tools require further development. + + +## πŸ“ Project Structure + +``` +SketchGetDP/ +β”œβ”€β”€ sketchgetdp/ # Core Implementation +β”‚ β”œβ”€β”€ bitmap_tracer/ # Converts Images to SVG +β”‚ β”œβ”€β”€ svg_to_getdp/ # Converts SVG to simulations +β”‚ └── rmvp_formulation.pro # GetDP configuration template +β”œβ”€β”€ tests/ # Example inputs for testing +β”œβ”€β”€ README.md # This documentation +β”œβ”€β”€ getdp_path.txt # Path to your GetDP installation +└── requirements.txt # Python package dependencies +``` + +For detailed information, check the README files in each subdirectory. ## Getting started -Install the SketchGetDP module by running the command -`pip install -e .` +1. **Install the SketchGetDP module** + ```bash + pip install -e . + ``` + +2) **Install the SketchGetDP module** + ```bash + pip install -r requirements.txt + ``` + +3) **Install GetDP** + - Download GetDP from [getdp.info](https://getdp.info/) + - Add the path to GetDP in `getdp_path.txt` + +## πŸ› οΈ Usage + +### Bitmap Tracer + +Convert a photo of a hand-drawn sketch to SVG by running the following from the sketchgetdp subdirectory: +```bash +python -m bitmap_tracer +``` + +### SVG to GetDP + +Three ways to use it from the sketchgetdp subdirectory: -in the SketchGetDP root directory. Use the command +```bash +# Mode 1: SVG to mesh only +python -m svg_to_getdp --config -`pip install -r requirements.txt` +# Mode 2: Full pipeline (SVG β†’ mesh β†’ simulation) +python -m svg_to_getdp --run-simulation --config -to install all further required packages to run SketchGetDP. +# Mode 3: Simulation only (existing mesh) +python -m svg_to_getdp --simulation-only --config +``` diff --git a/sketchgetdp/bitmap_tracer/README.md b/sketchgetdp/bitmap_tracer/README.md index aa74e08..ccf69c2 100644 --- a/sketchgetdp/bitmap_tracer/README.md +++ b/sketchgetdp/bitmap_tracer/README.md @@ -1,6 +1,6 @@ # Bitmap Tracer -A sophisticated image-to-SVG tracing application that converts bitmap images into clean, scalable vector graphics with intelligent color categorization and structure filtering. +A image-to-SVG tracing application that converts bitmap images into clean, scalable vector graphics with intelligent color categorization and structure filtering. ## 🎯 Overview @@ -12,27 +12,6 @@ Bitmap Tracer is a Python-based tool that analyzes bitmap images and converts th - **Point detection** for small, compact shapes - **Automatic contour closure** ensuring all paths form complete loops -## πŸ—οΈ Architecture - -The project follows Clean Architecture principles with clear separation of concerns: - -### Core Layers - -- **`core/`** - Enterprise business rules - - `entities/` - Domain models (Point, Contour, Color) - - `use_cases/` - Application logic (Image Tracing, Structure Filtering) - -- **`infrastructure/`** - Frameworks & drivers - - `image_processing/` - Contour detection, color analysis, closure services - - `svg_generation/` - SVG creation and shape processing - - `configuration/` - Config loading and management - - `point_detection/` - Point detection and curve fitting - -- **`interfaces/`** - Interface adapters - - `controllers/` - Application flow control - - `presenters/` - Output formatting (SVG presentation) - - `gateways/` - External interfaces (image loading, config access) - ## πŸš€ Key Features ### Color Categorization @@ -59,20 +38,23 @@ The project follows Clean Architecture principles with clear separation of conce ``` bitmap_tracer/ -β”œβ”€β”€ core/ # Business logic -β”‚ β”œβ”€β”€ entities/ # Domain models -β”‚ └── use_cases/ # Application services -β”œβ”€β”€ infrastructure/ # External concerns -β”‚ β”œβ”€β”€ image_processing/ # Computer vision -β”‚ β”œβ”€β”€ svg_generation/ # Vector output -β”‚ β”œβ”€β”€ configuration/ # Config management -β”‚ └── point_detection/ # Point analysis -β”œβ”€β”€ interfaces/ # Adapters -β”‚ β”œβ”€β”€ controllers/ # Flow control -β”‚ β”œβ”€β”€ presenters/ # Output formatting -β”‚ └── gateways/ # External interfaces -β”œβ”€β”€ __main__.py # Python module entry point -└── config.yaml # Configuration +β”œβ”€β”€ core/ # Core logic +β”‚ β”œβ”€β”€ entities/ # Point, Contour, Color models +β”‚ └── use_cases/ # Tracing and filtering workflows +β”œβ”€β”€ infrastructure/ # Technical Implementations +β”‚ β”œβ”€β”€ image_processing/ # OpenCV contour detection +β”‚ β”œβ”€β”€ svg_generation/ # Creates SVG output +β”‚ β”œβ”€β”€ configuration/ # Loads config.yaml +β”‚ └── point_detection/ # Identifies small shapes +β”œβ”€β”€ interfaces/ # Connects components +β”‚ β”œβ”€β”€ controllers/ # Orchestrates the workflow +β”‚ β”œβ”€β”€ presenters/ # Formats output +β”‚ └── gateways/ # Handles external input +β”œβ”€β”€ tests/ # Pytests +β”œβ”€β”€ __main__.py # Entry point +β”œβ”€β”€ config.yaml # Your settings +β”œβ”€β”€ pytest.ini # Pytest initialization +└── README.md # This documentation ``` ## βš™οΈ Configuration @@ -104,20 +86,11 @@ min_value_black: 50 # Minimum value below which colors are consid ## πŸ› οΈ Usage -The Bitmap Tracer can be run from the command line in two ways: - -### From the sketchgetdp directory as a python module: +From the sketchgetdp directory: ```bash python -m bitmap_tracer ``` -### From the bitmap_tracer directory: -```bash -python main.py -``` - -Where `` is the path to the bitmap image you want to convert to SVG. - The application will automatically: - Load configuration from `config.yaml` - Process the input image @@ -138,12 +111,3 @@ The tracer generates SVG files with: - NumPy - Numerical computations - svgwrite - SVG generation - PyYAML - Configuration parsing - -## 🎨 Use Cases - -- Converting hand-drawn sketches to vector graphics -- Processing technical diagrams and schematics -- Creating scalable versions of bitmap artwork -- Extracting structured information from images - -The Bitmap Tracer excels at transforming complex bitmap images into clean, manageable vector representations while preserving the essential structure and color information. \ No newline at end of file diff --git a/sketchgetdp/svg_to_getdp/README.md b/sketchgetdp/svg_to_getdp/README.md index 13a8aa2..d2738b7 100644 --- a/sketchgetdp/svg_to_getdp/README.md +++ b/sketchgetdp/svg_to_getdp/README.md @@ -4,7 +4,7 @@ A sophisticated electromagnetic simulation pipeline that converts SVG sketches i ## 🎯 Overview -SVG to GetDP is a Python-based electromagnetic simulation pipeline that processes SVG files containing electromagnetic structures and generates simulation results through a multi-stage workflow. It features: +SVG to GetDP is a Python-based electromagnetic simulation pipeline that processes non-freehand drawn SVG files containing electromagnetic structures and generates simulation results through a multi-stage workflow. It features: - **Three operation modes**: SVGβ†’Gmsh, SVGβ†’Gmshβ†’GetDP, or Gmshβ†’GetDP - **Configurable physical properties** via YAML configuration @@ -12,31 +12,6 @@ SVG to GetDP is a Python-based electromagnetic simulation pipeline that processe - **Fixed color mapping** for physical group identification - **Automatic wire grouping** and boundary curve meshing -## πŸ—οΈ Architecture - -The project follows Clean Architecture principles with clear separation of concerns: - -### Core Layers - -- **`core/`** - Enterprise business rules - - `entities/` - Domain models (Point, Color, BezierSegment, BoundaryCurve, PhysicalGroup) - - `use_cases/` - Application logic (SVG-to-Geometry conversion, Geometry-to-Gmsh conversion, GetDP simulation execution) - -- **`infrastructure/`** - Frameworks & drivers - - `factories/` - Factory classes for dependency creation - - `svg_processing/` - SVG parsing and path extraction - - `corner_detection/` - Corner detection for curve segmentation - - `bezier_fitting/` - BΓ©zier curve fitting - - `boundary_curve_grouper/` - Wire grouping logic - - `boundary_curve_mesher/` - Boundary curve meshing - - `wire_preprocessor/` - Wire preprocessing for meshing - -- **`interfaces/`** - Interface adapters - - `controllers/` - Application flow control - - `arg_parser/` - Command line argument parsing - - `abstractions/` - Interfaces for dependency inversion - - `debug/` - Internal visualization and debug output - ## πŸš€ Key Features ### Three Operation Modes @@ -59,32 +34,40 @@ The project follows Clean Architecture principles with clear separation of conce - Visualization of internal geometry - Debug output of intermediate processing steps via .txt files +## How It Works + +1. **Parse SVG** – Reads paths and identifies colors (Blue = wires, Green = iron, Red = boundaries) +2. **Detect corners** – Breaks paths at sharp angles for better curve fitting +3. **Fit BΓ©zier curves** – Creates smooth mathematical representations +4. **Preprocess wires and outlines** – Preprocesses wires and outlines for meshing with Gmsh +5. **Generate mesh** – Creates a Gmsh mesh with physical groups +6. **Run simulation** – Executes GetDP to solve the electromagnetic problem + ## πŸ“ Project Structure ``` svg_to_getdp/ -β”œβ”€β”€ core/ # Business logic -β”‚ β”œβ”€β”€ entities/ # Domain models -β”‚ └── use_cases/ # Application services -β”œβ”€β”€ infrastructure/ # External concerns -β”‚ β”œβ”€β”€ factories/ # Factory pattern implementations -β”‚ β”œβ”€β”€ svg_processing/ # SVG parsing -β”‚ β”œβ”€β”€ corner_detection/ # Corner detection -β”‚ β”œβ”€β”€ bezier_fitting/ # BΓ©zier fitting -β”‚ β”œβ”€β”€ boundary_curve_grouper.py # Wire grouping -β”‚ β”œβ”€β”€ boundary_curve_mesher.py # Boundary meshing -β”‚ └── wire_preprocessor # Wire preprocessing -β”œβ”€β”€ interfaces/ # Adapters -β”‚ β”œβ”€β”€ arg_parser.py # Command line interface -β”‚ β”œβ”€β”€ abstractions/ # Dependency interfaces -β”‚ β”œβ”€β”€ debug/ # Debug tools -β”‚ β”œβ”€β”€ mesher/ # Meshing tools -β”‚ └── solver/ # Solving tools -β”œβ”€β”€ tests/ # pytests -β”‚ β”œβ”€β”€ core/ # Core layer tests -β”‚ └── infrastructure/ # Infrastructure tests -β”œβ”€β”€ __main__.py # Package entry point -β”œβ”€β”€ config.yaml # Configuration file -└── rmvp_formulation.pro # GetDP configuration file +β”œβ”€β”€ core/ # Core logic +β”‚ β”œβ”€β”€ entities/ # Point, color, outline, etc. +β”‚ └── use_cases/ # Conversion workflows +β”œβ”€β”€ infrastructure/ # Technical Implementations +β”‚ β”œβ”€β”€ factories/ # Creates objects +β”‚ β”œβ”€β”€ svg_processing/ # Parses SVG files +β”‚ β”œβ”€β”€ corner_detection/ # Finds path corners +β”‚ β”œβ”€β”€ bezier_fitting/ # Fits curves to paths +β”‚ β”œβ”€β”€ outline_grouper.py # Groups outlines for preprocessing +β”‚ β”œβ”€β”€ outline_preprocessor.py # Preprocesses outlines for Gmsh +β”‚ β”œβ”€β”€ wire_preprocessor.py # Preprocesses wires for Gmsh +β”œβ”€β”€ interfaces/ # Connectors +β”‚ β”œβ”€β”€ arg_parser.py # Command-line interface +β”‚ β”œβ”€β”€ abstractions/ # Dependency interfaces +β”‚ β”œβ”€β”€ debug/ # Debugging tools +β”‚ β”œβ”€β”€ mesher/ # Gmsh integration +β”‚ └── solver/ # GetDP integration +β”œβ”€β”€ tests/ # pytests +β”œβ”€β”€ __main__.py # Entry point +β”œβ”€β”€ config.yaml # Your settings +β”œβ”€β”€ pytest.ini # Pytest initialization +└── README.md # This documentation ``` ## βš™οΈ Configuration @@ -122,7 +105,7 @@ physical_values: Convert an SVG file to a Gmsh mesh file: ```bash -python -m svg_to_getdp drawing.svg --config config.yaml +python -m svg_to_getdp --config ``` ### Mode 2: Full Pipeline (SVG to Simulation) @@ -130,7 +113,7 @@ python -m svg_to_getdp drawing.svg --config config.yaml Convert SVG file to mesh file and run GetDP simulation: ```bash -python -m svg_to_getdp drawing.svg --run-simulation --config config.yaml +python -m svg_to_getdp --run-simulation --config ``` ### Mode 3: Simulation Only (Existing Mesh) @@ -138,7 +121,7 @@ python -m svg_to_getdp drawing.svg --run-simulation --config config.yaml Run GetDP simulation on an existing mesh file: ```bash -python -m svg_to_getdp --simulation-only existing_mesh.msh --config config.yaml +python -m svg_to_getdp --simulation-only --config ``` ### Additional Options @@ -149,13 +132,13 @@ python -m svg_to_getdp --simulation-only existing_mesh.msh --config config.yaml ### Examples ```bash # Generate mesh with custom name and no GUI -python -m svg_to_getdp sketch.svg --mesh-name my_design --no-gui +python -m svg_to_getdp --mesh-name my_design --no-gui # Full pipeline with custom config -python -m svg_to_getdp circuit.svg --config custom_config.yaml --run-simulation +python -m svg_to_getdp --config custom_config.yaml --run-simulation # Get debug output -python -m svg_to_getdp layout.svg --debug +python -m svg_to_getdp --debug ``` ## πŸ“Š Output @@ -164,27 +147,46 @@ The pipeline generates the following outputs depending on the mode: ### Mode 1 (SVG β†’ Gmsh) +Inside the sketchgetdp directory inside SketchGetDP: + - **`.msh` file**: Gmsh mesh file with physical groups ### Mode 2 (SVG β†’ Gmsh β†’ GetDP) +Inside the sketchgetdp directory inside SketchGetDP: + - **`.msh` file**: Gmsh mesh file - **`.pro` file**: GetDP problem definition - **`results/` directory**: GetDP simulation results ### Mode 3 (Gmsh Mesh β†’ GetDP) +Inside the sketchgetdp directory inside SketchGetDP: + - **`.pro` file**: GetDP problem definition - **`results/` directory**: GetDP simulation results +### Debug Output + +Inside the debug subdirectory of the sketchgetdp directory inside SketchGetDP: + +- **`svg_parser_debug_[filename]_[timestamp].txt` file**: SVG Processing Debug output +- **`corner_detection_debug_[filename]_[timestamp].txt` file**: Corner Detection Debug output +- **`geometry_debug_[filename]_[timestamp].txt` file**: Internal Geometry Representation Debug output +- **`geometry_plot_[filename]_[timestamp].png` file**: Internal Geometry Representation Plot +- **`wire_preprocessor_debug_[filename]_[timestamp].txt` file**: Wire Preprocessing Debug output +- **`outline_grouping_debug_[filename]_[timestamp].txt` file**: Outline Grouping Debug output +- **`outline_preprocessing_debug_[filename]_[timestamp].txt` file**: Outline Preprocessing Debug output + + ## πŸ”§ Dependencies -- **NumPy** - Numerical computations -- **svgpathtools** - SVG parsing and path manipulation -- **PyYAML** - Configuration parsing -- **Gmsh** - Meshing engine (external dependency) -- **GetDP** - Finite element solver (external dependency) -- **matplotlib** - Visualization (optional) +- **NumPy** - Numerical calculations +- **svgpathtools** - SVG parsing +- **PyYAML** - Configuration +- **Gmsh** - Meshing engine (external) +- **GetDP** - Finite element solver (external) +- **matplotlib** - Visualization (optional, for debugging) ## 🎨 Use Cases @@ -192,5 +194,3 @@ The pipeline generates the following outputs depending on the mode: - **Educational Tool**: Visualize electromagnetic field distributions from simple drawings - **Design validation**: Quickly test electromagnetic structures before detailed CAD modeling - **Mesh generation**: Create quality meshes from vector graphics for various Finite Element Analysis applications - -The SVG to GetDP pipeline excels at transforming intuitive SVG sketches into detailed electromagnetic simulations, bridging the gap between conceptual design and numerical analysis while maintaining configurability and reproducability. \ No newline at end of file