mGFD CloudGenerator 2.0 ☁️

Web platform for generating 2D unstructured point clouds for meshless mGFD workflows

From images to contours to classified point clouds — with visualization and neighbor analysis

🔗 Quick Links

📋 Table of Contents

Overview
Features
Installation & Setup
Quick Start
Usage Guide
Visualizations
API Documentation
Data Formats
Project Architecture
Mathematical Model
Dataset Structure
Performance Benchmarks
Contributing
Research Team
Industry Partners Supporting Innovation
Scientific References
Citation & License
Acknowledgments
Contact
FAQ

🌟 Overview

mGFD CloudGenerator 2.0 is a Flask-based web platform that converts images → contours → classified point clouds designed for meshless Generalized Finite Differences (mGFD) workflows. It provides interactive contour extraction, multi-region management (including interior holes), cloud generation with two distribution strategies, high-quality visualizations (PNG/SVG), and region-aware neighbor computation.

🌐 Try it now! Live demo: https://malla.umich.mx/CloudGenerator/

🔧 Key Capabilities

🎨 ContourCreator: Single-click region detection (Flood Fill), interactive refinement, brush editing, and optional GrabCut.
☁️ CloudGenerator: Regular (grid-like) and Natural (Poisson disk sampling) distributions, optional contour reduction, multi-region support.
👁️ CloudViewer: Upload a CSV (contours or clouds) and instantly generate PNG/SVG visualizations.
:users: NeighborsCalculator: Compute k-nearest neighbors constrained by region boundaries (cKDTree-based).
💾 Export & Reproducibility: Standardized CSV formats + verification on export for integrity.

🔬 Typical Applications

Field	Application	Use Case
Computational Fluid Dynamics 🌊	Irregular domains	Node generation for complex geometries
Structural Engineering 🏗️	Stress analysis	Point sets for meshless discretization
Heat Transfer 🔥	Interface problems	Multi-region clouds with internal boundaries
Environmental Modeling 🌿	Geography-driven domains	Contour-driven discretization from maps
Biomedical Engineering 🔬	Organ shapes	Point cloud generation from silhouettes

✨ Features

🎨 ContourCreator

One-click region detection based on cv2.floodFill (fast and interactive).
Adaptive tolerance using local texture statistics for robust segmentation.
Positive/negative seed refinement for add/subtract workflows.
Brush editing to manually correct masks and boundaries.
Export single or multi-region contours as normalized CSV coordinates.

☁️ CloudGenerator

Regular Distribution: uniform grid-style generation inside polygonal regions.
Natural Distribution: Poisson disk sampling for organic point spacing.
Contour reduction to simplify boundaries before generation (optional).
Multi-region support: main region + interior regions (holes) handled explicitly.
Node classification written to CSV (boundary, interior, and region-aware classes).

👁️ CloudViewer

CSV upload and automatic rendering to PNG and SVG.
Compatibility with the standardized CSV formats described below.

:users: NeighborsCalculator

Region-constrained neighbor search (no cross-region connections).
Efficient KD-tree implementation via scipy.spatial.cKDTree.

📦 Installation & Setup

💻 System Requirements

Component	Minimum	Recommended
Python	3.9+	3.10+
RAM	4 GB	8 GB+
CPU	2 cores	4+ cores
Storage	1 GB	5 GB+ (if generating large datasets)
OS	Windows/Linux/macOS	Linux (recommended for deployments)

📋 Dependencies

# Web framework
Flask==3.1.1
Werkzeug==3.1.3

# Computer vision / geometry
opencv-python-headless==4.12.0.88
shapely==2.1.1

# Scientific computing
numpy==2.2.6
scipy==1.15.2
matplotlib==3.10.0

Quick Installation

# Method 1: Direct installation
git clone https://github.com/gstinoco/mGFD_CloudGenerator.git
cd mGFD_CloudGenerator
pip install -r requirements.txt

# Method 2: Virtual environment (recommended)
python -m venv cloudgen_env
source cloudgen_env/bin/activate  # On Windows: cloudgen_env\Scripts\activate
pip install -r requirements.txt

✅ Installation Verification

python -c "import flask, cv2, numpy, scipy, shapely, matplotlib; print(':white_check_mark: Installation successful!')"
python app.py

Local server default:

http://127.0.0.1:5000/

🚀 Quick Start

Step	What to do
1) Run	`python app.py`
2) Open	Go to `http://127.0.0.1:5000/`
3) Workflow	ContourCreator → export contours CSV → CloudGenerator → export cloud CSV + PNG/SVG → optional NeighborsCalculator.

📖 Usage Guide

Practical workflows for ContourCreator, CloudGenerator, CloudViewer, and NeighborsCalculator

🎨 ContourCreator (Image → Contours)

Step	What to do
1) Upload	Upload an image (PNG/JPG/JPEG/GIF/BMP). Max request size is 16 MB.
2) Detect	Click inside a region to extract it with Flood Fill (adaptive tolerance).
3) Refine	Use positive/negative seeds and brush tools to add/remove pixels from the mask.
4) Export	Export a single region or all regions to CSV with normalized coordinates.

☁️ CloudGenerator (Contours CSV → Classified Cloud)

Step	What to do
1) Upload CSV	Upload a contour CSV (`x,y,region` recommended for multi-region).
2) Choose method	Regular (grid-like) or Natural (Poisson disk sampling).
3) Options	Enable contour reduction and/or generate points inside interior regions (holes).
4) Outputs	CSV: `x,y,region,classification` Images: `.png` and `.svg` visualizations

👁️ CloudViewer (CSV → Visualization)

Step	What to do
1) Upload CSV	Upload a contour or cloud CSV.
2) Inspect	Get PNG/SVG renderings and point counts for fast validation.

:users: NeighborsCalculator (Cloud CSV → Neighbors)

Step	What to do
1) Upload Cloud CSV	Upload a cloud CSV containing `x,y,region,classification`.
2) Set k	Select the number of neighbors (`nvec`, default is 9).
3) Compute	Neighbors are computed within each region only (no cross-region links).

🎥 Visualizations

🖼️ Examples Gallery

The repository includes sample inputs and outputs under static/examples/.

Balkhash
_{Input image}

_{Cloud preview}

Balkhash_contours.csv · Balkhash_cloud.csv Caspio
_{Input image}

_{Cloud preview}

Caspio_contours.csv · Caspio_cloud.csv Titicaca
_{Input image}

_{Cloud preview}

Titicaca_contours.csv · Titicaca_cloud.csv

Tip: Use these CSV files in CloudViewer/CloudGenerator to reproduce the example outputs.

⚙️ API Documentation

The application exposes REST endpoints used by the web UI. All endpoints return JSON (except file downloads).

Endpoint	Method	Purpose
`/upload`	POST	Upload an image for ContourCreator
`/detect_region`	POST	One-click region detection (Flood Fill)
`/interactive_segmentation`	POST	Multi-seed segmentation (add/subtract)
`/grabcut_segmentation`	POST	Optional GrabCut segmentation
`/refine_with_brush`	POST	Apply brush strokes to refine the mask
`/export_single_region`	POST	Export one region to CSV (`x,y,region`)
`/save_all_coordinates`	POST	Export multiple regions to a single CSV (`x,y,region`)
`/upload_csv`	POST	Upload contour CSV for CloudGenerator
`/generate_cloud`	POST	Generate cloud (Regular distribution)
`/generate_cloud_natural`	POST	Generate cloud (Natural distribution)
`/upload_viewer`	POST	Upload CSV for rendering in CloudViewer
`/upload_neighbors`	POST	Upload cloud CSV and compute neighbors
`/download/<filename>`	GET	Download generated files from the output folder

🗄️ Data Formats

🚩 Contours CSV (exported by ContourCreator)

Minimal format (single region):

x,y
0.1234,0.5678
0.1240,0.5681
...

Recommended format (multi-region / holes):

x,y,region
0.1234,0.5678,1
0.1240,0.5681,1
...

All coordinates are normalized to the [0,1] × [0,1] range (with Y-axis inversion from image coordinates to Cartesian coordinates).

☁️ Cloud CSV (exported by CloudGenerator)

x,y,region,classification
0.1234,0.5678,1,boundary
0.2222,0.3333,1,interior
...

📂 Project Architecture

:package: mGFD_CloudGenerator/
├── app.py                                  # Flask app + API routes
├── requirements.txt                        # Python dependencies
├── vercel.json                             # Vercel deployment config (writes to /tmp)
│
├── contour_modules/                        # ContourCreator (segmentation + contour extraction)
│   └── detection.py
│
├── cloud_modules/                          # Cloud generation pipeline (Regular / Natural)
│   ├── generator.py                        # Orchestrates the full cloud workflow
│   ├── point_generation.py                 # Sampling algorithms (grid / Poisson disk)
│   ├── classification.py                   # Boundary vs interior labeling
│   ├── data_processing.py                  # CSV loaders / validation
│   ├── reduction.py                        # Contour reduction (optional)
│   ├── export.py                           # CSV export utilities
│   ├── visualization.py                    # PNG/SVG rendering
│   └── utils.py
│
├── analysis_modules/                       # Post-processing tools
│   └── neighbors.py                        # Region-constrained kNN neighbor computation
│
├── templates/                              # Web UI (Jinja2)
├── static/                                 # Frontend assets + examples gallery
│   ├── css/
│   ├── js/
│   ├── images/
│   └── examples/
│
├── logs/                                   # local rotating logs (not used on Vercel)
│
└── docs/                                   # Project branding + team images
    ├── logo/
    └── team/

Runtime directories created automatically on startup (local mode):

uploads/ (temporary uploads)
output/ (generated CSV/PNG/SVG)

📚 Mathematical Model

mGFD CloudGenerator is a preprocessing tool, but several steps are driven by simple, explicit mathematical mappings and geometric algorithms.

📐 Coordinate System & Normalization

ContourCreator works in normalized coordinates and exports points to the Cartesian-like convention used by mGFD workflows.

Concept	UI / Image Space	Exported Space
Range	$[0,1] \times [0,1]$ (normalized canvas)	$[0,1] \times [0,1]$
Origin	top-left	bottom-left
Y axis	downwards	upwards (inverted)

The export transformation applied to each point is:

$$x' = \mathrm{clip}(x \cdot s_x, 0, 1), \quad y' = \mathrm{clip}((1 - y) \cdot s_y, 0, 1)$$

Where $(s_x, s_y)$ are scaling factors derived from the source image size:

Scaling method	$s_x$	$s_y$	Notes
preserve_aspect_ratio (default)	$w/\max(w,h)$	$h/\max(w,h)$	Preserves aspect ratio in a unit square
stretch	$1$	$1$	Stretches to fill the unit square
custom	user-defined	user-defined	Direct overrides

☁️ Point-Cloud Generation (Regular vs Natural)

Given a set of polygonal contours (optionally multiple regions), CloudGenerator produces boundary and interior nodes:

Method	Strategy	Typical use
Regular Distribution	grid-like sampling inside the polygon	structured clouds, fast generation
Natural Distribution	Poisson disk sampling (minimum-distance constraint)	more organic spacing, avoids grid artifacts

Nodes are exported with metadata:

region: integer region ID (Region 1 is the outer domain; Regions 2+ are interior holes when enabled).
classification: boundary or interior (used by downstream mGFD pipelines).

🧭 Neighbor Model (Region-Constrained kNN)

Neighbor computation is performed per region using a KD-tree search. This prevents cross-region connectivity that would be invalid for disconnected domains or holes.

🗄️ Dataset Structure

This repository is organized as a web application plus reusable Python modules. When running locally, files are generated in a small set of runtime folders:

uploads/                               # temporary uploaded images/CSVs
output/                                # generated CSV/PNG/SVG artifacts
logs/                                  # local rotating logs (if not in Vercel)
static/examples/                       # versioned example inputs/outputs

📦 Output Artifacts

Typical filenames (written under output/):

Contour exports: <region_name>_<timestamp>.csv
Multi-region exports: <base>_all_regions_<timestamp>.csv
Regular clouds: <input>_cloud_<timestamp>.csv + PNG/SVG visualizations
Natural clouds: <input>_cloud_natural_<timestamp>.csv + PNG/SVG visualizations

⏳ Automatic Cleanup

The server periodically removes old files from uploads/ and output/ to avoid disk growth in long-running deployments.

📈 Performance Benchmarks

The application is designed for interactive workloads and scales well for typical mGFD preprocessing sizes. Exact runtimes depend on hardware, point counts, and geometry complexity.

⏱️ Scaling Overview

Stage	Core operation	Typical scaling
Segmentation	Flood Fill / interactive refinement	~ proportional to affected pixels
Cloud generation (Regular)	grid sampling + polygon checks	~ proportional to generated points
Cloud generation (Natural)	Poisson disk sampling	~ proportional to generated points (higher constant)
Neighbors	KD-tree kNN per region	~ $O(n \log n)$ per region
Visualization/Export	CSV + PNG/SVG	~ proportional to points

🤝 Contributing

🌟 Contribute to the Project

Bug reports, feature requests, and pull requests are welcome

🐛 Bug Reports

Search existing issues: Check if the bug has already been reported
Create a detailed report: Include steps to reproduce and expected vs actual behavior
Provide context: Operating system, Python version, browser, and relevant parameters (image size, regions, method)

💡 Feature Requests

Describe the feature: Clear and concise description of the proposed functionality
Justify the need: Explain how it benefits research, reproducibility, or usability
Provide examples: Use cases, expected inputs/outputs, and acceptance criteria

💻 Code Contributions

git clone https://github.com/gstinoco/mGFD_CloudGenerator.git
cd mGFD_CloudGenerator

python -m venv dev_env
source dev_env/bin/activate  # On Windows: dev_env\Scripts\activate
pip install -r requirements.txt

git checkout -b feature/your-feature-name

🧑‍🔬 Research Team

🌟 Meet the Team

Researchers and graduate students advancing meshless computational methods

👥 Main Researchers

Photo	Researcher	Affiliation	Contact
	Dr. Gerardo Tinoco Guerrero 🇲🇽 _{Numerical Methods & Computational Mathematics}
	Dr. Francisco Javier Domínguez Mota 🇲🇽 _{Applied Mathematics & Finite Difference Methods}
	Dr. José Alberto Guzmán Torres 🇲🇽 _{Engineering Applications & Artificial Intelligence}
	Dr. Heriberto Árias Rojas 🇲🇽 _{Engineering Applications}

🎓 Ph.D. Research Students

Photo	Student	Institution	Contact
	Gabriela Pedraza-Jiménez
	Eli Chagolla-Inzunza

🎓 M.Sc. Research Students

Photo	Student	Institution	Contact
	Jorge L. González-Figueroa
	Christopher N. Magaña-Barocio

🎓 Undergraduate Research Students

Photo	Student	Institution	Contact
	Maria Goretti Fraga-Lopez

🏭 Industry Partners Supporting Innovation

🌟 Industry Partners Supporting Innovation

Collaboration between academia and industry to accelerate real-world impact

🏭 SIIIA MATH

Soluciones de Ingeniería, México

🎯 Focus areas:

Mathematical modeling & simulation
AI/ML engineering solutions
Technology transfer and applied R&D

📚 Scientific References

📚 Core Publications (GFD / mGFD Background)

Tinoco-Guerrero, G., Domínguez-Mota, F. J., Guzmán-Torres, J. A., & Tinoco-Ruiz, J. G. (2022). "Numerical Solution of Diffusion Equation using a Method of Lines and Generalized Finite Differences." Revista Internacional de Métodos Numéricos para Cálculo y Diseño en Ingeniería, 38(2). DOI: 10.23967/j.rimni.2022.06.003

🏆 Project Highlights

Contour-to-cloud pipeline: interactive image-based contour extraction and multi-region management
Cloud generation methods: Regular (grid-like) and Natural (Poisson disk sampling) distributions
Region-aware analysis: neighbor computation constrained by region labels for disconnected domains and holes

📝 Citation & License

If you use this software in your research, please cite:

@software{tinoco2025mGFD_cloudgenerator,
  title={mGFD CloudGenerator 2.0: Web platform for generating 2D unstructured point clouds},
  author={Tinoco-Guerrero, Gerardo and 
          Domínguez-Mota, Francisco Javier and 
          Guzmán-Torres, José Alberto and
          Arias-Rojas, Heriberto},
  year={2025},
  institution={Universidad Michoacana de San Nicolás de Hidalgo},
  organization={SIIIA MATH: Soluciones en ingeniería},
  url={https://github.com/gstinoco/mGFD_CloudGenerator},
  version={2.0},
  note={Web-based preprocessing tool for meshless mGFD workflows: image-to-contour extraction, multi-region handling, point-cloud generation (regular/Poisson), node classification, and region-constrained neighbor analysis}
}

📄 License

This project is licensed under the MIT License - see the full license text below:

MIT License

Copyright (c) 2025 Gerardo Tinoco-Guerrero, Francisco Javier Domínguez-Mota, 
                   José Alberto Guzmán-Torres, Heriberto Árias Rojas

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Academic Use: This software is developed for research and educational purposes. Commercial use is permitted under the MIT License terms.

🙏 Acknowledgments

❤️ Special Thanks

We extend our gratitude to the institutions and partners supporting this research and open-source development

🏛️ Institutional Support

🎓 Universidad Michoacana de San Nicolás de Hidalgo (UMSNH) _{Academic institution, Mexico} Key support Academic foundation and research infrastructure Scientific training and supervision environment	🏛️ Secretariat of Science, Humanities, Technology and Innovation(SECIHTI) _{State Secretariat, Mexico} Key support Support for science and technology initiatives Funding and innovation promotion
🌿 Centre Internacional de Mètodes Numèrics en Enginyeria (CIMNE) _{Industry, Spain} Key support International collaboration in numerical methods Computational engineering research environment	🏭 SIIIA MATH: Soluciones en Ingeniería _{Industry, México} Key support Industry-driven applied research and development Technology transfer and practical engineering impact

:building_with_garden: Research Centers & Collaborations

🌿 Aula CIMNE-Morelia
_{Research collaboration space}

Collaboration highlights

Numerical methods and computational engineering environment
Academic–industry collaboration and training activities

🎓 UMSNH
_{Academic collaboration}

Collaboration highlights

Institutional infrastructure supporting research and training
Graduate formation and supervision for scientific computing

💻 Technology Communities

📦 Framework	👥 Community	⭐ Contribution
	OpenCV Community	Computer vision and image processing
	Flask Development Team	Web framework
	NumPy Community	Array computing foundation
	SciPy Community	Numerical algorithms
	Matplotlib Community	Scientific visualization
	Shapely Development Team	Computational geometry

📧 Contact & Support

Contact channels, technical support, and collaboration opportunities

Primary Contact
_{Research group coordination}

Dr. Gerardo Tinoco Guerrero
_{Morelia, Michoacán, México}

Technical Support
_{Bug reports, questions, and collaboration requests}

Issues for bugs and feature requests
Email for technical inquiries
Collaboration for partnerships and joint projects

Collaboration Opportunities
_{Research and engineering partnerships}

🧮 Meshless Methods _{mGFD discretizations, boundary handling, point cloud quality}	📐 Computational Geometry _{polygon processing, hole handling, robust point-in-region tests}
🖼️ Computer Vision _{segmentation workflows, contour extraction from images}	🌐 Scientific Web Tools _{reproducible preprocessing platforms for simulation pipelines}
🌊 CFD / Engineering _{node generation for complex domains and multi-region problems}

Student Opportunities
_{Projects and training in scientific computing}

Graduate Programs: research opportunities with the team
Undergraduate Projects: thesis topics in computational engineering
Internships: scientific computing, numerical methods, and applied modeling

Institutional Affiliations

💬 FAQ

Which image formats are supported?

PNG, JPG/JPEG, GIF, and BMP. Maximum request size is 16 MB.

Where are outputs saved when running locally?

Generated files are written to output/. Uploaded files are stored in uploads/. Both folders are created automatically on startup.

What is the expected CSV format for CloudGenerator?

Contours: x,y,region (region is optional, but recommended for multi-region). Clouds: x,y,region,classification.

Can I use this in commercial projects?

Yes. The project is released under the MIT License.

How should I cite this work?

Use the BibTeX entry in the Citation section and the referenced DOI in Scientific References.

Advancing meshless methods through open-source collaboration

If this project helps your research, please consider giving it a star.

Name		Name	Last commit message	Last commit date
Latest commit History 112 Commits
analysis_modules		analysis_modules
cloud_modules		cloud_modules
contour_modules		contour_modules
docs		docs
logs		logs
static		static
templates		templates
.gitignore		.gitignore
.vercelignore		.vercelignore
LICENSE		LICENSE
README.md		README.md
app.py		app.py
requirements.txt		requirements.txt
vercel.json		vercel.json

Folders and files

Latest commit

History

Repository files navigation

mGFD CloudGenerator 2.0 ☁️

🔗 Quick Links

📋 Table of Contents

🌟 Overview

🔧 Key Capabilities

🔬 Typical Applications

✨ Features

🎨 ContourCreator

☁️ CloudGenerator

👁️ CloudViewer

:users: NeighborsCalculator

📦 Installation & Setup

💻 System Requirements

📋 Dependencies

Quick Installation

✅ Installation Verification

🚀 Quick Start

📖 Usage Guide

🎨 ContourCreator (Image → Contours)

☁️ CloudGenerator (Contours CSV → Classified Cloud)

👁️ CloudViewer (CSV → Visualization)

:users: NeighborsCalculator (Cloud CSV → Neighbors)

🎥 Visualizations

🖼️ Examples Gallery

⚙️ API Documentation

🗄️ Data Formats

🚩 Contours CSV (exported by ContourCreator)

☁️ Cloud CSV (exported by CloudGenerator)

📂 Project Architecture

📚 Mathematical Model

📐 Coordinate System & Normalization

☁️ Point-Cloud Generation (Regular vs Natural)

🧭 Neighbor Model (Region-Constrained kNN)

🗄️ Dataset Structure

📦 Output Artifacts

⏳ Automatic Cleanup

📈 Performance Benchmarks

⏱️ Scaling Overview

🤝 Contributing

🌟 Contribute to the Project

🐛 Bug Reports

💡 Feature Requests

💻 Code Contributions

🧑‍🔬 Research Team

🌟 Meet the Team

👥 Main Researchers

🎓 Ph.D. Research Students

🎓 M.Sc. Research Students

🎓 Undergraduate Research Students

🏭 Industry Partners Supporting Innovation

🌟 Industry Partners Supporting Innovation

🏭 SIIIA MATH

Soluciones de Ingeniería, México

📚 Scientific References

📚 Core Publications (GFD / mGFD Background)

🏆 Project Highlights

📝 Citation & License

📄 License

🙏 Acknowledgments

❤️ Special Thanks

🏛️ Institutional Support

:building_with_garden: Research Centers & Collaborations

💻 Technology Communities

📧 Contact & Support

💬 FAQ

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Packages