So, you are about to contribute to the Morevna Project? That's great! The question is where to begin. Working in collaboration on such a complex project implies the need to use various open-source tools. Git, wiki, make... All of this stuff could confuse even those who are more or less familiar with the open source development model. Also, to manage the project data effectively we should define and follow certain policies. This manual was written with the purpose to guide you into the depths of the Morevna Project's infrastructure and help you to understand the main principles of the contributor workflow.

Before you begin

First of all, before you contribute, consider the nature of the project. We are only able to accept contributions conforming to two main conditions:

1. By contributing to the Morevna Project Wiki you agree that your contribution or its part can be published in the future by the Morevna Project Team under the terms of one of the Creative Commons Licenses (see http://creativecommons.org/licenses/).
2. Contributed data must be produced with the help of open source software only (see "Main production tools" about page).

Is it alright for you? If yes, then let's go!

Concept documentation

Start by getting familiar with the concept documentation. Let me invite you to the Morevna Project wiki.

There is always a lot of pending tasks at the main page, so you could see what is planned to be done in the nearest future and who is responsible for it. You could track the progress made on particular tasks by other contributors by watching the Recent Changes page.

To be able to edit wiki pages you need to register. When you are editing the wiki please don't forget to write a summary of your changes so other people can easily understand what you have done without watching the whole page. Wiki syntax is intuitive and easy to learn just by watching the markup of existing pages. For detailed information on using the wiki software visit User's Guide.

The most common question is how to upload an image. To insert an image into a post, just write this tag in the message body:

[[Image:Filename.jpg]]

where Filename.jpg is the name which will be assigned to your image after it is uploaded. After you save the page, at the place you inserted the tag you will see a link like this:

File:Filename.jpg

Clicking this link will guide you to the file upload form. After upload your image will appear on the page instead of the tag. If you made a new version of the existing file it's better to upload it under the same name - the wiki stores the file changing history and previous versions could be easily reverted if a mistake happens.

Production tree

If you want to go deeper and work directly on the project footage, you should get a copy of the production tree.

NOTE: All further information is applied to Linux operation systems only.

Structure

The source files are organized in the production tree according to the following structure. There is a screenplay, the main thing. Screenplay is split into parts which we call "scenes". Each scene is a significant (and relatively independent) part of the story, with a particular sequence of particular actions happening in a particular place (or places). Each scene in our screenplay is referred to by a number, which is assigned according the order of the scenes.

Ah, my bad, the screenplay is still not translated into English! Maybe that's the point where you could help?

The animation sources of every scene are stored in a separate directory with the corresponding number. Each scene is planned with a storyboard. Storyboard divides scene into shots. Take a look at the storyboard of the demo and you will see that each shot has an individual number, like the scenes. Source files for each shot are placed in the subdirectory with a corresponding number inside of the scene directory.

There is a scene that currently has a special status - it is scene 04. It is special because it is almost the exact equivalent of the Morevna Project Demo, which we are currently working on. So, the Morevna Project Demo should be considered a scene, too.

Fetching

Project directory tree is managed with git. Git is an open source version control system which allows you to track, manage, collect and combine together changes made by contributors working on a large project.

The project directory tree is stored in the git repositories. There is a main repository, called "production", containing shared data - files which are common for various scenes of the project. Other repositories contain project scenes and are fetched as submodules into the directory of the production repository.

We presume that a person generally won't need to work on all scenes at once. So, you do not need to fetch all project files at once (which is really bandwidth expensive). Instead, just fetch the main "production" repository and only the necessary scenes as submodules. Such an approach dramatically reduces bandwidth usage and it has other advantages, like separating the editing history of one scene from another. That's the reason why this scheme was chosen.

Currently there are no scenes in the project other than the one corresponding to the Morevna Project Demo. So, since we have no choice - let's fetch it.

Repositories are currently in private mode, so you should request an access to it first to be able to work with production files. To request the access just contact the team by email. After you receive your username and password, proceed to the next step.

To fetch the repository you need to install git. Most modern Linux distributions have it in their repositories. We recommend to install the `git-gui' and `gitk' packages along with git itself.

OK, so our working scene is the demo. But it is impossible to work on a particular scene of the project without having a production repository, because it contains all the shared data, such as 3D models, layouts, colorcharts, etc. So we should clone it first.

Warning: The demo repository size is more than 100 Mb.

Open terminal and go to your home directory:

$ cd ~

Note: You may choose any other dir - repository will be fetched there. From here on we will assume what you have chosen the home directory.

Now clone:

$ git clone ssh://user@git.tuxfamily.org/gitroot/morevna/production.git

Replace 'user' with the username that you received. Enter your password when it is requested. The system may ask you about adding an ssh key, answer 'yes'.

Next we should prepare the repository to import submodules:

$ cd production/
$ git submodule init

Now we can fetch submodules. To fetch 'demo' submodule issue the following commands:

$ rmdir demo
$ git clone ssh://user@git.tuxfamily.org/gitroot/morevna/demo.git

As in previous operation, replace 'user' with your username.

Notice, there is already a directory called 'demo' inside of the production repository. Git cannot clone into existing dir, so we have removed the empty demo directory and cloned a repository in it's place. The empty directory is a placeholder for the submodule, so it's undesirable to remove the empty directory from the production repository forever - because git treats this action as removing a module.

Now you have a full copy of the production tree on your computer.

Note: If you read the Git Submodule Tutorial, you will find that we use a different way of fetching submodules than explained there. The use of the 'git clone' command to fetch the submodules has the following advantage - you can do a shallow clone of repository. By default 'git clone' produces a full-fledged repository with it's complete history. Because of the nature of the Morevna Project we have a lot of binary files in repositories (images, Blender scenes) that may result in a huge repository history. To reduce the transfer size you could do a shallow checkout which will cut the history by the specified depth, for example:

$ git clone --depth 2 ssh://user@git.tuxfamily.org/gitroot/morevna/demo.git

Setting up build environment

The production tree contains only the source files of the footage. There is no reason to keep footage in the repository because it could easily be produced from source files (rendered) at any time. To do that you need to have the required software installed. Check the REQUIREMENTS file in the 'production' directory.

You will see something like this inside:

(*) synfig >= SVN 2316
(*) blender = 2.48a
(*) vorbis-tools
(*) make
(-) GIMP >= 2.4
(-) Pencil = 0.4.3b

That means that you need an SVN version of Synfig no less than 2316, version of Blender equal to 2.48a, any version of vorbis-tools and make. Mark (-) near Pencil and GIMP means what they aren't required to render footage, but you will need them if you decide to edit files produced with that software.

Synfig Studio is the main tool for producing the 2D animation in the Morevna Project. It is a relatively young piece of software and not every Linux distribution has it packaged in the repositories by default. New releases come out every half year, although the latest SVN versions usually have some new features and lots of bug fixes compared to the release. Most of those features and bugs, fixed in SVN, are critical to the Morevna Project, that's why we are sticking to the SVN and not to the releases.

Blender is included in the repositories of all popular linux distributions, but usually without FFMPEG support.

Most easy way to install appropriate versions of Synfig Studio and Blender is to get packages from this page.

To get Pencil visit its official download page or compile from source. Though, you need it only if you intend to work with the draft animation sketches (*.pencil files).

The other software mentioned can usually be found in the repositories of any modern Linux distribution. Please refer to your distribution documentation for details about installing software.

Demo background music

Background music for demo is not included in the repository. It is a composition of Per Gessle - "Hey Mr Dj (Won't You Play Another Love Song)" - and we do not have rights to use it yet. If you own a copy of that composition and want to enjoy the demo with background music, you should place a file with the name "Per Gessle - Hey Mr Dj.ogg" into the demo/music directory. If no such file in demo/music is found, then a dummy sound file in the production/lib directory will be used.

Building project

OK, now it's time to render all of the files in the project.

To do that, you should go to every shot subdirectory inside of the 'demo' subdirectory, open every .blend and .sif file there, select the "File" -> "Render", choose the right location, and click "Render", then wait until the shot is rendered. Then go to next directory, open every .blend and .sif file there, select the "File" -> "Render"... OK, now I'm just joking. ^_____^

It's not accidental that we have 'make' in the requirments. All source files in the project are rendered automatically in necessary order with a single command if you have all the software installed correctly. It's all done with the 'make' utility.

And that's not all. Imagine you changed the model of the bike in some way. The bike model is used in scene 48, 52, 53, 55 and...and... Well, of course you don't remember exactly which scenes use the bike model, so you don't remember which of them should be re-rendered. And you don't need to! Just run 'make' again - it will automatically detect changes in the project, resolve dependencies and execute the appropriate actions to update your footage. Only scenes affected by changes will be rendered. Of course, this only happens if the appropriate rules are written correctly for those scenes. We will talk about those rules later.

OK, let's start. Make sure that you have enough free disk space. Currently footage requires approximately 600MB. All rendered files will go to the 'render' directory.

We assume what you still have your terminal open and you are still in the 'production' directory. To render footage just type:

$ make

Note: You could type 'make -j2' if you have a dual-core CPU.

Footage rendering could take a lot time. So it's a good opportunity to take a break and go for a walk. ^_^

After rendering will be finished you will get 'render' directory filled with footage. Make procedure will also produce 'demo.mpg' file inside of the 'render' directory. It is the footage montage rendered into final file so you could watch project at it's current status.

Working on the project

Ok, now you have software and footage and you ready to edit project data.

Let's take a closer look at the contents of the production directory. You already know what 'demo' directory contains a demo scene submodule.

There is also 'lib' directory which contains all project data which is common to the different scenes. I.e. 3D models (bike.blend, helicopter.blend), color charts (colorchart-ivan.sif, colorchart-morevna.sif) and other stuff. If you working on the 3D models, please place textures which are specific to a file of model inside the dir with the same name as the file (i.e. textures for 'lib/bike.blend' will go into the 'lib/bike/' directory).

Production Pipeline

Directory named 'render' contains rendered footage and final animation.

Inside of the demo directory you will find a subdirs with a numbers. They are corresponding to shots in the storyboard. I.e. 'demo/01' contains sources for shot 01, 'demo/02' contains sources for shot 02 and so on. The storyboard itself is located at the 'demo/storyboard' subdirectory.

Inside of the 'demo' directory you will find an important file - 'demo.blend'. It contains a montage, where all footage comoposed together into a single movie. Because you have a footage rendered, you could open it right now. As you see from production pipeline image, we did a montage right after the storyboard was produced. Basically it contained only static images from a storyboard. We used it to sync shots with sound, define length and timing of each shot.

Project montage opened in Blender

When we making a progress on particular shots we replacing them in the montage with their current version. Thus our "slideshow" slowly becomes animated. Usually at first draft animation made - it is called 'animatic'. Animatic helps to define (again) timing of the shot, show the idea of the action happening. It doesn't expose how the characters and objects look - it is concentrated on movement. Animatic could be done in synfig, pencil or blender, depending on the shot. Sometimes we use them together when we want to combine 2D and 3D animation.

After animatic for shot is done, keyframe animators draw keyframes of the shot - characters and objects exposed at extreme positions during their motion. Animation constructed from keyframes only is not smooth and, like animatic, gives just the idea of the motion. The difference is what the objects/characters on keyframes are drawn good and detailed - like they look in final movie. Keyframes are generally drawn in Gimp or Krita. At the same time artists work on the backgrounds. Sometimes we are making a 3D layouts for some locations, to clearly understand the interaction of the characters with environment and camera position at particular shots. Discussions about the work on particular shots and backgrounds are usually happen on the wiki.

When clean keyframes are produced they are traced in Synfig. Synfig takes care about filling the gaps between keyframes - tweening. Animation becomes smooth. And another thing - image becomes resolution independent, so, whatever was keyframe resolution, it is possible to make final rendering in HD.

Notice, what currently footage is rendered at 480x270. Because of that rendering process not consumes SO MUCH time. The final movie supposed to be rendered in 16:9 HD - 1920x1080.

After the animation in Synfig done, it is composited with 3D (if needed), rendered and placed into montage. Compositing could be done not only at the end - we often do compositing at the early stages for animatic and keyframes, inserting result into montage to see how it looks in the whole piece. At current project status you will see a lot of shots at different stages in the montage.

That's how our workflow looks in general. As you see, montage is a central point where you starting from and when you finish working with project files.

Blender Relative Paths button

Working with the project, please remember to always use relative paths, when you linking data from one file to another. Synfig usually do it automatically and even if something goes wrong, its files could easily be edited even with simple text editor and nothing lost. But with blender situation is radically different. If it is not finding some data which was linked through usage of absolute paths - it is loosing it. So please don't forget about little "Relative paths" button in Blender, when you use File-> Append or Link or something like that.

Setting sif extension in Synfig Studio save dialog

Also notice, what all Synfig data in repository is stored in the .sif files. By default Synfig saves new files in compressed .sifz format, what is no good for keeping in git, because changes are not tracked effectively. So please don't forget change format to 'sif', when you saving new files.

Remember, if you made some change into existing project files you could render them into footage by executing 'make' in the 'production' directory. After footage will be re-rendered you could watch changes in the render/demo.mpg video file or in the montage.

If you started work on a new shot, or added a new files to existing shot directory, you possibly need to write Makefile rules to make it render automatically. You could learn it by yourself or ask someone from the project team to do it.

Sharing changes using git

After you made some changes to the project you possibly want to share them with other project participants. You could do that by pushing your changes back into the project repository.

Real power of git comes when you operating with it through command-line. Though, not all of us are comfortable with console, that's why I suggest to use 'git-gui' for commiting changes and updating development tree.

For those, who brave enough to go with command-line I recommend to read a very nice tutorials to grab the basics of git: Pushing and pulling with git - part 1 & part 2.

My following explanation will be about the use of 'git-gui' for commiting data.

I recommend to create a shortcut for 'git-gui' executable on your desktop. If you start it from terminal then it will request all passwords through terminal window, which could be quite confusing sometimes. You may also run git-gui through system Run dialog (which is invoked through Alt+F2 shortcut in Gnome).

When git-gui starts it will offer you following dialog:

Choose 'Open Existing Repository'. In next dialog click "Browse", go to the '~/production/demo' directory and click OK. Then click 'Open'.

Main GitGui window will be shown.

Introduce yourself to git

Each change recorded into repository (commit) will be signed with your name and e-mail. You need to introduce yourself to git. Choose "Edit" -> "Options" and fill name and e-mail fields.

Creating your personal branch

Before commiting your changes it's better to create your personal branch, so your changes won't interfere with changes of other contributors. To do that select "Branch" -> "Create" from menu. Type some sane name into "Name" field (your nickname, for example) and press "Create" button.

Your branch will be created and it will be set to current. Before that your current branch was "master", which is the main project branch.

Browsing repository

You could watch project history by selecting "Repository" -> "Visualize All Branch History". This command will open 'gitk' window.

Green labels is a branches heads. Your current branch is marked with bold text.

There is also a yellow labels - tags. It is a special names for the particular commits. For example, you could see jumps from one version of used software to another. That allows to track regressions if they are appearing.

Now let's see how to add your commit. Close 'gitk' and return to main GitGui window.

Commiting your changes

Imagine, you mage some changes in the demo repository. Press "Rescan" button in the main GitGui window. Changed files will be shown in the red area with a label "Unstaged changes".

Notice, if you made changes outside of the 'demo' submodule - in the 'production' directory, those changes will not be reflected here, 'cause 'production' is an independent repository. To commit changes made there you should open 'production' directory in git-gui and do all requested actions there.

Important: Backup and temporary files are excluded from tracking. We also have *.sifz files in ignore list to prevent user from commiting them by mistake instead of sif files. Check the contents of '.gitignore' file to see a list of ignored files.

Select files you want to commit by clicking on the icons near their names. They will be moved to the green area with a "Staged Changes" label.

Now enter Commit message at the right textbox and press "Commit". Your changes will be added to your local repository.

Please describe your changes in a sane way so it will be clear for other contributors what have you done.

Open "Repository" -> "Visualize All Branch History" again and look at your first commit there. You could do more commits - as many as you like.

You may commit to your repository even if you are not connected to Internet. If you did something wrong on your files you could always revert to one of the previous states. This is a great advantage of git - no Internet connection required when you manipulate your commits - that allows you to arrange them as you like and most effecient.

Please do not commit junk or copyrighted data to repository. Also, watch te size of your files - if they are too huge, then consult with the project team before commiting them. In most cases there is a way to avoid keeping too big files in repository.

When you feel ready to share your work, push commits back into the public repository. To do that, click "Push" button in the main GitGui window.

GitGui asks password in terminal window

In appeared dialog ensure what your branch is highlighted and click "Push". GitGui will ask your password and push your changes to the server.

If you have run 'git-gui' through terminal then password will be prompted in terminal window. Check it if no password prompt dialog appears. That often confusesg me, that's why I not recommend to run 'git-gui' through terminal ^_^.

Updating your branch

Each contributor is working on his separate branch. Project administrators merging their changes into master branch. When you want update your branch with latest changes made in project you should merge your branch with master branch.

To do that you should pull latest changes from repository. Choose "Remote" -> "Fetch from" -> "origin" from menu in main GitGui window. Your password will be requested.

After pull process will be completed check what was changed in the main repository by selecting "Repository" -> "Visualize All Branch History" from menu.

You see, during our work on personal branch, some changes were applied to master branch. We want to incorporate those changes in our branch. Select "Merge" -> "Local Merge".

Select "Tracking Branch", choose 'origin/master' branch from the list and click "Merge". The branches will be merged. Sometimes merge produce conflicts, but usually it is easy to resolve them. Open "Repository" -> "Visualize All Branch History" again to see changes.

Don't forget to re-run 'make' to update footage if you want to get changes reflected in montage.

You could track changes in master branch through cia.vc page: http://cia.vc/stats/project/MorevnaProject. Or if you want to be notified about every project event (including wiki and blog), check out our Underground feed.

Good luck!