🌐 English|한국어

Frequently Asked Questions (FAQ)

General Questions

What is Modan2?

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 source; the released builds are GPL-3.0)

  • 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?

Download the package for your platform from https://github.com/jikhanjung/Modan2/releases — file names carry the version and build number.

  1. Windows: extract the installer ZIP and run the installer inside it

  2. macOS: open the DMG and drag Modan2.app to Applications

  3. Linux: make the AppImage executable and run it

Only the Windows build is well tested; the macOS and Linux packages have not been through the same testing.

See the Installation Guide for detailed instructions.

Where is my data stored?

By default, everything is under one folder. ~ below is your home folder (for example C:\Users\<you> on Windows); see the next question if you would rather keep it somewhere else.

  • Database: ~/PaleoBytes/Modan2/Modan2.db

  • Images and 3D models: ~/PaleoBytes/Modan2/data/

  • Log files: ~/PaleoBytes/Modan2/logs/

  • Backups: ~/PaleoBytes/Modan2/backups/

  • Preferences: your operating system’s settings folder — on Windows %LOCALAPPDATA%\PaleoBytes\Modan2, on macOS ~/Library/Application Support/PaleoBytes/Modan2, on Linux ~/.config/PaleoBytes/Modan2. These are settings, not data.

Note: When you attach an image or 3D model, Modan2 copies it into its own data/ folder, so your originals are left where they are. An oversized photo (longer side above 2560 px) is stored as a smaller working copy with the full-resolution original archived alongside it.

Can I keep my data somewhere else?

Yes. Open Preferences and change Data folder — useful when your 3D models outgrow the drive Modan2 was installed on. The database, images, 3D models, backups and logs all move together; they are one library, and either half is useless without the other.

When you pick a folder, Modan2 offers to move your existing library there:

  • Move now — Modan2 copies everything across, checks that it arrived, and only then removes the originals. You can stop it partway; if you do, your data is left exactly where it was. Nothing ends up half-moved, and when it finishes you can carry on working without restarting.

  • Change the setting only — nothing is moved. Use this to point Modan2 at a library that is already in the new folder, for instance one you copied there yourself. The setting takes effect the next time Modan2 starts.

Warning

Do not put your library in a folder managed by Dropbox, OneDrive, Google Drive or a similar service, and not on a network drive. Modan2 warns you if you try.

Modan2 keeps your data in a database file that it writes to as you work. Sync services upload such a file while it is being written, and if you ever open the same library from two computers they will not merge it — you get two copies that have silently drifted apart, with no way to tell which one is right. Over a network drive, the file locking the database relies on is unreliable and can corrupt it outright.

Keep the library on a local disk, and put backups and exported datasets in the sync folder instead. Those are snapshots: nothing is writing to them, so they are safe to synchronise.

If the folder is missing when Modan2 starts — an external drive that is not plugged in, a share that is down — Modan2 says so and asks what to do rather than starting an empty library.

Can I backup my data?

Yes — use Data ▸ Back Up Library. It writes your whole library to a single .zip file: every dataset, object, landmark, variable, image, 3D model and saved analysis. Put that file wherever you keep your backups.

Two things make it worth using rather than copying folders by hand:

  • A backup is complete or it is not written. If it is interrupted, you get no file at all rather than a truncated one that looks like a backup. And if a file is recorded in the database but missing from your disk, Modan2 tells you which ones instead of quietly leaving holes in the archive.

  • It is safe to synchronise. Unlike the live library, the archive is a snapshot — nothing is writing to it — so a sync folder is a perfectly good place for it. This is what to put in Dropbox or OneDrive instead of your data folder.

To bring it back, use Data ▸ Restore from Backup. Restoring adds the datasets to your library alongside what is already there; nothing is replaced or deleted, and a dataset whose name is taken is given a new one. So a restore started by mistake cannot lose you anything.

Note

Backups do not include your preferences — window layout, colours, chosen language. Modan2 recreates those, and losing them costs you nothing but a few clicks.

Two smaller options remain useful:

  • Export a single dataset as a JSON+ZIP package, or as TPS, Morphologika or another format, when you want to hand one dataset to a colleague. A dataset package deliberately leaves analyses out, so it stays small.

  • Keep your original image and model files. Modan2 copies what you import, but the originals are still the only copy of anything you never imported.

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:

  • A new, empty dataset nested under the parent

  • Objects are not copied into it — you populate it yourself

  • Has its own landmark count, dimension, and variables

Use cases:

  • Organise a study into subgroups

  • Keep related datasets together in the tree

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 one in the object dialog with “Add Missing” / “Insert Missing”, or by typing MISSING into a coordinate cell (a blank cell counts as missing)

  • The viewer draws a hollow circle at each missing landmark’s estimated position while “Show Estimated” is ticked

  • Marking a landmark missing keeps the landmark count consistent across the dataset, which is what analysis requires

How they are estimated: Modan2 fits the dataset’s mean shape onto the landmarks a specimen actually has — matching rotation, scale, and position — and reads the missing positions off the fitted mean. During analysis this is repeated as the alignment settles (an EM-style loop), and the imputed values are used only in the analysis working copy, never written back to your data.

Best practice: keep missing data under about 10% of landmarks, and keep a good number of complete specimens.

Can I capture curves instead of individual points?

Yes — semi-landmark curves (2D only for now).

You define a curve once for the dataset, with a name and a point count N, then trace it on each specimen. Modan2 resamples the trace into N evenly-spaced points along its length, and analysis treats those points like ordinary landmarks, appended after the fixed (anatomical) ones.

  • Trace in the object dialog’s Curve mode

  • “Snap to curve” (on by default) follows the strongest image edge between your clicks, so a clean outline takes only a few points

  • Editing N later re-resamples the stored trace — no need to re-trace

  • Curves round-trip through TPS (CURVES= blocks) and the JSON+ZIP package

  • A dataset can be analyzed with only semi-landmarks and no fixed landmarks

Landmark Digitization

How do I digitize landmarks on 2D images?

Steps:

  1. Create dataset → Set dimension to 2D

  2. Create object → Attach image

  3. Open object dialog

  4. Click on image to place landmarks

  5. Landmarks numbered sequentially

  6. Right-click to delete last landmark

  7. 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:

  1. Create dataset → Set dimension to 3D

  2. Create object → Attach 3D model

  3. Open object dialog

  4. Rotate model to view landmark location

  5. Click to place landmark

  6. Landmark appears as sphere

  7. Continue for all landmarks

  8. Save when complete

3D Controls:

  • Left-drag: Rotate

  • Middle-drag: Pan

  • Right-drag or scroll: Zoom

Can I edit existing landmarks?

Yes! Multiple editing options:

  1. Visual editing:

    • Open object dialog

    • Click and drag landmarks

    • Updates in real-time

  2. Table editing:

    • Edit X, Y, Z coordinates directly in table

    • Precision editing for fine adjustments

  3. 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

Superimposition Methods:

  • Procrustes: translation, rotation, and scaling (the default)

  • Bookstein: baseline registration; requires a baseline on the dataset

Both impute missing landmarks first. Resistant Fit (RFTRA) was offered in earlier 0.2.0 pre-releases and has been withdrawn because it does not converge.

Shape Analysis:

  • Mean shape calculation

  • Shape grid showing how shape changes across a plot

  • Regression overlay on scatter plots

How do I run an analysis?

A single run computes PCA, CVA, and MANOVA together — you do not choose an analysis type.

Steps:

  1. Select the dataset in the tree view

  2. Click Analyze (Ctrl+G) or use the Data menu

  3. Set the analysis name, the superimposition method, and the grouping variables for CVA and MANOVA

  4. Click OK

  5. Open the finished analysis in the Data Exploration dialog

Results include:

  • Score plots (PC1 vs PC2, and other axis combinations)

  • Variance explained per component

  • CVA and MANOVA output for the chosen grouping variables

  • Export options

What is Procrustes superimposition?

Procrustes superimposition removes non-shape variation:

  1. Translation: Centers configurations

  2. Rotation: Aligns to minimize distance

  3. Scaling: Standardizes centroid size

Purpose: Compare shape independent of:

  • Position (translation)

  • Orientation (rotation)

  • Size (scaling)

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:

  1. File → Import → [Format]

  2. Select file (TPS, NTS, Morphologika, etc.)

  3. Choose or create target dataset

  4. Map variables if needed

  5. 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:

  1. Dataset export:

    • File → Export → Dataset

    • Choose format (TPS, Morphologika, JSON+ZIP)

    • Select objects to export

  2. Analysis results:

    • Right-click analysis → Export

    • Save as Excel or CSV

    • Includes scores, loadings, statistics

  3. 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:

  1. Use SSD for database storage

  2. Close unused objects in tree view

  3. Reduce polygon count for 3D models

  4. Disable 3D preview during batch editing

  5. Export subsets for large analyses

System optimization:

  • Ensure adequate RAM (8GB+ recommended)

  • Update graphics drivers for 3D performance

What if analysis is taking too long?

For large datasets:

  1. Check progress bar - may still be running

  2. Reduce object count - analyze subset first

  3. Simplify analysis - fewer variables

  4. 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):

  1. This FAQ - Quick answers to common questions

  2. User Guide - Comprehensive documentation

  3. Troubleshooting Guide - Detailed problem-solving

  4. GitHub Issues - Search existing problems/solutions

    https://github.com/jikhanjung/Modan2/issues

  5. GitHub Discussions - Ask questions, share workflows

    https://github.com/jikhanjung/Modan2/discussions

  6. 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:

  1. System info:

    • Operating system and version

    • Modan2 version and build number (Help → About)

  2. Problem description:

    • What you were trying to do

    • What actually happened

    • Error message (if any)

  3. Steps to reproduce:

    1. Open dataset…

    2. Click button…

    3. Error appears…

  4. Log files:

    • Attach the most recent file from ~/PaleoBytes/Modan2/logs/

  5. Screenshots (if UI-related)

Good bug reports get fixed faster!

Why does Modan2 crash?

Common causes:

  1. Corrupted database → Restore from backup

  2. Out of memory → Close other applications

  3. Graphics driver issues → Update GPU drivers

  4. Graphics/OpenGL problems → See the Troubleshooting Guide

Debugging steps:

  1. Check log files for error messages

  2. Try with sample data (isolate problem)

  3. Run with --debug from a terminal to see errors

  4. Report crash with log files attached

See Troubleshooting Guide for detailed solutions.

The 3D viewer is not working

Common issues:

  1. OpenGL not available:

    • Update graphics drivers

    • Install OpenGL libraries (Linux)

    • Check GPU compatibility

  2. Model not loading:

    • Verify file format (OBJ, PLY, STL)

    • Check file is not corrupted

    • Try different model

  3. Black screen:

    • Check that a 3D model is attached to the object

    • Zoom out — the model may be off-screen

    • Try a 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.”

Can I extend Modan2 with custom analyses?

Yes! Modan2 is extensible:

  • Python API: Use modules directly in custom scripts

  • Database access: Query database with Peewee ORM

  • Export data: Analyze in R, Python, MATLAB

See Developer Guide for API documentation.

How does the database work?

Technology:

  • Engine: SQLite (embedded database)

  • ORM: Peewee (Python Object-Relational Mapping)

  • Location: a single file, ~/PaleoBytes/Modan2/Modan2.db

Tables:

  • md_dataset: Dataset definitions

  • md_object: Objects and landmark data

  • md_image: 2D image attachments

  • md_threedmodel: 3D model attachments

  • md_analysis: Analysis results

Advantages:

  • No server required

  • Portable (single file)

  • ACID compliant (data integrity)

  • Fast queries

  • Easy backup

Can I run Modan2 on a server?

Not currently. Modan2 needs a GUI environment; there is no batch or headless mode.

Current workarounds:

  • Use VNC or Remote Desktop for GUI access

  • Or use X11 forwarding over SSH (ssh -X user@server) and launch the application there — note that 3D rendering often does not work over a forwarded session

Development and Contributing

Is Modan2 open source?

Yes!

  • License: MIT for the source code; GPL-3.0 for the builds we publish

  • Repository: https://github.com/jikhanjung/Modan2

  • Free to use: Commercial and non-commercial

  • Free to modify: Change, extend, redistribute

This means you can:

  • Use in research (published papers)

  • Use in commercial projects

  • Modify for your specific needs

  • Redistribute (must include license)

Can I contribute to Modan2?

Absolutely! Contributions welcome:

Ways to contribute:

  1. Report bugs - GitHub Issues

  2. Suggest features - GitHub Discussions

  3. Fix bugs - Submit Pull Request

  4. Add features - Submit Pull Request

  5. Improve documentation - Edit .rst/.md files

  6. Write tutorials - Share workflows

  7. Translate UI - Help complete the Korean translation, or add a language

Getting started:

  1. Read CONTRIBUTING.md (when available)

  2. Fork the repository

  3. Make your changes

  4. Submit Pull Request

No contribution is too small! Even fixing typos helps.

What features are planned?

Short-term (v1.0):

  • Enhanced documentation

  • UI polish and accessibility

  • Performance optimization

  • Additional statistical tests

  • Beta testing program

Long-term (v1.1+):

  • Command-line interface for batch processing

  • Additional analysis methods

  • Enhanced 3D visualization

  • Plugin system

  • Cloud storage integration

  • Mobile companion app

See GitHub Issues and Milestones for details.

Who develops Modan2?

Primary developer:

  • Jikhan Jung (@jikhanjung)

  • Part of PaleoBytes software suite

  • Developed for morphometrics research

Contributors:

  • See GitHub contributors page

  • Community bug reports and suggestions

  • Open source contributions welcome

Funding/Support:

  • Academic research project

  • No commercial backing

  • Developed for research community

Still Have Questions?

Check these resources:

  1. Installation Guide - Setup and configuration

  2. User Guide - Detailed usage instructions

  3. Troubleshooting Guide - Problem-solving

  4. Developer Guide - Technical details

  5. Advanced Features - Power user tips

Contact:

This FAQ is open source!

Found an error? Have suggestions? Submit a PR to improve this document.