start docs site

README.md

+
 # Scotty3D
+
+Welcome to Scotty3D! This 3D graphics software implements interactive mesh
+editing, realistic path tracing, and dynamic animation. Implementing the
+functionality of the program constitutes the majority of the coursework for
+15-462/662 Computer Graphics at Carnegie Mellon University
+
+The [User Guide](docs/guide/guide.md) describes the intended functionality of the software to an end user.
+
+The components of the Developer Manual are exhaustively listed on the sidebar to the right, and are organized under the three main components of the software:
+
+- [MeshEdit](docs/meshedit/overview.md)
+- [PathTracer](docs/pathtracer/overview.md)
+- [Animation](docs/animation/overview.md)
+
+See the sidebar on the right for access to all material in this wiki. In particular,
+please read through the [Project Philosophy](docs/philosophy.md) before you begin work.

docs/building.md

+
+## Build Instructions
+
+![Ubuntu Build Status](https://github.com/CMU-Graphics/Scotty3D-dev/workflows/Ubuntu/badge.svg) ![MacOS Build Status](https://github.com/CMU-Graphics/Scotty3D-dev/workflows/MacOS/badge.svg) ![Windows Build Status](https://github.com/CMU-Graphics/Scotty3D-dev/workflows/Windows/badge.svg)
+
+To get the code:
+
+```git clone https://github.com/CMU-Graphics/Scotty3D.git```
+
+Note: the first build on any platform will be very slow, as it must compile the source-based dependencies. Subsequent builds will only need to re-compile your edited Scotty3D code.
+
+### Linux 
+
+The following packages (ubuntu/debian) are required, as well as CMake and either gcc or clang:
+```
+sudo apt install pkg-config libgtk-3-dev libsdl2-dev
+```
+
+The version of CMake packaged with apt may be too old (we are using the latest version). If this is the case, you can install the latest version through pip:
+```
+pip install cmake
+export PATH=$PATH:/usr/local/bin
+```
+
+Finally, to build the project:
+```
+mkdir build
+cd build
+cmake .. 
+make -j4
+```
+
+The same process should also work modified for your distro/package manager of choice. Note that if you are using Wayland, you may need to set the environment variable ``SDL_VIDEODRIVER=wayland`` when running ``Scotty3D`` for acceptable performance.
+
+Notes:
+- You can instead use ``cmake -DCMAKE_BUILD_TYPE=Debug ..`` to build in debug mode, which, while far slower, makes the debugging experience much more intuitive.
+- You can replace ``4`` with the number of build processes to run in parallel (set to the number of cores in your machine for maximum utilization).
+- If you have both gcc and clang installed and want to build with clang, you should run ``CC=clang CXX=clang++ cmake ..`` instead.
+
+### Windows
+
+The windows build only supports the Visual Studio compiler (for now). You can download Visual Studio Community 2019 [here](https://visualstudio.microsoft.com/downloads/). Be sure to install the "Desktop development with C++" component.
+
+You can download CMake for windows [here](https://cmake.org/download/).
+
+Once the Visual Studio compiler (MSVC) is installed, you can access it by running "Developer Command Prompt for VS 2019," which opens a terminal with the utilities in scope. The compiler is called ``cl``. You can also import these utilities in any terminal session by running the script installed at ``C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat``. 
+
+We also provide a simple script, ``build_win.bat``, that will automatically import the compiler and build the project. You should be able to simply run it in the project root to build. ``Scotty3D.exe`` will be generated under ``build/RelWithDebInfo/``.
+
+If you want to build manually, the steps (assuming MSVC is in scope) are:
+```
+mkdir build
+cd build
+cmake ..
+cmake --build . --config RelWithDebInfo
+```
+
+You can also use ``--config Debug`` to build in debug mode, which, while far slower, makes the debugging experience much more intuitive. If you swap this, be sure to make a new build directory for it.
+
+Finally, also note that ``cmake ..`` generates a Visual Studio solution file in the current directory. You can open this solution (``Scotty3D.sln``) in Visual Studio itself and use its interface to build, run, and debug the project. (Using the Visual Studio debugger or the provided VSCode launch options for debugging is highly recommended.)
+
+### MacOS
+
+The following packages are required, as well as CMake and clang. You can install them with [homebrew](https://brew.sh/):
+```
+brew install pkg-config sdl2
+```
+
+To build the project:
+```
+mkdir build
+cd build
+cmake .. 
+make -j4
+```
+
+Notes:
+- You can instead use ``cmake -DCMAKE_BUILD_TYPE=Debug ..`` to build in debug mode, which, while far slower, makes the debugging experience much more intuitive.
+- You can replace ``4`` with the number of build processes to run in parallel (set to the number of cores in your machine for maximum utilization).

docs/guide/guide.md

+
+The User Guide provides some end-user information on how to use Scotty3D.
+
+## Modes and Actions
+
+The basic paradigm in Scotty3D is that there are six different _modes_, each
+of which lets you perform certain class of actions. For instance, in `Model` mode, you
+can perform actions associated with modeling, such as moving mesh elements and performing global mesh operations. 
+When in `Animate` mode, you can perform actions associated with animation. Etc. 
+Within a given mode, you can
+switch between actions by hitting the appropriate key; keyboard commands are
+listed below for each mode. Note that the input scheme may change depending on
+the mode. For instance, key commands in `Model` mode may result in
+different actions in `Render` mode.
+
+The current mode is displayed as the "pressed" button in the menu bar, and available actions
+are are detailed in the left sidebar. Note that some actions are only available when a model/element/etc. is selected.
+
+## Global Navigation
+
+In all modes, you can move the camera around and select scene elements. Information about your selection will be shown in the left sidebar. 
+
+The camera can be manipulated in three ways:
+- Rotate: holding shift, left-clicking, and dragging will orbit the camera about the scene. Holding middle click and dragging has the same effect.
+- Zoom: using the scroll wheel or scrolling on your trackpad will move the camera towards or away from its center.
+- Translate: right-clicking (or using multi-touch on a trackpad, e.g., two-finger click-and-drag) and dragging will move the camera around the scene.
+
+## Global Preferences
+
+You can open the preferences window from the edit option in the menu bar.
+- Multisampling: this controls how many samples are used for MSAA when rendering scene objects in the Scotty3D interface. If your computer struggles to render complex scenes, try changing this to `1`. 
+
+## Global Undo
+
+As is typical, all operations on scene objects, meshes, etc. are un and re-doable using Control/Command-Z to undo and Control/Command-Y to redo. These actions are also available from the `Edit` option in the menu bar.
+
+## Mode Guides
+
+- [Layout](layout.md)
+- [Model](model.md)
+- [Render](render.md)
+- [Rig](rig.md)
+- [Animate](animate.md)
+- [Simulate](simulate.md)
+
+

docs/guide/layout.md

+
+# Layout
+
+This is the main scene editing mode in Scotty3D, and does not contain tasks for the student to implement. 
+This mode allows you to load full scenes from disk, create or load new objects, export your scene (COLLADA format), and edit transformations that place each object into your scene.
+
+## Creating Objects
+
+There are three ways to add objects to your scene:
+- `Import New Scene`: clears the current scene (!) and replaces it with objects loaded from a file on disk.
+- `Import Objects`: loads objects from a file, adding them to the current scene.
+- `New Object`: creates a new object from a choice of various platonic solids.
+
+To save your scene to disk (including all meshes and their transformations) use the `Export Scene` option.
+
+Scotty3D supports loading objects from the following file formats:
+- dae (COLLADA)
+- obj
+- fbx
+- gltf / glb
+- 3ds
+- stl
+- blend
+
+Scotty3D only supports exporting scenes to COLLADA.
+
+## Managing Objects
+
+Left clicking on or enabling the check box of your object under `Select an Object` will select it. Information about that object's transformation will appear under `Edit Object` beneath the "Select an Object" options. 
+
+Under `Edit Object`, you may directly edit the values of the object's position, rotation (X->Y->Z Euler angles), and scale. Note that clicking and dragging on the values will smoothly scale them, and Control/Command-clicking on the value will let you edit it as text. 
+
+You can also edit the transformation using the `Move`, `Rotate`, and `Scale` tools. One of these options is always active. This determines the transformation widgets that appear at the origin of the object model.
+- `Move`: click and drag on the red (X), green (Y), or blue (Z) arrow to move the object along the X/Y/Z axis. Click and drag on the red (YZ), green (XZ), or blue (XY) squares to move the object in the YZ/XZ/XY plane.
+- `Rotate`: click and drag on the red (X), green (Y), or blue (Z) loop to rotate the object about the X/Y/Z axis. Note that these rotations are applied relative to the current pose, so they do not necessarily correspond to smooth transformations of the X/Y/Z Euler angles.
+- `Scale`: click and drag on the red (X), green (Y), or blue(Z) block to scale the object about the X/Y/Z axis. Again note that this scale is applied relative to the current pose.
+
+Finally, you may remove the object from the scene by pressing `Delete` or hitting the Delete key. You may swap to `Model` mode with this mesh selected by pressing `Edit Mesh`. Note that if this mesh is non-manifold, this option will not appear.
+
+## Key Bindings
+
+| Key                   | Command                                            |
+| :-------------------: | :--------------------------------------------:     |
+| `r` | Swap between `Move`, `Rotate`, and `Scale`. |
+| `delete` | Delete currently selected mesh. |
+
+## Demo
+
+![layout](layout.mp4)

docs/philosophy.md

+
+# Project Philosophy
+
+Welcome to your first day of work at Scotty Industries! Over the next few months
+you will implement core features in Scotty Industries' flagship product
+Scotty3D, which is a modern package for 3D modeling, rendering, and animation.
+In terms of basic structure, this package doesn't look much different from
+"real" 3D tools like Maya, Blender, modo, or Houdini. Your overarching goal is
+to use the developer manual to implement a package that
+works as described in the [User Guide](guide/guide.md), much as you would at a real
+software company (more details below).
+
+Note that the User Guide is **not** an Assignment Writeup. The User Guide
+contains only instructions on how to use the software, and serves as a
+high-level specification of _what the software should do_. The Developer Guide
+contains information about the internals of the code, i.e., _how the software
+works_. This division is quite common in software development: there is a
+**design specification** or "design spec", and an **implementation** that
+implements that spec. Also, as in the real world, the design spec does _not_
+necessarily specify every tiny detail of how the software should behave! Some
+behaviors may be undefined, and some of these details are left up to the party
+who implements the specification. A good example you have already seen is
+OpenGL, which defines some important rules about how rasterization should
+behave, but is not a "pixel-exact" specification. In other words, two different
+OpenGL implementations from two different vendors (Intel and NVIDIA, say) may
+produce images that differ by a number of pixels. Likewise, in this assignment,
+your implementation may differ from the implementation of your classmates in
+terms of the exact values it produces, or the particular collection of
+corner-cases it handles. However, as a developer you should strive to provide a
+solution that meets a few fundamental criteria:
+
+*   [Failing gracefully](https://en.wikipedia.org/wiki/Fault_tolerance) is
+preferable to failing utterly---for instance, if a rare corner case is difficult
+to handle, it is far better to simply refuse to perform the operation than to
+let the program crash! 
+*   Your implementation should follow the [principle of least
+surprise](https://en.wikipedia.org/wiki/Principle_of_least_astonishment). A user
+should be able to expect that things behave more or less as they are described
+in the User Guide. 
+*   You should not use an algorithm whose performance is [asymptotically
+worse](https://en.wikipedia.org/wiki/Asymptotic_computational_complexity) just
+because it makes your code easier to write (for instance, using [bubble
+sort](https://en.wikipedia.org/wiki/Bubble_sort) rather than [merge
+sort](https://en.wikipedia.org/wiki/Merge_sort) on large data sets). 
+*   That being said, when it comes to performance, [premature optimization is
+the root of all evil!](https://en.wikipedia.org/wiki/Program_optimization#When_to_optimize) The only way to know whether an optimization matters is to [measure performance](https://en.wikipedia.org/wiki/Profiling_(computer_programming)), and understand [bottlenecks](https://en.wikipedia.org/wiki/Program_optimization#Bottlenecks). 
+*   Finally, you should take pride in your craft. Beautiful things just tend to work better.
+
+Just to reiterate the main point above:
+
+**As in real-world software development, we will not specify every little detail
+about how methods in this assignment should work!**
+
+If you encounter a tough corner case (e.g., "how should edge flip behave for a
+tetrahedron"), we want you to _think about what a good **design choice** might
+be_, and implement it to the best of your ability. This activity is part of
+becoming a world-class developer. However, we are more than happy to discuss
+good design choices with you, and you should also feel free to discuss these
+choices with your classmates. Practically speaking, it is ok for routines to
+simply show an error if they encounter a rare and difficult corner case---as long as it
+does not interfere with successful operation of the program (i.e., if it does
+not crash or yield bizarre behavior). Your main goal here above all else should be 
+to develop _effective tool for modeling, rendering, and animation_.