Category Archives: open source

open source

End of Summer – Thank you!

This summer was a big one at for CDOT (Centre for Development of Open Technology).  We had almost 30 RA’s working on many many different types of project.  Yesterday was our final cdot presentation day for the summer.

For those unfamiliar, CDOT is an applied research group within Seneca College.  Over the years we have worked on many different projects related to open technology in various areas.  I am one of the faculty members involved with CDOT.  Projects tend to run over the course of a semester or two.  Students are hired either while they are studying or just after they graduate.

My team worked on projects related to 3D web graphics.  This summer I had two projects.  The first was a project with Box, to implement a 3D data visualization tool.  The second was with a Gorilla Productions.  The project was to implement realistic cameras for three.js.  (cameras that behave as real world cameras do).  In total I had 4 awesome research assistants working for me (Andrii, Barbara, Dmitry and Koji).  They have done a fantastic job on their projects.

However, aside from my two projects, CDOT also hosted many other projects.  One of the reasons the reasons that CDOT exists is to provide experiential learning opportunities to our students.  A chance for them to work on real projects and develop skills.  One of those skills is the ability to talk about their work.  Thus, each Thursday was we have “Demos”.  During that time, the teams will talk about their project and what they have been working on, problems they encountered, solutions they found.  Yesterday, was the last day and everyone had a chance to talk about thoughts of on their summer’s work.

Generally the comments were all very positive. However, there did seem to be a few themes that were shared by multiple students.  These were:

  1. Being surrounded by other very smart people working on interesting projects has helped them develop as programmers
  2. Demo days helped them learn from other teams even when they were not working on remotely the same thing.
  3. Demo days made them less nervous about speaking in front of crowds
  4. CDOT provided opportunities to work on something important with a great amount of freedom to design and implement their work
  5. CDOT experience has helped them to either find a job (a couple of students will start in new positions right after labour day) or the confidence that they will be able to find one shortly.

I truly believe that CDOT is one of those places that are unique and special.  We have students that do very interesting work on a wide variety of projects.  Our students are very bright, and I have always admired their ability to exceed my expectation.  Many of you have taught me things I did not know.  To all the RA’s at CDOT, know that you are the ones that make CDOT special.  When I see what you do, when I see what you have accomplished, I am reminded of why I teach.   Thank you!

Using git and github in your classroom

I wrote this for the ACSE mailing list about year ago and have passed it onto my colleague when they ask about using github for their classroom.  At the encouragement of another colleague, David Humphrey (he did a really good talk on git and github for fsoss2015),I’m going to post it to my blog to make it more accessible.

Using git and github for your classes

Firstly it is important to distinguish between git and github.

git is the open source distributed revision control system used by the Linux project. It lets you create a history of all your code.  You can send git repository around as zip files if you like.

github is a company that creates a nice place for you to put these repositories into the cloud so that you can much more easily sync and share these repositories without having to set up servers or send around giant archives.  It also provides things like access control, issue tracking, wikis, activity graphs and so on.  Very handy.

As this post is long, I’ll start with some links for quick reference on where to find/get stuff.  After that I have a section specifically for dealing with github, working together and git itself.

git client download: http://git-scm.com/downloads
git tutorial: https://try.github.io/levels/1/challenges/1
github gui: https://help.github.com/articles/set-up-git
tortoise git: http://code.google.com/p/tortoisegit/

About Github

github  has 2 types of accounts: individual and organization.
As a teacher, will need to make for yourself an individual account and an organization account.  Any individual account can belong to zero or more organizations.  For myself, I have quite a few different organization accounts.  One for each of my courses and one for my research group.

It should be noted that both types of accounts are free to use if your repositories are open source.  I have been using github as a place to put my in-class examples for students…and that is open source so I don’t have to pay for doing that…you can check out the repo for my data structures and algorithms course here.  I use the repository itself for code examples, the wiki for assignments and course documents (minus the notes… I prefer gitbooks for that).  I have not yet tried to do this consistently but I think the issue tracker in this case can also serve as a notification and discussion board.  You can check out the repo here:

http://github.com/cathyatseneca/dsa555-w15
github makes money by essentially charging for privacy so under normal circumstances they would charge some amount for some number of private repositories.   You can see their pricing plans here:  https://github.com/pricing

However, as an educator, what you can do is request for an organization account with X number of private repositories at some discount.    You can do so at this site:

https://education.github.com/

Typically they will want info about your school, number of students and so on.  The number of private repositories depends on how many students and how you plan to use the repositories.  So for example, if you have 20 students and they work in groups of 4, then you will need 5 private repositories.  However, if you have 20 students and they are working individually you will want 20 private repositories.   If you want both team and individual repos for some group work and some individual work, then you would need 25.    I also suggest asking for a couple of extras for yourself or for class material that you don’t want to open source.  In any case what you want to do is set it up so that your organization can have some number of private repositories that will suit your needs.

Aside from you setting up an account, your students must each individually create a github account.  Once that is done, have them send you their github ids.  They can get a free one.  They don’t need to pay for it as the private repos will be given to them through the your organization account.

Once you have created your organization, you can go to your organization settings and create teams.  A team consist of 1 or more individual.  As the administrator of the organization you will be able to see all the repos so if you forget to add yourself its no big deal.  Each team also has different access permissions.  Typically I would set up a student team for write access but not admin access.  If you are only planning on doing group work then set up each team so that all members are part of that group.  If you plan to do individual work or a mix of team and individual work then you will want to set up a team for each student.

Once you have the teams set, you can then create private repositories.  You can initialize them with an empty readme (or push some code up by following the instructions).  In any case once you have created those repos, you can give access to 1 or more “teams”  by hitting the collaborator button in the settings tab.
Only teams with access to private repos can see that repo.  So its a great way for groups to all contribute to a project because you can limit who sees what.  As a teacher, if each student actually submits their own stuff (and not email around and have one person do it) you can actually see their commits down to the line they put in through the blame button.

About collaboration

Getting students to unlearn the code collaboration method they had been working with for years is a definite challenge.  Putting in some best practices may be a good idea.  Here is something I wrote up for the students in my research team to help them do this:

To ensure that we are not going to step all over each others code, these are the steps we will use when putting code into  the repository:

  1. All commits should be accompanied by an issue. If there is no issue for your commit, please make one first!
  2. All commits should be put into a branch matching the issue number. Thus, if the problem the code is solving is described in issue 2, then the branch should be named issue2
  3. before pushing your code to github make sure you merge in the most recent code on master to your branch and resolve any conflicts
  4. push your code into the remote issue branch (if you want to work off your own fork then thats fine but issue branch on your fork)
  5. submit a pull request for the code that you have submitted but DO NOT merge that code yourself.
  6. assign someone else to review your pull request
  7. if you are assigned a pull request, test out the pull request on your local machine BEFORE accepting it. Do not just click the button. If there are any problems, comment and let the submitter know and have them fix it. If all goes well accept the pull request to merge into master

There are other methods out there… but you probably will need to invest some time to teach whatever that method is.

About git and git clients

git is a revision control system and it is part of all linux distributions so if you are running linux, you already have git installed (unless it is a really really old linux release).  For OSX git is installed as part of command line tools for xcode (if I remember correctly… on mavericks the first time I tried to type git at the command prompt, it installed those tools for me).  For windows, you can download it from:  http://git-scm.com/downloads

The above are command line tools for using git… and this is all you need for git and github.

You can learn to use git with this interactive tutorial: https://try.github.io/levels/1/challenges/1

Everyone tells me that gui’s are awesome… so github does provide some fancy gui clients for git (https://help.github.com/articles/set-up-git
).

Tortoise git is what one of my student use to swear by… so that may be worth looking at (http://code.google.com/p/tortoisegit/)

I tend to prefer the command line myself so I can’t speak to either unfortunately.

Anyhow, hope this is useful to others trying to figure this out.  Let me know what would make this even more useful for you

Fixing My Processing.js Data Structure Animations

Over the holidays, I spent some time fixing some code for a processing.js data structures and algorithms animation project that I had been working on.  Check out the results here:

Now, a bit of a story about the code.  About 2 years ago, I wrote some code to do some animations of sorting algorithms while I was learning Processing.js.  The idea was to build a library of these animations that my students can use as reference. I wanted to add animations for all the data structures and algorithms we covered in my data structures class. Although I was able to implement two simple sorts using my previous code, I had quite quickly realized that there were two big flaws in the way I had designed my code.  The first is that the animations were frame based.  I basically went and changed the frame rate in my sketch to get the animation to play at the speed I wanted… not a good idea but it was something that was easy to code with pjs so I had done it that way. The bigger problem however was that I had written a state transitioning mess of a program.

The way that Processing works is that there is a single draw() function that is repeatedly called to produce an animation.  The way that I have coded my animation was to have different states for each of my objects and depending on what I wanted to show, I would modify the state of that object.  So if the array was swapping the values of two elements, the array object would be in a swapping state. The drawing and animation was pretty simple.  Change the state, change what animation to play. However, when it came time to code the actual sort animations though, I realized I had a problem.  Translating the procedural sorts into a series of state transitions of the various animation objects was difficult to do.  When completed the animation code was a big mess and does not in any way resemble the sorting algorithm. For example here is the original mess that drew the bubble sort animation (don’t cringe too much… it was a first attempt :P)

  void draw(){
    if(!sorted_){
      if(array_.state()==array_.STABLE){
        if(array_.atIdx(currJ_)>array_.atIdx(currJ_+1)){
          src_.setHighLighter(7);
          array_.setLetterColour(currJ_,#ff0000);
          array_.setLetterColour(currJ_+1,#ff0000);
          array_.swap(currJ_,currJ_+1);
        }
        if(array_.state()==array_.STABLE){
          src_.setHighLighter(6);
          array_.setLetterColour(currJ_+1,#000000);
          array_.setLetterColour(currJ_,#000000);
          currJ_++;

          array_.changeIndicator(0,currJ_);
          array_.changeIndicator(1,currJ_+1);
          if(currJ_ >= sortLength_){
            src_.setHighLighter(4);
            currJ_=0;
            array_.changeIndicator(0,currJ_);
            array_.changeIndicator(1,currJ_+1);
            sortLength_--;
            if(sortLength_==0){
              sorted_=true;
              src_.setHighLighter(11);
            }
          }
          array_.setSplitterPosition(sortLength_+1);
        }
      }
    }
    else{
      array_.setSplitterPosition(0);
    }
    array_.draw();
    src_.draw();
  }

As you can see it does not in any way resemble a bubble sort… no loops, just a nasty series of state transitions. After completing the animation for bubble and insertion I posted my code to github and just left it as is… I always wanting to go back to add more but the thought of translating something more complicated into that mess made my head hurt.

Sometime in the fall I was talking with my friend Phil about the mess I made with my code and trying to think of a way to fix it or possibly even rewriting it. He pointed out that what I needed was really an animation system… something that you can record and play back. Essentially the idea is that you would run through a standard algorithm as is on some given piece of data. During the process of running through the algorithm, the system would “record” the states the animation objects should go through. Displaying the animation was simply playing back the recorded steps. My new design involves 3 new objects (they are not yet complete .. but complete enough for sorting algorithms).

  • Animation step – one discrete step in an animation. I wanted a way to allow for the ability to step through an algorithm. Each step may involve modifying multiple objects or even modifying one object in more than one way but it is taken as one whole step.
  • Animation Instruction – an instruction sent to an object that changes the object’s state in some way… The way it is currently implemented is a series of instructions represented by a constant, and parameters to the instructions which are all done as integers. Its not the best way to do this… but for now it works.
  • Animation – contains a list of animation objects (things that are drawn), and a list of animation steps.

In any case… this method works. Here is the function that creates the bubble sort animation:

void bubble(int array[],int sz){
    int i,j;
    int tmp;
    for(i=0;i<sz-1;i++){
        bubbleSort.addStep();
        bubbleSort.addInstruction(0,SET,4);
        for(j=0;j array[j+1]){
                bubbleSort.addStep();
                bubbleSort.addInstruction(1,SETFONTCOLOUR,j,255,0,0);
                bubbleSort.addInstruction(1,SETFONTCOLOUR,j+1,255,0,0);
                bubbleSort.addStep();
                bubbleSort.addInstruction(0,SET,7);
                bubbleSort.addInstruction(1,SWAP,j,j+1);
                tmp=array[j];
                array[j]=array[j+1];
                array[j+1]=tmp;
                bubbleSort.addStep();
                bubbleSort.addInstruction(1,SETFONTCOLOUR,j,0,0,0);
                bubbleSort.addInstruction(1,SETFONTCOLOUR,j+1,0,0,0);
            }
        }
        bubbleSort.addStep();
        bubbleSort.addInstruction(2,SET,15-(i+1));
    }
    bubbleSort.addStep();
    bubbleSort.addInstruction(2,SET,0);
    bubbleSort.addInstruction(0,SET,0);
}

You can actually see the bubble sort algorithm in here… the animation steps and animation instructions are simply like “print” functions except that they state what should be drawn instead. Each of the addInstruction() calls passes in the index of the animation object to modify and the instruction (SET, SETFONTCOLOUR, etc.) and parameters of the instructions. its not perfect but its way better than the original.  The animation has also been fixed to be time based.  Furthermore, while it is not currently implemented,  it will be possible to allow a step through of the animation also.

I have updated both animations for insertion and bubble sort using this new animation system.  I have also implemented the animation of selection sort and quicksort.  Both were not really hard to do (though I admit that I would want to tweak the quick sort a bit as it isn’t quite as accurate as I would like). Hopefully others will find these animations useful.  Let me know if there is an error or something that is unclear with how the animation is done.

Giving a Processing.js Workshop

Last Friday, I gave a workshop on Processing.js.  This workshop was aimed at girls of around 15 years of age with little to no programming background.  The challenge for this workshop was the very limited amount of time that was available (40 minutes).  I  thought I would write about my experience giving it and some changes that I would make the next time I did it.  If you are interested in the material I made for the workshop, its all on github and you can get it here.  Note that I will be making changes to it in the next few days(see below)

What I wanted to do was something cool that could be done in 40 min with girls who may not have done any programming.  I was given a lab with standard equipment (which did not include the Processing IDE).  There were two options for doing a workshop like this.  I could start from scratch or I could start with something that could be built on.  I decided on the latter because I thought being able to get something that looked really cool was important.  In the past I have helped with workshops for the same age/gender group and what I learned was that starting from scratch, not much would get done.   For most programmers,  tasks like putting together a simple web page or writing a simple script is easy even if we have never used a particular language. It is far too easy for us to underestimate how much time it would take for someone to be able to write a simple program.   Programming requires a certain amount of discipline.  Even languages like Processing which were designed to be easily accessible requires a certain syntactic awareness (spelling, capitalization, placement of ;’s and }  etc.) and all too often it is easy to make simple typos.  As we were using a plain text editor, knowing how to find syntax errors by sight was also important.  I also felt that you wanted to have a very specific goal.  “make a web page” or “make an animation” is too broad. Even something as simple as search for an image to put into a page would eat away at that time all too easily.

Thus, I decided that I wanted to have a very clear goal on what they will get when they finished.  I decided to have them put together an animated picture frame (essentially a slide show with an animated background).   The idea was simple to understand and it was clear what the goal was.  I got some photos to put into the album from my friends Raymond Wong and Samson Chan who had picked up photography as a hobby.  I wanted pictures that were pretty and fairly neutral in topic and both had recently taken pictures at various gardens and flower shows.

I then wrote a bunch of classes that would animate various objects.  In the end I had the following collection:

  • polkadots   – a circle that moves around the page
  • triangles – a triangle that moves around the page and spins
  • fireworks – essentially exploding set of particles
  • flowers – a flower shape that floats downwards
  • poem – lines of text that would be drawn diagonally downwards.

Most of these were created with random values for things like colors and positions by default.  These values could be changed via functions but could also be left alone. The picture frame could then be created by simply instantiating a bunch of these objects and drawing them in the draw() function.

My intial plan was to have a picture frame already done and have the students change things like colour of the flowers and so on.  You can see what I had thought would be a good starting point by looking here.    As a programmer, what I had done was of course create a sketch with an array of random polkadots/triangles/flowers/fireworks some text.  I handled all the initialization and drawing with loops.  The animation is busy which is ok because that is one of the things we could change.

However on the way to workshop this morning I started thinking some more about this… and I realized that I had made the mistake of being overly complex.  I was not keeping it simple because to understand something like arrays and loops took an extra step in the understanding of how programs work.   Its not necessarily hard to explain these but in 40 min, this was maybe a bit too much to ask.  Therefore in the last minute, I decided to change the main sketch.  Instead of starting with the kitchen sink, I decided to start off with a simple sketch that only ran through all the pictures. (essentially erased all but 5 lines of code.  This turned out to work pretty well and the feedback seemed positive (I’ll have to check the official feedback later 🙂 ). The students were able to add single instances of the different objects and modify things like colour or number of petals on the flowers and so on.

Here are some changes that I would make to make this workshop run smoother next time.

  • change the text that was the default text for the “poem” class (going for the code poets theme… I had used a version of the initial main sketch source as the text) and that looks very confusing for the students to change because it looked like code.
  • change the way that text was added (separate the data from the code more… currently its all part of add() statements).  It would be better if I had declared a bunch of strings or read the text in from a file because that would have made it easier for the students to modify the text
  • don’t mix american and canadian spelling of the word “colour”.  I had named all the functions to change colours on the objects setColour().  unfortunately I made the mistake of having the function take color as the argument.  Thus to call the function, the students would have to write:  obj.setColour(color(…));   The different spellings make it extra confusing.  The better approach would be to have the object just take 4 floats and set the colour inside the function

Mostly the changes are not difficult to make and I will be making them over the course of the next week.  I will also update the workshop instruction document to match the changes.

GJK Explained

A friend of mine has been writing an article that explains the GJK (GIlbert-Johnson-Keerthi) algorithm for collision testing.  His goal is to write something that comes at it from a geometric approach in the hopes to make it more understandable as he finds that many of the other explanations are far too convoluted to follow.  If you are interested in collision detection and how to test it easily you should check it out.  He would love to get some feedback on whether what he wrote is easy to understand and how things could be clarified.

You can find it here:  http://phill.vec3.net/gjk

Creating Data Structure Animations with Processing.js

Ever since I saw the first demonstration of Processing.js I have wanted to do something with it.  I teach a data structures and algorithms course and one of the annoying things I have found is that many of the animations for showing how these structures work were written in Java and put on a web page as an applet.  Many of these animations are also just broken.   Thus as a response I thought it would be a good idea to put together a set of algorithms animations that didn’t need any plugins.

I started putting together a small bubble sort animation about a year ago.  I liked the way the way the final animation looked but I didn’t like the way the code looked and felt.  It was really hacky and not very good.  Definitely not extendible for other algorithms.  About a week ago I decided to restart that effort.  I thought about what would actually be necessary to do general algorithms and data structure animations.  I rewrote the code (you can get it here: https://github.com/cathyatseneca/DSAnim ).  Currently the code animations are pure Processing sketches (I didn’t stick any bits of JS in my sketch this time :P).  However that might change later when I try to add in controls.  You can check it out live here:

https://cs.senecac.on.ca/~catherine.leung/sketches/index.html

When I was putting these animations together, one of the things that I had trouble with was translating the algorithms into animations. Processing works by repeatedly calling a draw() function in which you tell it what to draw in the next frame.  In other words there is a sort of built in loop.  While it is possible to call a function for some algorithm (a sort for example) within the draw loop, you can’t really animate it just by calling it as it will be called each frame and what you want is to animate steps within the function.

I admit that I’m very new to Processing.  Thus, this may not be the best way to do this (if anyone has suggestions please let me know!)  The design I settled on in the end was to create a general array animation. The array has a single draw function that the main draw loop will call.  Depending on the state of the array, the array’s draw() function will animate one frame of what is going on (one frame of a swap for example).

The array has states which determines what to draw.   Currently the array has these functionalities:

  • moves (move number from one element to another)
  • swaps (swaps two values in array)
  • stable (nothing is happening)
  • move to temp (move number to a temporary location out of array)
  • move from temp (move number from temporary location to array)

The object also has indicators and a splitter bar that you can add to your animation. You can also change the colour of the text in the array.

So far I have completed the bubble and insertion sorts.  I think I will need to add more functionality to properly show merge sort.  I have not yet really thought too much about a quick sort.  After the sorts I will probably start looking to add trees and lists.  I am hoping to also add animations for other data structures as well.  The code is far from perfect but it looks neat and for now that will have to do :).

Firefox 4 release!

Firefox 4 is being released today and with it the realization of a promise made long ago.  It has been more than 4 years ago when we started our project on providing a JavaScript library c3dl.  It was named after Canvas3D the precursor to WebGL.  For those of you not familiar with WebGL, it essentially allows you to use hardware accelerated graphics in the web browser using OpenGL ES 2.0 api in JavaScript.

TL;DR version: fast 3D graphics in the browser!.

When we first started c3DL, Canvas3D was a plug-in (which was really odd because the whole idea was to be able to do 3D graphics in the web page without any plug-ins).  I remember explaining to people how Canvas3D will let people do 3D graphics in the browser without any addons…and that if they wanted to check it out they should go and download the addon for it.  We had tutorials on how to get the right browser, how to install the add-on how and test if you did everything correctly.   Even in pre-release versions of Firefox 4, WebGL had to be enabled in about:config.  Finally today WebGL just comes shipped with the browser.  All the things we have been working on are now viewable without plug-ins or changing any settings.  With Firefox 4’s release the number of browsers there are 2 browsers that come WebGL enabled.

Firefox 4 did more than just turn on a switch for WebGL.  It also came with some crazy enhancements to their JavaScript engine.  When c3DL first started, our first demo consisted of 4 spinning cubes.  It was really really boring.  However, one of the really odd things about it was that after a few seconds of spinning it would have this noticeable pause.  Basically a garbage collection pause.  Today this is gone for the most part.  The graphics made with WebGL has frame rates.

What to do with your shiny new browser:

sooo… now that you have got your new firefox 4 browser, what is there to do?  What is there to check out?  Here are some demos.  It is admittedly Seneca-centric featuring work developed by staff and students at Seneca.