Getting Started

Installing Python3

Regardless of how you intend to use or install Writing3D, you must install Python3 first. Basic instructions are available here, and you can visit the official Python documentation if you have any trouble.

For Windows

If you are on a 64-bit Windows computer, download and run the MSI installer from here. If you are on a 32-bit Windows computer, download and run the MSI installer from here.

For Mac OS X

Download and run the installer for Mac here.

For Debian-based Linux systems (including Ubuntu and Mint)

Run the following from terminal:

$ sudo apt-get install python3 python3-tk

For other Linux systems

Either check your distribution’s documentation for how to install Python3 via your package manager or run the following from terminal:

$ wget https://www.python.org/ftp/python/3.4.3/Python-3.4.3.tar.xz
$ tar xf Python-3.*
$ cd Python-3.*
$ ./configure
$ make; make altinstall

Downloading Writing3D

As a zip file

You can download the latest version of Writing3D as a zip file here. Then, extract the zip archive to any convenient directory on your system.

Using Git

If you know how to use git, you can also just clone the Writing3D repository, which will allow you to stay up to date with new versions and features more easily:

$ git clone https://github.com/wphicks/Writing3D.git

Installing Writing3D

Using the GUI installation script

Once you’ve installed Python3, you can use the included GUI install script (install_w3d.py) to install everything you need for Writing3D.

On Windows

Windows automatically associates .py files with the Python launcher, so you should be able to just double-click on install_w3d.py to begin the install process. Follow the prompts, and the installer will walk you through the process.

On Mac

After installing Python3, you should have an application called PythonLauncher in /Applications/MacPython 3.5/. Drag and drop install_w3d.py onto PythonLauncher, and then follow the prompts. More details are available here.

TODO: This seems to occasionally point to the wrong Python version. Advice from a Mac user would be appreciated.

On Linux

Depending on your desktop environment, you may be able to just double-click on install_w3d.py to run it. If not, open a terminal, cd to the directory containing install_w3d.py and then run:

$ python3 install_w3d.py

Manual installation

To install manually from terminal, just execute the following:

$ python3 setup.py install –user

This will install Blender, and you should now have access to the pyw3d module from Python3.

Warning

Due to a bug in the Homebrew configuration of Python, Homebrew users should instead run

$ python3 setup.py install –user –prefix=

This will prevent the system-level distutils.cfg file from conflicting with the –user flag.

Using w3d_writer: The Writing3D GUI

Unfortunately, w3d_writer is not yet ready for primetime. Check back soon for updates.

In the meantime, you might be interested in CWEditor, the legacy Java-based frontend that was once used in the Brown University CaveWriting program to create VR projects. It outputs to the same XML archival format as Writing3D, so it should interoperate smoothly with the Writing3D backend. You may download this legacy software from here for Mac and Linux and here for Windows.

Once you have downloaded the indicated zip file, extract CWEditor.jar and only CWEditor.jar to some convenient location on your system. Do not extract the other files, or if you do, just copy CWEditor.jar to another directory. Next double-click on CWEditor.jar (on most systems) to run it with the Jave JRE.

Within the editor, go to the “Run” menu and select “Configure paths.” In the resulting dialog, navigate to cwapp.py in the Writing3D samples folder. The editor should now be able to use Writing3D to preview VR projects. See documentation within cwapp.py for additional help and caveats.

Module Documentation

TODO: Create and link w3dui documentation

Using pyw3d: The Python Library

Now that you have Writing3D installed, the best way to get started is to check out some of the examples in the samples directory. These are all carefully documented with instructions on how to make them run. We suggest that you start with link_sample.py, shown here:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
#!/usr/bin/env blender
# Copyright (C) 2016 William Hicks
#
# This file is part of Writing3D.
#
# Writing3D is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>

"""An example showcasing a basic W3DObject with a link


To run this script, use the following command::

    $ python3 link_sample.py
"""

import os
from pyw3d import project, objects, placement, actions, export_to_blender

# First, create a W3DProject to hold everything else you'll create
my_project = project.W3DProject(
    call_directory=os.path.dirname(__file__),
    allow_movement=True
)

# Next, let's create a simple text object
my_object = objects.W3DObject(
    name="hello",  # Give it a name
    color=(255, 0, 0),  # Make it red
    placement=placement.W3DPlacement(  # Specify position and orientation
        position=(0, 1, 0),  # We'll leave rotation as default for now
    ),
    content=objects.W3DText(  # Specify that this is a text object
        text="Hello, World!"  # ...with text reading "Hello, World!"
    ),
    link=objects.W3DLink(  # Add a clickable link to the text object
        actions = {
            -1: [  # On every click (negative number)...
                actions.ObjectAction(  # ...change the object...
                    object_name="hello",  # ...named hello...
                    duration=1,  # ...over a period of one second...
                    move_relative=True,  # ...by moving it relative to its
                                         # current location...
                    placement=placement.W3DPlacement(
                        position=(0, 0.5, 0)  # ...back half a meter.
                    )
                )
            ]
        }
    )
)

# Now add this object to the project
my_project["objects"].append(my_object)

# Enable debugging output
my_project["debug"] = True

#Finally, we render the whole thing using Blender, export it, and display the
#result
export_to_blender(my_project, filename="link_sample.blend", display=True)

TODO: Example with export to Oculus and Brown University Cave