VCStudio/wiki/docs/Analytics.md

Analytics

In order to fight procrastination producers invented a tool. This tool is called "Deadline". And the movie is finished when a given date is due. No matter how incomplete it is. Sometimes it results in a lesser films. But most of the times it works to motivate people to work.

VCStudio as a tool that helps you make the whole movie should also give you motivation to work on the project. Rather than spend time doing other things. For this we have the Analytics system. Basically it's our day to day performance, compared to the amount should be done to meet the deadline. And stuff around it. Like checklists, schedules and history.

Chapters:

• User Guide
• Source Code

User Guide

The Analytics is accessed from the Story Editor on the top.

As you can see this window is devided into 3 parts. The left side, the bigger middle part and the right side. This kind of layot will be in multiple places in the VCStudio. Usually it's because on the right there are checklists.

The middle

In the middle usually are the more important parts. This middle part or analytics window, as you may see on the picture above, is also devided into 3 parts vertically.

Progress bars

The progress bars on the very top are there to give you general idea of where the project is in the given time. As you can see you have various progress bars there with icons beside them.

It's the full calculation of all elements in the project. It contains all scenes from the main chain, all assets, all checklists. When the movie is finished. This bar will full.

This bar is quite simple in theory. You have your start date and your deadline. And you have the current date. This progress bar represents the current date in relation to the start date and a deadline. Comparing this bar with the previous bar can give you an over all idea of whether you are behind or ahead of schedule.

That will fill up the more scenes from the main chain will be complited. It will completelly ignore the test scenes and such.

, , and bars per each category of assets.

Grpaph

Just under the progress bars is the graph showing you the same information but over time. Now keep in mind that this example is using a project that was ones a Blender-Organizer project. Which recorded only the main progress bar. And since it was converted to VCStudio project. There is now a huge spike of all assets on the graph. Because they were concidered 0% up to the point of conversion. When suddenly they all became 100%.

The graph has 3 modes that you can access in the panel above it on the left. Let's go over them.

By default you will have the Pulse mode. Which going to give you spikes based on overall progress done in a given time on the graph. Think about this one as sound waveform. If it's flat, nothing was done. If it spikes up. Progress was done. If it spikes down, progress was lost.

The very left mode is the Linear mode. The true values per time. You can see the grey line. It represends the expected percentage over time. Going steady from 0% to 100%. And the graph struggles to addapt to this line.

And the middle mode the Normalized mode. Is if you flatten the time line. Anything behind schedule is below the line and anything ahead of the schedule is above the line.

Calendar

And in the bottom you have a calendar to select days to see various history and schedules for that particular date. And it's also used to schedule tasks.

On the right

On the right side you can see the checklist.

Let's look at a checklist real quick. You can find them all over the program. The image is from Assets for example.

Checklists are quite simple to understand. It's your to do list. But insdead of being just a list. You can make tasks with subtaks in them. And so you can have a more organized to do list. You can move them arround, rename them, delete them, add them.

And one very cool feature is that you can schedule them. And you do this by dragging the task into the calendar of the analytics window.

Now you are probably asking me. But what if I'm in the asset or the script writer? There is no calendar. Well if you going to drag a task toward the center, it will give you a calendar. So don't be afraid to schedule things.

On the left

On the left you have 2 types of data you can access.

Schedules

These are all the scheduled tasks. By default it will give you only your tasks. You can click on the little icon to see all tasks.

If your date is today. Then you also will see all the tasks from all days. ( the finished ones are hidden by default ). You can see the grey task, reddish taks and the purple task.

Grey task means that the task is for today. Red task means that you behind schedule on this one. Purple task is any task that is for any future day.

There is also Green task that are all the finished tasks. And a light Blue task which is for anyday. You can make one by setting any task to 1997/07/30.

Dragging the tasks into the calendar will re-schedule them to a different day.

History

The history is a list of things done. Per date. That were recorded to be done on a given day. Also it's broken up into usernames. So you can see who done what when. Precicelly to the second.

Now will be the most interesting part. But the one that will fry your brain a little. The source code. Please read. There is nothing wrong with reading the source code.

Source Code

The best documentation is to read the code of the software directly. For the analytics I recommend:

• studio/analytics.py Reads the analytics. Calculates the percentages. Records the data for th graph.
• studio/story.py Reads the story and calculates the analytics for the scenes.
• studio/schedule.py Handles all the scheduling. Parses, Filters and renders the schedules.
• studio/history.py Handles all the history. Records history, renders the history.
• studio/checklist.py Handles the checklists. Reads, writes calculates and renders the checklists.
• studio/studio_analyticsLayer.py Render the UI of the analitycs. Records schedules.

How are analytics calculated?

Almost every single script above appart from maybe history is somehow involved in calculating the analytics. The main script studio/analytics.py has 2 functions to calculate analytics. One for the legacy Blender-Organizer projects. And one for the new VCStudio projects.

The legacy was a bit harder because everything was broken up to peaces and using weird text data files that all need to be parsed in their own way. For the new one, most of the stuff is in /set/analytics.json

Now if you only read the /set/analytics.json file alone. It will not do any calculation. There wont be any change. So here is how we do it.

We have 6 items we want to know the percentage of.

• Main checklist.
• Story.
• Characters
• Vehicles
• Locations
• And other assets.

Main checklist is handled by the studio/checklist.py. It reads the /set/project.progress file. Sees what tasks are checked. And calculates the percentage for us.

Story is handled by the studio/story.py. It reads the script. Either the legacy /pln/main.bos or the new /pln/story.vcss and gets the data of all the scenes and all of the shots. Then it looks of whether a given shot has a checklists. If yes using studio/checklist.py it gets a percentage of that shot. If not it looks at whether there are any files in the folders storyboard, opengl, test_rnd or rendered. And gives an aproximation based on the files.

When it got this data it can now calculate the main percentage of the whole story. But first it looks at the arrows ( connections ) and gets a list of scenes that are in the main chain. ( Connected to the Start and End nodes. ) The final story persentage is the average of all the scenes in the main chain.

Assets are calculated some what similarly to story. But instead of having a huge file with a list of assets. It just look into the /dev/ folder and sees what folders exists in there. The asset is finished automatically if a corrisponding named blend file exists in the /ast/ folder. If not it will look into the checklist of each asset.

Combining all of these percentages is not an easy task. There are hidden values ( that I will make a setting for in the future ) that give each category a factor. By default Story has a factor of 4. While each asset category only a factor of 1. Meaning that 1 story worth the same as all 4 categories of assets.

Then combined percentage is averaged with the main checklist. And we get the main percentage.

How checklists can do tasks with in tasks?

Actually my implementation is kind of not the smartest way of doing it. I'm doing real recursion but in python. Which is a bit of a problem.

The file is structured more like a python script. But I'm transforming it into a huge nested dictionary. To do that I'm running a bunch of functions with in themselves. Now if you actually try to do this in python. You will have a recursion error. Because python does not allow above like 1000 level of nesting like this.

But, and this could be my mistake, I don't see a need in 1000 levels of subtasks for any application. There are maybe 20 that fit on the screen there. But technically the checklist is limited to this python's limitation.

Help The Documentation

The documentation files are not perfect. And need maintenance.

If you are reading it from the VCStudio build in Documentation:

• Press to edit locally.
• Press to commit in our NotABug repository.

(C) J.Y.Amihud 2021. Under GPL v3 or later.