FreeCAD/FreeCAD

OBJ importer dialog is confusing for new users

Open

#21,307 opened on May 13, 2025

View on GitHub
 (3 comments) (2 reactions) (0 assignees)C++ (30,913 stars) (5,550 forks)batch import
File format: OBJHelp wantedMod: CoreTopic: User InterfaceType: Feature

Description

Is there an existing issue for this?

  • I have searched the existing issues

Problem description

The OBJ file import dialog prompts the user to select an importer:

Image

  1. There is no context or guidance as to which one the user should choose
  2. Although both are OBJ format importers, their name wildly differs and is rather technical

OBJ format naming

What's probably most unfortunate is the format naming. Both import the same format, but simply process it differently. Yet they should not name the format differently.

From these sources, the format should be either called Alias/Wavefront OBJ, or Wavefront OBJ:

FreeCAD OBJ importer comparison

Aspect Alias Mesh importer Wavefront OBJ importer
Use cases - Raw mesh processing (3D printing, simulations).- Large files where speed matters. - BIM/architectural workflows- An additional materials file (.mtl) is required
Mesh handling Raw triangles, no post-processing. Merges coplanar faces.
Implementation C++ (MeshCore::MeshIO), Mesh workbench Python (importOBJ.py), BIM workbench
Performance Faster (C++ backend). Slower (Python overhead).

Proposal

While changing the import dialog to select the module would make more sense, it looks like a big task at a glance. An initial improvement though, would be to unify the file format names of both importers to e.g. Wavefront OBJ. If a distinction needs to be made,

Current name New name proposal
Alias Mesh Wavefront OBJ
Wavefront OBJ Wavefront OBJ for architecture

It might be worth researching how other software names the OBJ format as well.

Full version info

1.1.0-dev

Subproject(s) affected?

Other (specify in description)

Anything else?

  1. https://wiki.freecad.org/Arch_OBJ describes the difference as:

    Additionally to the standard FreeCAD OBJ exporter, the BIM Workbench features an alternative exporter that exports coplanar faces as whole OBJ faces, instead of triangulating Shape-based objects, like the standard exporter does.

  2. An example of a user being confused (they received no answer for the particular question either): https://blender.stackexchange.com/questions/243684/blender-import-whats-the-difference-between-wavefront-and-alias-mesh
  3. Another example (the OBJ format exporter has the same issue): https://forum.freecad.org/viewtopic.php?t=19230
  4. The naming issue also applies to the exporter counterpart

Code of Conduct

  • I agree to follow this project's Code of Conduct

Contributor guide

Tech stack
cpppython
Domain
frontenddesign
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
under 1 hour
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
None
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
80
Research direction
Locate the import dialog source code in FreeCAD. The dialog is likely defined in a Python file under the BIM workbench (e.g., importOBJ.py) and the mesh workbench (C++ code in MeshCore::MeshIO). Search for the strings 'Alias Mesh' and 'Wavefront OBJ' to identify the GUI labels. The proposal suggests renaming both to 'Wavefront OBJ' and optionally 'Wavefront OBJ for architecture'. Also check the exporter dialog (issue mentions exporter counterpart). Review the forum links provided in the issue for additional context. Make the changes in a new branch and test by importing an OBJ file.