Simple 3D Viewer Manual

Last updated December 2024

Introduction

This document describes how to install, run, check and remove Simple Viewer on Linux and Unix-like systems. Please note that the program was written and tested on Ubuntu 22.04 LTS, so its behaviour may differ if you use other versions or OS distributions.

Installation & Running

Prerequisites

Correct compilation and running of the program depends on other utilities and libraries. Check that you have their latest versions before proceeding:

Compilation targets	Utilities
App Compilation & Running	gcc, make
Desktop Interface	Qt5, qmake
Testing	GTest library
GCOV Report	gcov, lcov
Leaks Check	valgrind
Convert Manual to DVI	texi2dvi

Setup

Download or clone (git clone <link_to_git_folder>) the source repository to where you can easily find it. Then type and run the following commands in the terminal:

1. cd <path_to_git_folder>/src/viewer

2. make install

Now the program is compiled, placing the app in a folder named SimpleViewer/. The app should open automatically. If you want to open it later using command line, run make viewer. If there are errors, you're likely missing some packages. Check Prerequisites.

Usage

The app layout should be fairly intuitive. On the first load, you'll see a horizontal Menu Tab plus an Information Tab on the right side of the screen. The Menu Tab is divided into three sub-categories and the options you choose are saved after each session:

> File

(a) Upload file — choose .obj file to display

(b) Save as .bmp, .jpg — save current render as a picture

(c) Make screencast — save current render as a GIF (5sec, 10 frames/sec, 640x480) with custom model rotation

(d) Exit — close the app

> Model

(a) Rotate — rotate the model on a given axis by N degrees

(b) Translate — translate the model on a given axis by N degrees

(c) Scale — scale the model on a given axis by N degrees

(d) Wireframe — display model as wireframe (as opposed to solid)

(e) Parallel projection — apply parallel projection (as opposed to central, or perspective projection)

> Settings

(a) Set background — change background colour

(b) Set texture — choose texture (only in SOLID MODE)

(c) Vertices — set colour, size and display mode (circle, square, none) of vertices (only in WIREFRAME MODE)

(d) Edges — set colour, size and dashed mode of edges (only in WIREFRAME MODE)

(e) Show information — toggle the visibility of the Information Tab

The model is initially displayed in the central part of the screen (Tip: if you can't see your model at first, try changing its dimensions and coordinates. Also check the settings to ensure that the model and background are differently coloured). The Information Tab lists the keys to manipulate your model as well as its number of edges and vertices. Additionally, you can click and drag the mouse to rotate your object and scroll with the mouse wheel to scale it.

Here are some examples of what you can produce with this app:

A model of a cat (src/assets/models/cat.obj) with a texture applied to it (src/assets/textures/car.jpg).

And here's the same model in wireframe mode.

And here's a rotating wireframe sword model (src/assets/models/sword.obj).

Structure & testing

The program was made using C++17 language and standard libraries, with the interface provided by Qt5. It uses an MVC design structure to separate the interface from the controller and model. The source code can be found in src/viewer/backend and src/viewer/frontend folders. The backend libraries can be tested with GTest:

1. To run tests: make test

2. To display test coverage: make gcov_report

3. To check for leaks: make valgrind

Running make or make all will reinstall and compile the program. You can get DVI documentation with make dvi or a distribution .tar.gz package with make dist.

Also note:

1. Not every model can be processed by this simple app — check src/assets/models for inspiration.

2. The basic textures and shaders in src/assets/textures and src/assets/shaders are needed for the app to function (but you can mod and replace them if you know what you're doing).

3. This app uses external libraries to process .gif, .jpg, .bmp and .obj files: please see src/external for licenses.

4. All make commands should be run from src/viewer Use make clean to get rid of the post-compilation junk.

Deinstallation

Simply run make uninstall. This will remove the SimpleViewer/ directory but not the original download, which can be safely deleted afterwards.

If you wish to suggest an improvement or report a bug, contact me @ginzburg_jake (Telegram) or JakeTheSillySnake (GitHub).