calband / calchart-viewer

An online show viewer and continuity generator for Calchart.

Calchart Viewer

Motivation

The goal of Calchart Viewer is to provide an easy way for Cal Band members to prepare for a performance by watching a preview of the charting file generated by Calchart. We aim to do this by building a web app which has three main features:

1. Provide a preview of the show, rendered in a web page.
2. Allow users to highlight their spot and step through the show with music.
3. Allow users to generate a PDF printout of their specific continuity (moves) for the show.

Installing and building

1. Install nodejs. Node comes packaged together with npm ("node package manager") on windows and mac. For linux, please see this post.
2. Navigate to the project root in your terminal of choice.
3. npm install: this will install all the dependencies needed to compile the javascript in this project.
4. npm install -g grunt-cli: this will allow you to run grunt commands.
5. grunt build: this will compile the javascript into the build/js/application.js file. Webpack allows us to import things in javascript using the require function. See app/js/application.js and app/js/viewer/ApplicationController.js for an example. This will also compile the LESS code into the CSS files that the app needs to work.
6. Open app/index.html in your browser. Presto!

Developing

When you change a javascript file, you will have to compile build/js/application.js again by running grunt webpack:build. Same thing with when you change a .less file: you'll need to run grunt less to compile to CSS. You should run grunt watch from the project root: this will start a task that listens for changes to the javascript and less files and autocompiles build/js/application.js and all the CSS files on every save.

Contributing

Open issues and milestones are on the issues page. When you start work on an issue, assign yourself to it to make sure no two people work on the same thing at the same time. Please work on your own branch and submit a pull request when you're done so it can be reviewed for style: tag the person you want to review it in the pull request, but feel free to comment on any open pull request with questions/conerns. Noah will be responsible for merging the pull requests into master or not.

If you have an idea for a feature, general question, bug report, etc, open an issue about it! All issues will be triaged.

Architecture Diagram

You can find a very high level overview of how the code architecture should work and interact with the UI here.

Deploying

To push changes to http://calband.github.io/calchart-viewer, checkout the master branch and run source scripts/push.sh.

calchart-viewer's Issues

Arrow keys should nudge show by one beat

When the left and right arrow keys are pressed, the animation should move along by a beat (forward or backword, depending on the key).

Clicking "next stuntsheet" while music is playing should reset music to the correct stuntsheet

Title says it all. This is a nice to have though. We could also simply disable the next/prev sheet/beat buttons while music is playing

Inconsistency in the way that music animation plays when started from beginning vs. when started from middle

Hook up html ui to select and display dot labels

The html select box should actually display the relevant dot labels and you should be able to select them.

Grapher should draw dots

Blocking this issue: #13, #7

Description: Implement fully the draw(stuntsheet, currentBeat, selectedDot) function of the Grapher object from #13. Given a Sheet object, and int representing the beat of that stuntsheet to draw, and the string representing the dot label of the selected dot, the dots should be rendered on the preview.

End result: I should be able to create a full Sheet object and pass it to the draw function of the Grapher, and actually see the dots render correctly.

Show the print continuity for the current stuntsheet if a dot is selected

i.e. if I've selected dot 124 and I'm on SS 14, I want to see the "Execute REMEMBER THAT YOU ARE JUICE continuity facing East".

Metadata in JSON output

We are going to need more metadata in the JSON charts. There's no concept of anything about the name, year, indexable name, etc. in the current format of charts. There's probably a lot more we would want to know about the charts for retrieval purposes.

Implement MovementCommand: Arc

Issues blocking this issue: #6

Description: Implement ArcMovementCommand. This should take the same constructors, etc as MovementCommand, but should implement getAnimationState correctly (see #6, #7 ).

                        // move in an arc for 12 beats in a radius from current position
                        // to the specified center, in the given cw/ccw direction, one step every 1 beats,
                        // over the specified angle in degrees, while facing away from the direction of travel
                        // by an offset of 90 degrees in the given cw/ccw direction
                        // the start coordinates and arc center coordinates are measured in number of steps from
                        // the upper left corner of the field. these coordinates can have float values.
                        {
                            "type": "arc",
                            "start_x": 40,
                            "start_y": 50,
                            "center_x": 300,
                            "center_y": 32,
                            "angle": 240,
                            "direction": "ccw",
                            "beats": 12,
                            "beats_per_step": 1,
                            "facing_offset": 90,
                            "face_offset_direction": "ccw"
                        },

End result: I should be able to instantiate an ArcMovementCommand with start and end positions and it should return the correct values when getAnimationState is called.

Using the beats file, enqueue and play animation updates

Issues Blocking This Issue: #5, #29, #14, #16

Description: This is the coup d'etat of the calchart viewer: play the show along with the music! To do this, we'll need the file upload, mp3 playing, and grapher to be implemented fully. This issue should attach the functionality to the "animate with music" button that tells the ApplicationController to take the beats file content, enqueue the animationState updates to be processed at the right times, then kick off the music and the animation queue at the same time to make the show play along with the music.

End result: I should be able to upload a beats file, viewer file, and mp3 file that correspond to each other, and they should result in the actual show playing along in sync with music.

Implement MovementCommands: Goto, Even

Issues blocking this issue: #6

Description: Implement GotoMovementCommand and EvenMovementCommand. These should take the same constructors, etc as MovementCommand, but should implement getAnimationState correctly (see #6, #7 ).

                        {
                            "type": "goto",
                            "beats": 1,
                            "from_x": 320,
                            "from_y": 50,
                            "to_x": 320,
                            "to_y": 60
                            "facing": "east"
                        },
                        {
                            "type": "even",
                            "beats": 12,
                            "beats_per_step": 1,
                            "x1": 300,
                            "y1": 32,
                            "x2": 300,
                            "y2": 36,
                            "facing": "east"
                        }

End result: I should be able to instantiate goto and MovementCommands with start and end positions and they should return the correct values when getAnimationState is called.

Better handling of continuity text errors

There are no continuities for stuntsheet 13 of the pink show, resulting in this the previous sheet's continuity being shown, and this:

Let's handle this better instead of throwing errors (e.g. just reset the continuity div in the html to be empty).

Implement HTML/CSS interface

Description: Implement the design represented here:

End Result:

1. Header, highstepper, buttons, etc should be implemented, clicking on buttons should not do anything.
2. Graph should be an empty space.

Add select box for choosing file from calchart server

This will happen once the calchart viewer file server is done. We should add a select box that grabs the current shows through a GET request and allows the user to load the show based on which one is selected.

Pressing the "Prev Stuntsheet" button while on the first stuntsheet should bring you to first beat of the sheet

Implement the PDF printout

Issues blocking this issue: #32

Description: Once the printout has been designed, we have to actually implement generating the PDF. This should happen in the ApplicationController by looking at the current Show and the selected dot from the AnimationStateController, figuring out what continuities it needs, drawing the necessary pictures, then outputting them to a pdf. We should use jsPDF to do this: let me know and I can get you that script: I've already downloaded it.

End Result: I should be able to actually generate a legit continuity printout for a show, and it should look like the design and not get cut off when actually being printed out. This is the END RESULT of Calchart Viewer v1.1!!

• #101
• #102
• #103
• #104
• #105
• #106
• #107
• #124

Animate button still says "stop animation" when the animation is finished

API for charts

@noahsark769 @kmdurand

So, we should hash out the basics of what should be expected from the database of charts. The current format of filenames and stuff doesn't really give us a proper and easy to use index, and it would be cumbersome to have some kind of search thing and then choose a unique id from among them, so my idea is to standardize to a degree the filenames of charts and use that as a unique key so I could do something like:

GET calchartdb/get_chart/2013-pixar-show

And get the pixar show. I imagine a format like yyyy-{name with hyphens} would work fine enough. Also, how are we planning to keep the viewer updated to the correct show within a given week? Cause I was thinking it may be wise to also have an endpoint that would query the nth show of a given football season.

GET calchartdb/get_show/2014/1

To get the first show of the 2014 season. This may be a bit much but it would at least make maintaining the correct show to be easy, or better yet:

GET calchartdb/get_current_show

To get this week's show, no matter what.

What sort of format would you imagine to be the most helpful? I feel like the first is necessary no matter what, and one of the next two would be nice to have.

Standardizing Debugging Code

I think we should come up with a standard for how we write our debugging code (type checks and the like). Example:

var func1 = function(intParam, stringParam) {
    //DEBUG_START
        assert(isInt(intParam), "first parameter should be an int");
        assert(isString(stringParam), "second parameter should be a string");
    //DEBUG_END
    //other code here...
}

I think it's best that we eventually comment out the debugging code, to speed up our final application, and if we standardize the debugging code somehow, like in the example above, it should be really easy to make sure that all of the debugging code has been removed. All we'd need to do is perform a quick document search for the keyword "DEBUG_START", and then make sure everything between that keyword and "DEBUG_END" is commented out.

Take Viewer file content and make Show, Sheet and Dot objets

Issues Blocking this Issue: #5

Description: After we're able to get the content of the files, we're going to need to parse the viewer file content (use JSON.stringify) and create an object oriented representation of it. This will take the form of a Show class which will contain many Stuntsheet objects, which themselves will contain Dot objects.

The Show object

The show object should contain three things, accessible by setter methods: a description, an array of strings which represent dot labels, and an array of Stuntsheet objects. See the spec to see how this is represented in the viewer file. The following methods should be implemented:

1. Show(description, dotLabels): (constructor) create a new show without any stuntsheets.
2. getDescription: return the show description
3. getStuntsheets: return the array of Stuntsheet objects
4. addStuntsheet(stuntsheet): add a stuntsheet to the show
5. Show.fromJSON: (static method) return a new show matching the given JSON format as a string (the format from here).

The Sheet object

The Sheet object is a wrapper around various information about a stuntsheet. It should have a constructor which takes the necessary arguments and accessor (get) methods for label, field type, dot types, dot labels, and continuities as specified in the viewer filespec. In addition:

1. getDuration: return the number of beats this stuntsheet is, as an int.
2. getDots: return the array of Dot objects representing the dots in this stuntsheet.

The Dot object

The dot object encapsulates the list of MovementCommands (see #6). It should have the necessary constructors and accessor methods to contain that. In addition, it should support:

1. getAnimationState(beatNum): Given the current beat of the stuntsheet, pick the correct MovementCommand and return its animationState.

End Result: Show, Sheet, and Dot objects should be instantiatable in the console, and a Show should be createable from JSON through Show.fromJSON.

Error checking for file uploads

If we try to upload a viewer file that doesn't look like a viewer file (e.g. someone uploaded it to the wrong file input) we should display a message telling the user what to do.

Infrastructure backbone: LESS and Webpack

Description:

1. Implement the infrastructure and development enviornment we'll use for the project. This includes:
   1. Implement grunt for task running
   2. Implement grunt task to compile LESS to CSS
   3. Implement grunt task to use webpack to compile js files into one file and thus allow imports.
   4. Implement grunt to watch files and do this automatically on save.
2. Add README.md with description of how to install and build the app.
3. Implement the directory structure of the app and accompanying description in the README.

End result: Javascript that prints "hello world" to the console should be defined in a javascript module and actually work.

Feedback form

We should have a link to a google form in the html UI so that people can give feedback.

What is the purpose of the app.css file in the css folder?

Isn't the app.css file generated by the app.less file anyway?

Implement a dummy MovementCommand class

Issues blocking this issue: #3

Description: Implement a MovementCommand class. You don't need to implement the entire class, just a skeleton which logs "method called" to the console when a method is called.

The MovementCommand class

A MovementCommand defines exactly one movement that a marcher must make during a show. For example, this might be a forward march highstep 4 East, or a pinwheel around point H4, or any number of things. A marcher might have many movements per stuntsheet: for example, 4 east, 6 west, mark time 16 east. The MovementCommand encapsulates all the information about a single movement.

As far as the calchart viewer is concerned, there are exactly six possible types of movements (remember, the view cares only about the information it needs to display, so things like step style, for example, don't matter). These types are: stand, mark, move, goto, mark, and even. For this issue, you do not need to care about any of these types of movements: instead, you just need to create a class definition for the MovementCommand class.

The MovementCommand class should always know about the start position and the end position of its movement. This way, when we want to know where a dot should go for the next beat, we can simply ask its MovementCommand to tell us, and the MovementCommand will take care of calculating the correct position based on whether it's an arc move, even step move, regular move, etc. MovementCommand should have several methods:

1. MovementCommand(startX, startY, endX, endY, numBeats): (constructor) create a new MovementCommand with the given coordinates, as ints. These are steps from the top left corner of the field, but that fact doesn't matter for the scope of this issue.
2. getStartPosition: Return an object like {x: 2, y:4} that represents the start position of this movement.
3. getEndPosition: Return an object like {x: 2, y:4} that represents the end position of this movement.
4. getBeatDuration: Return the duration of the movement in beats as an int.
5. getAnimationState: Just log "getAnimationState called" for now.

End result: I should be able to create a new MovementCommand, and the getStartPosition and getEndPosition should return the right things. The other methods should log their method name to the console when called, and do nothing else.

Make index.html accessible in the root directory

Can we have an extra step in the build that generates an index.html in the root of the directory, for use with github pages? Github pages looks for index.html in the root of the repo, so we need to have it there. This also means we need to put the build files back in the repo, which is a necessary evil if we want to host this app on github.

Make the "animate" button not disabled by default

It's disabled (striked through) by default for some reason. Who wrote that?

Add dummy viewer and beat files to the repo

Description: Add a dummy viewer file and a dummy beats file to use for testing to the repo under a dummy folder. Optionally, if a tool is used to generate the dummy file, add it to a tools directory.

End result: Dummy viewer and beats files as defined in the spec folder should be present in the repo.

When music is playing, the animate button should stop the music

Grapher should draw tunnel

Blocking this issue: #13 Fixed by #25

Description: We need to be able to draw tunnel as well. The Grapher object should be able to accept "tunnel" as a field type, and draw an svg depiction of the north tunnel from memorial exactly as calchart does.

Implement the AnimationStateDelegate

Issues Blocking This Issue: None

Description: Implement the AnmationStateDelegate: this is an object that the ApplicationController should know about, which keeps track of what stuntsheet and what beat the preview is currently showing, as well as the selected dot label.

The AnimationStateDelegate should implement the following interface

nextBeat()
prevBeat()
nextStuntsheet()
prevStuntsheet()
getCurrentBeatNum()
getCurrentSheetNum()
getShow()
hasNextBeat()
hasPrevBeat()
hasNextStuntsheet()
hasPrevStuntsheet()
getSelectedDot()

*End Result: I should be able to instantiate an AnimationStateDelegate in the console and each of the above methods should behave as expected.

Hook up buttons to work with Show/AnimationStateDelegate

When you click on the buttons, if there is a currently loaded show, it should update and draw the desired sheet/beat.

Grapher should draw field

Blocking this issue: #13

Description: The Grapher object should know how to draw the field (the actual green field with the lines on it). This will involve using d3 to render an svg and append it to the page.

End result: I should be able to instantiate a grapher with field type "college" and call draw, and a field preview should be drawn to the page.

Skipping through beats via the arrow keys sometimes screws up the music

Particularly in the pink show, pressing the right arrow key skips through beats correctly and restarts the music (usually) at the right place, but holding it down sometimes causes the music to stop completely, and you have to click the animate button twice to restart the music (which sometimes also results in the beat being off).

UI should show the current show title

Right now it's hardcoded to relationship show. Who wrote that?

Idea: Links to our Youtube Performances

Just thought of this, and I think it could be cool.
What if the calchart-server could associate youtube links with particular shows? Then there could be a button in the viewer labelled something like "Watch it on Youtube!", which could open, in a new tab, a video of us performing the show that is currently loaded in the app.

Implement MovementCommands: Stand, Mark, and Move

Issues blocking this issue: #6

Description: Implement StandMovementCommand, MarkMovementCommand, MoveMovementCommand. These should take the same constructors, etc as MovementCommand, but should implement getAnimationState correctly (see #6).

An animationState is simply a javascript object (basically a struct) with the following form:

{
    "angle": 40 // in clockwise from straight east (down),
    "x": 47, // in steps from the top left corner of the field
    "y": 28 //in steps from the top left corner of the field
}

End result: I should be able to instantiate stand, mark, and move MovementCommands with start and end positions and they should return the correct values when getAnimationState is called.

Update radio button and file select styles

Right now, they don't look like they do in the mockup from #2. We should apply some tricky styles to these input elements and make them look like that.

Dummy viewer file has incorrect "facing"

The dummy viewer file reports the "facing" of the dots as "north", "south", "east", etc, when in fact according to the specification, they should be numbers which represent degrees.

Grapher skeleton

Blocking this issue: #3

Description: We need some way to draw the "graph" preview of the field and the marchers: this will be handled by the Grapher class. The grapher class should:

1. Accept a field type (string) in the constructor and implement getter and setter methods for the field type
2. Have a draw(Stuntsheet stuntsheet, int currentBeat, String selectedDot) method. For this issue, since this is only a skeleton, we will not implement this method fully, but instead simply have it log a string to the console.
3. Have a member jQuery object which represents the HTML element in which to draw the field.

End result: I should be able to instantiate a new Grapher object in the javascript console and the getters and setters should work properly for field type and the jquery root. Calling draw should result in a string like draw called being logged to the console.

Implement uploading JSON files

Description: Implement the ability to upload files when the "upload file" button is clicked. Don't actually do anything with the upload file, just log its content to the console.

End result: I should be able to click the upload file button in the HTML interface, select a file, and see the file's content printed to the javascript console.

Issues blocking this issue: #2, #3

Design the PDF printout for individual continuities

Issues blocking this issue: None, but this is low priority

Description: We want to implement a PDF printout of the continuity of a selected dot and make this downloadable via the viewer. But first, we need to design how this printout will actually look. That's what we need to do in this issue.

Ideas for database storage of viewer files

@superoven can you get me up to speed on the ideas you talked to @kmdurand about this?

Standard colors

Standard berkeley blue is #003262. This is not the color that the highstepper and the words in the calchart viewer are. We should change that.

Highstepper svg for generating the image is on the wiki.

Launch Calchart Viewer v1.0

Self explanatory. All issues which need to be completed for the launch are in the launch milestone.

Upload mp3 files and have them play

Issues Blocking This Issue: possibly #5

Description: In order to play the show along with music, we need to implement uploading of mp3 files too, and having them play. The audio context should be stored in the ApplicationController.

For this issue, we won't actually sync up the mp3 files with the preview, BUT we'll implement uploading an mp3 file through the mp3 file upload button, and the expected result is that it should just play through on the page. Check out Mozilla's guide to html5 audio and video for more info on exactly how to do this.

Change alert popup to html

#59, #69

Right now, the app will alert the user of an invalid file with a popup box, but we want it to show in the HTML UI somehow.

readme: grunt css:src

Now that the entire build folder is in the gitignore, we should add "grunt css:src" to the build instructions in the readme.

Illustrated description of code architecture

It would be really great if we could get a picture of how all the components of the calchart viewer architecture are supposed to work together. Ideally should have a picture of the UI and a box/arrow chart that describes how ApplicationController, AnimationStateDelegate, etc work together, and what kind of action is triggered by each UI component.

Add chosen for the dot select box

Chosen is great, we use it in members only and berkeleytime. Super easy way to enable search in the select box for dots. We should put it in.

Grapher should draw dots different based on facing angle, whether they're selected

Draw them in white when facing east, blue when facing north/south, gold when facing west, purple if selected