🌐 English|한국어

Frequently Asked Questions (FAQ)

Modan2 is a user-friendly desktop application for geometric morphometrics research. It enables researchers to analyze shape variations in 2D and 3D data through landmark-based methods and statistical analysis.

Key features:

Hierarchical dataset management with parent-child relationships
2D image and 3D model landmark digitization
Statistical analysis (PCA, CVA, MANOVA)
Multiple file format support (TPS, NTS, Morphologika, OBJ, PLY, STL)
Comprehensive visualization tools
Built-in Procrustes superimposition

Who is Modan2 for?

Modan2 is designed for:

Researchers in biology, paleontology, anthropology
Graduate students learning geometric morphometrics
Morphologists analyzing shape variation
Evolutionary biologists studying form and function
Anyone working with landmark-based shape analysis

What makes Modan2 different from other morphometrics software?

Traditional morphometrics software challenges:

Complex commercial software with steep learning curve
Expensive licenses
Limited 2D/3D integration
Difficult data management

Modan2 advantages:

Free and open source (MIT license)
Intuitive interface designed for researchers
Integrated 2D/3D workflow in one application
Hierarchical dataset organization
Built-in database for persistent storage
Active development and community support

What file formats does Modan2 support?

Input Formats:

Landmark data: TPS, NTS, X1Y1, Morphologika
3D models: OBJ, PLY, STL
Images: JPG, PNG, BMP, TIF (for 2D landmark digitization)
Import/Export: JSON+ZIP packages (complete dataset backup)

Output Formats:

Same as input for landmark data
Excel/CSV for analysis results
JSON+ZIP for complete dataset sharing

Installation and Setup 

What are the system requirements?

Minimum Requirements:

OS: Windows 10+, macOS 10.14+, or Ubuntu 18.04+
CPU: Dual-core processor (2.0 GHz+)
RAM: 4GB minimum
Disk: 500MB for application + space for datasets
Display: 1280×720 resolution
Graphics: OpenGL 3.3+ compatible GPU

Recommended Requirements:

CPU: Quad-core processor (3.0 GHz+)
RAM: 8GB or more
Disk: 2GB for datasets
Display: 1920×1080 or higher
Graphics: Dedicated GPU for 3D visualization

How do I install Modan2?

Binary Installation (Easiest):

Download from https://github.com/jikhanjung/Modan2/releases
Windows: Run installer Modan2-Setup.exe
macOS: Open DMG and drag to Applications
Linux: Use AppImage or install from source

From Source (For Developers):

git clone https://github.com/jikhanjung/Modan2.git
cd Modan2
pip install -r requirements.txt
python Modan2.py

See the Installation Guide for detailed instructions.

Where is my data stored?

Database Location:

Windows: %APPDATA%\Modan2\modan.db
Linux/macOS: ~/.local/share/Modan2/modan.db

Settings File:

Windows: %APPDATA%\Modan2\settings.json
Linux/macOS: ~/.config/Modan2/settings.json

Log Files:

Windows: %APPDATA%\Modan2\logs\
Linux/macOS: ~/.local/share/Modan2/logs/

Note: Original image and 3D model files remain in their original locations. Only landmark data is stored in the database.

Can I backup my data?

Yes! Multiple backup options:

Copy database file
- Locate modan.db (see above)
- Copy to backup location
- Restore by replacing database file
Export datasets
- Export as JSON+ZIP package (includes all data and files)
- Export as TPS, Morphologika, or other formats
Manual backup
- Keep original image/model files
- Export landmark data regularly
- Export analysis results

Data Management 

What is a dataset in Modan2?

A dataset is a collection of objects (specimens) with shared:

Number of landmarks
Dimension (2D or 3D)
Variable definitions (measurements, categories)
Wireframe/baseline/polygon definitions
Analysis settings

Datasets can have parent-child relationships for hierarchical organization.

How do parent-child datasets work?

Parent dataset:

Contains original landmark data
Defines basic structure (landmark count, dimension)

Child dataset:

Inherits from parent
Can apply different Procrustes superimposition
Can have different object subsets
Can have additional variables
Shares landmark definitions with parent

Use cases:

Compare different superimposition methods
Analyze subgroups from same original data
Test different analytical approaches

What is the difference between objects and datasets?

Dataset:

Container for multiple objects
Defines structure (landmark count, dimension, variables)
Settings for visualization and analysis

Object:

Individual specimen
Contains landmark coordinates
Can have attached image or 3D model
Has variable values (measurements, categories)

Relationship: Dataset contains multiple objects

How many landmarks can I use?

Practical limits:

2D: Up to 1000 landmarks per object (tested)
3D: Up to 1000 landmarks per object (tested)
Objects: Tested with 2,000 objects successfully

Performance:

100 landmarks, 1000 objects: Excellent performance
Memory usage scales linearly (~4KB per object)
Analysis time depends on landmark count and algorithm

Can I have missing landmarks?

Yes! Modan2 supports missing landmarks:

Mark landmarks as “missing” in object dialog
Missing landmarks excluded from analyses
Visualization shows missing landmarks differently
Can estimate missing landmarks from existing data

Estimation methods:

Thin-plate spline (TPS) interpolation
Mean configuration estimation
Manual estimation

Landmark Digitization 

How do I digitize landmarks on 2D images?

Steps:

Create dataset → Set dimension to 2D
Create object → Attach image
Open object dialog
Click on image to place landmarks
Landmarks numbered sequentially
Right-click to delete last landmark
Save when complete

Tips:

Zoom in for precision (mouse wheel)
Pan by dragging with middle button
Use wireframe to verify landmark placement
Mark missing landmarks if needed

How do I digitize landmarks on 3D models?

Steps:

Create dataset → Set dimension to 3D
Create object → Attach 3D model
Open object dialog
Rotate model to view landmark location
Click to place landmark
Landmark appears as sphere
Continue for all landmarks
Save when complete

3D Controls:

Left-drag: Rotate
Middle-drag: Pan
Scroll: Zoom
Double-click: Reset view
Right-click: Context menu

Can I edit existing landmarks?

Yes! Multiple editing options:

Visual editing:
- Open object dialog
- Click and drag landmarks
- Updates in real-time
Table editing:
- Edit X, Y, Z coordinates directly in table
- Precision editing for fine adjustments
Batch editing:
- Select multiple objects
- Apply transformations
- Update landmarks programmatically

Statistical Analysis 

What analyses does Modan2 support?

Multivariate Analysis:

PCA (Principal Component Analysis): Explore main patterns of variation
CVA (Canonical Variate Analysis): Analyze group differences
MANOVA (Multivariate Analysis of Variance): Test group differences

Procrustes Methods:

Full Procrustes: Translation, rotation, scaling
Partial Procrustes: Translation, rotation only
Bookstein registration: Align using baseline
Resistant Fit: Robust to outliers

Shape Analysis:

Mean shape calculation
Shape differences visualization
Regression analysis
Size and shape components

How do I run a PCA analysis?

Steps:

Select dataset in tree view
Click Analysis → New Analysis
Analysis Type: PCA
Optional: Select grouping variable for coloring
Click OK
Results appear in new tab

PCA Results Include:

Scree plot (variance explained)
Score plots (PC1 vs PC2, etc.)
Loadings visualization
Shape variation along PCs
Export options

What is Procrustes superimposition?

Procrustes superimposition removes non-shape variation:

Translation: Centers configurations
Rotation: Aligns to minimize distance
Scaling: Standardizes size (optional)

Purpose: Compare shape independent of:

Position (translation)
Orientation (rotation)
Size (scaling, if full Procrustes)

Result: Procrustes coordinates represent pure shape

How many objects do I need for analysis?

Minimum requirements:

PCA: At least 3 objects (more recommended)
CVA: At least 2 groups with 3+ objects each
MANOVA: At least 2 groups with 3+ objects each

Recommended sample sizes:

Exploratory PCA: 20-30 objects minimum
Group comparison (CVA): 10-15 per group minimum
Publication quality: 30+ per group recommended

General rule: More is better for robust results

File Import and Export 

How do I import landmark data?

Steps:

File → Import → [Format]
Select file (TPS, NTS, Morphologika, etc.)
Choose or create target dataset
Map variables if needed
Click Import

Supported formats:

TPS (most common)
NTS
X1Y1
Morphologika
JSON+ZIP (complete backup)

Can I import from other software?

Yes! Modan2 supports standard formats:

From MorphoJ: Export as TPS or Morphologika
From tpsUtil/tpsDig: Use TPS files directly
From Landmark Editor: Export as NTS
From R packages: Save as TPS or Morphologika

Format compatibility:

TPS: Most compatible format
Morphologika: Good for complex datasets
NTS: Simple format

How do I export my data?

Export options:

Dataset export:
- File → Export → Dataset
- Choose format (TPS, Morphologika, JSON+ZIP)
- Select objects to export
Analysis results:
- Right-click analysis → Export
- Save as Excel or CSV
- Includes scores, loadings, statistics
Complete backup:
- Export as JSON+ZIP
- Includes all data, images, models
- Perfect for sharing or archiving

What is JSON+ZIP export?

JSON+ZIP is Modan2’s comprehensive backup format:

Includes:

Landmark coordinates
Object metadata and variables
Dataset settings (wireframe, baseline, polygons)
Attached images and 3D models (optional)
Analysis results

Use cases:

Complete dataset backup
Sharing data with collaborators
Moving data between computers
Long-term archival

Format: Industry-standard JSON + ZIP compression

Performance and Optimization 

How fast can Modan2 handle large datasets?

Tested Performance (Phase 7 validation):

1000 objects load: 277ms (18× faster than target)
1000 objects PCA: 60ms (33× faster than target)
Memory usage: 4KB per object (125× better than target)
UI responsiveness: 12.63ms for 1000-row table

Scalability:

Linear O(n) scaling confirmed
Production-ready for 100,000+ objects
Tested up to 2,000 objects

Can I improve performance?

Tips for best performance:

Use SSD for database storage
Close unused objects in tree view
Reduce polygon count for 3D models
Disable 3D preview during batch editing
Export subsets for large analyses

System optimization:

Ensure adequate RAM (8GB+ recommended)
Update graphics drivers for 3D performance
Use 64-bit Python installation

What if analysis is taking too long?

For large datasets:

Check progress bar - may still be running
Reduce object count - analyze subset first
Simplify analysis - fewer variables
Check memory - ensure sufficient RAM

Typical analysis times:

100 objects: < 1 second
1000 objects: 1-5 seconds
2000 objects: 5-15 seconds

If much slower: Check troubleshooting guide

Troubleshooting 

Where do I get help?

Resources (in order):

This FAQ - Quick answers to common questions
User Guide - Comprehensive documentation
Troubleshooting Guide - Detailed problem-solving
GitHub Issues - Search existing problems/solutions

https://github.com/jikhanjung/Modan2/issues
GitHub Discussions - Ask questions, share workflows

https://github.com/jikhanjung/Modan2/discussions
Email Support - jikhanjung@gmail.com

(Please try above resources first)

How do I report a bug?

GitHub Issues: https://github.com/jikhanjung/Modan2/issues/new

Include this information:

System info:
- Operating system and version
- Python version (python --version)
- Modan2 version (Help → About)
Problem description:
- What you were trying to do
- What actually happened
- Error message (if any)
Steps to reproduce:
1. Open dataset…
2. Click button…
3. Error appears…
Log files:
- Help → View Logs
- Attach relevant log files
Screenshots (if UI-related)

Good bug reports get fixed faster!

Why does Modan2 crash?

Common causes:

Corrupted database → Restore from backup
Out of memory → Close other applications
Graphics driver issues → Update GPU drivers
Qt plugin conflicts → Use fix_qt_import.py (Linux)
Missing dependencies → Reinstall requirements

Debugging steps:

Check log files for error messages
Try with sample data (isolate problem)
Run from command line to see errors
Report crash with log files attached

See Troubleshooting Guide for detailed solutions.

The 3D viewer is not working 

Common issues:

OpenGL not available:
- Update graphics drivers
- Install OpenGL libraries (Linux)
- Check GPU compatibility
Model not loading:
- Verify file format (OBJ, PLY, STL)
- Check file is not corrupted
- Try different model
Black screen:
- Reset view (double-click)
- Check lighting settings
- Try different model

See Troubleshooting Guide → 3D Visualization Issues

Advanced Topics 

Can I use Modan2 in a publication?

Yes! Please do.

How to cite:

@software{modan2_2025,
  author = {Jung, Jikhan},
  title = {Modan2: Geometric Morphometrics Analysis Software},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/jikhanjung/Modan2},
  version = {0.1.5-beta.1}
}

In text:

“Geometric morphometric analyses were performed using Modan2 v0.1.5 (Jung, 2025), an open-source desktop application for landmark-based shape analysis.”