The Problem

Engineers working with CAD data often need to inspect or convert files across formats like STEP, IGES, STL, and glTF. Desktop tools are either proprietary, platform-locked, or lack batch conversion. Mayo addresses this with an open-source, cross-platform viewer and converter built on Qt and OpenCascade.

What This Does

Mayo provides a GUI application (src/app/main.cpp) for interactive 3D visualization—clip planes, assembly explosion, measurement tools, and a view cube—plus a CLI tool (src/cli/main.cpp) for headless file conversion. The repo is a fork of fougue/mayo (2,131 stars upstream), carrying the same feature set.

The codebase is organized into src/ (core logic), i18n/ (English, French, Chinese translations), and images/ (icons and themes). Build configuration lives in CMakeLists.txt, with platform-specific CI workflows under .github/workflows/.

How It Is Wired

Execution starts in src/app/main.cpp for the GUI or src/cli/main.cpp for the CLI. Both initialize Qt and OpenCascade, then route through the application context (src/app/app_context.cpp) which manages document state, file I/O, and the model tree. The CLI path calls conversion routines directly, writing output to the filesystem. The GUI path drives the OpenCascade rendering viewport and user interactions.

The import graph shows 3 internal modules with no edges between them—each operates independently. The most connected modules are the i18n files (i18n/mayo_en, mayo_fr, mayo_zh), which have zero dependencies in either direction. There are no circular dependencies, so changing one module won't cascade unexpectedly. The widest blast radius sits in the third-party headers under src/3rdparty/—fast_float.h and fmt/base.h are 3,462 lines each and heavily included.

How To Use It

Setup: Build with CMake. The repo includes CMakeLists.txt and a Windows-specific helper (cmake/OpenCascadeWin.cmake). You'll need Qt 5/6 and OpenCascade installed.

git clone https://github.com/moses-y/mayo
cd mayo
mkdir build && cd build
cmake .. -DCMAKE_PREFIX_PATH=/path/to/qt;/path/to/opencascade
cmake --build . --config Release

Running: Launch the GUI with ./mayo (binary name per CMake config). For CLI conversion, use ./mayoconv <input> <output>—the README documents mayoconv as the CLI tool. No environment variables are required beyond standard Qt/OpenCascade paths.

Real-World Use

A manufacturing workflow: receive a STEP file from a supplier, inspect it in the GUI for geometry issues, then batch-convert a folder of IGES files to STL for downstream CAM tooling:

./mayoconv part.iges part.stl

The CLI accepts format pairs listed in the README's support table (STEP, IGES, STL, OBJ, glTF, etc.).

Code Health & Issues

Static analysis (not opinion) found 71 total issues: 34 high, 33 medium, 4 low, across 3 kinds.

  • High - Deep nesting (x44): src/3rdparty/fast_float/fast_float.h, fmt/base.h, fmt/chrono.h reach indentation depth 16, making control flow hard to follow. Fix: early returns and extracted blocks.
  • High - Duplicated code blocks: 764 repeated 6-line blocks across 130 files, including i18n/*.ts and miniply.cpp. Fix: extract shared helpers.
  • High - Oversized files (x15): fast_float.h and fmt/base.h exceed 3,400 lines each. Fix: split by responsibility.

SDLC observations from file structure:

  • High - Unpinned CI actions: .github/workflows/ uses version tags (@v1.0.1, @v2, @v3) instead of commit SHAs. A moved tag can execute arbitrary code with your CI token. Fix: pin to 40-char SHAs.
  • Medium - No least-privilege token: 4 workflows declare no permissions, inheriting repo defaults. Fix: add permissions: contents: read.
  • Medium - Large binary in repo: doc/screencast_1.gif is 5.4MB. Fix: use Git LFS.
  • Low - No job timeouts: workflows lack timeout-minutes, risking long-hanging jobs.
  • Low - Missing convention files: no .editorconfig, .gitattributes, or formatter config.

The Bottom Line

Mayo is a functional, well-structured CAD viewer/converter with solid cross-platform CI and clean module boundaries. The upstream project is mature, but this fork carries third-party code that needs maintenance (pinning, splitting, deduplication). Use it if you need reliable STEP/IGES/STL handling without commercial tools—just budget time to harden the CI pipeline first.