PyJnius to rule them all!

Last time I described how I would be rewriting some of the Plyer facades. I had some confusion about the how to go about this after listening to varying opinions from different Kivy community members. I even had a plan to study the sl4a style of doing things.  But finally after a discussion with  tito [1] and the rest of the group, we decided to drop that approach altogether and stick with using Pyjnius on Android.

In my introductory post to Kivy, I had described the motivation behind the Pyjnius project:

 … a Python module to access Java classes as Python classes using JNI. The idea behind Pyjnius is completely different from other frameworks offering similar functionality of providing device independent access to hardware features. Instead of having to write specific “interface” code using Android SDK to make calls to the device APIs.

Pyjnius let’s you autoclass any of the Java classes and even implement abstract classes that act as API interfaces. To illustrate this with an example, I’ll consider the accelerometer facade in Plyer that I re-worked upon:

Yes, it’s actually as simple as that! You can access any of the Android APIs just by specifying the corresponding Java classes.

Implementing an abstract class takes slightly more effort as you have to declare an interface with the methods that need to be implemented:

Except hashCode, the rest of the portions are quite self-explanatory. Wikipedia has the following to say about the hash code function in Java:

In the Java programming language, every class implicitly or explicitly provides a hashCode() method, which digests the data stored in an instance of the class into a single hash value (a 32-bit signed integer). This hash is used by other code when storing or manipulating the instance …

You would probably want to refer to http://pyjnius.readthedocs.org/, if you are interested in using Pyjnius yourself.

I think after this first accelerometer facade, implementation other similar features (other sensors) would a be a trivial task. I hope to make some good progress on them in the coming week.

Footnotes

  1. I must acknowledge that a most of the content in this post has been derived from this discussion. ^

Mid-Midterm Activities on Kivy

This week I continued our Plyer development. I worked on implementing the accelerometer, gyroscope and magnetometer sensors facades.

Although after a discussion with the community on IRC with tito and tshirtman, we realized that we may need to rework on some of these implementations to avoid the dependencies that we currently have. We intend to completely avoid any Java and Objective C code to access the platform APIs. Instead, we’d let Pyjnius (and Pyobjus) to directly use the classes provided by these operating systems.

But not all was lost. By working on these implementations I was able to have a better understanding of the architecture that we are aiming for and re-writing the specific portions from here would be much easier.

Apart from that, I was able to bring the accelerometer implementation on OS X to a closure. It was quite interesting to be read the sudden motion sensors available on Macbooks (mostly to safeguard the hard-disks) and use it as an accelerometer sensor:

Accelerometer on a Macbook
Using the sudden motion sensor on a Macbook Pro as an accelerometer.

I see that our list of pull requests has grown to a considerable size. In the coming week, I hope to resolve the problems pointed out with some of these and be able to merge them as well.

Kivy Updates from the First Week

As I announced in my previous post, I will be working with the Python Sotware Fundation to contribute towards the Kivy’s Plyer project this summer. And I’ll be posting regular updates about the developments here.

This week, I had to spend a significant amount of time trying to debug this nasty bug in python-for-android. It was critical bug to fix, as it was blocking me to try out kivy apps on Android. After a few blind attempts to tackle this problem by trying to find any missing dependencies or looking for any regression with the Kivy code, we finally narrowed it down to be a P4A issue with the build directories. After long hours of debugging quanon, brousch and I were able to find a temporary work-around for the problem. We should soon expect a fix on this from quanon.

Next, I reviewed some of the Plyer’s pending pull requests about the SMS facade, and providing email support on desktops. I think all four of these PRs are now ready to be merged after a couple of minor changes that I suggested.

Finally, I worked towards implementing the accelerometer facade on MacOSX. While, it happens to be a simple task on Linux, being an awesome OS; it was a bit hacky to do so on Mac by making use of the sudden motion sensors. Currently, we have kept this PR on hold to think about cleaner ways of providing support on different kinds of portable macs. So along with the camera facade, this is the second feature PR on which waiting on better ideas for implementation.

That’s about it from me till the next update!

 

Kivy for all your GUI (or NUI) needs!

I work on projects in the area of intelligent user interfaces. This involves building UI prototypes that run on devices of different shapes, sizes and forms.

I think most of you would agree when I say that Python is one of the best languages  for prototyping anything as a CS student.

More often I have found myself switching back and forth between using Python on my desktop for doing the core part of the project and using mobile specific frameworks for the making the user facing components. For example, I would create partially complete apps on the phone to collect the data on the phone and do all the processing on my desktop. Unfortunately with this approach, you have to dive into understanding the API of the platform you are building for in its “favorite” programming language. It’s even more of a mess when you target your studies on more than one such platform.

What if I tell you that you could do everything in Python and enjoy all of it benefits (read modules ūüôā ) while building cross-platform applications?

Recenty, I was introduced to this library called Kivy:

… an open source Python library for rapid development of applications
that make use of innovative user interfaces

The best part about using Kivy is that your same code runs on Linux, Windows, OS X, Android and iOS.

It also takes care of most of the input devices and has native support for things like multi-touch.

If this sounds interesting, you can check out a couple of kivy examples, talking to people on freenode #Kivy (testified by many as one of the friendliest communities on IRC :D) and following these wonderful introductory videos:

You can also find apps with a variety of innovative user interfaces built by independent developers in the Kivy gallery.

While Kivy provides you with a framework for building apps, it is supported by complementary projects such as PyJnius, PyObjus and Plyer.

PyJnius is a library for accessing Java classes from Python. So instead of trying to build communication layers for each of the API feature of a device, PyJnius on Android (and PyObjus on iOS) lets you access all the device specific APIs on mobile devices. This python code is converted to C using Cython and can be then interfaced with the Android OS using the native development kit (NDK).

But this still needs you to know about different platform APIs and mind the differences between them when you build cross-platform applications.

To solve this problem, we have the Plyer project which gives you a set of common APIs for accessing things like Camera, GPS, Accelerometer and other other sensors; and takes care of making the appropriate PyJnius and PyObjus calls in the background.

This summer, I’ll be working to contribute towards the development of this library. Hopefully as the support for these libraries grows, I would be able to manage my own projects with more ease and also help others in the community who were looking for a solution like this.

Making makefiles for your research code

Edit: This post needs a refresh using modern methods namely, Docker and Kubernetes. I hope to find some time to write a post on them one of these days…

There has been a lot of discussion lately about Reproducibility in computer science [1] . It is a bit disappointing to know that a lot of the research described in recent papers is not reproducible. This is despite that only equipment needed to conduct a good part of these experiments is something that you already have access to. In this study described in the paper here, only about half of the projects could be even built to begin with. And we are not talking about reproducing the same results as yet. So why is it so hard for people who are the leaders in the field to publish code that can be easily compiled? There could be a lot of factors like – lack of incentives, time constraints, maintenance costs etc. that have already been put forward by the folks out there, so I wouldn’t really go into that. This post is about my experiences with building research code. And, I have had my own moments of struggle with them now and then!

One is always concerned about not wasting too much effort on seemingly unproductive tasks while working on a research project. But spending time on preparing proper build scripts could in fact be more efficient when you need to send code to your advisor, collaborate with others, publish it … Plus it makes things easy for your own use. This becomes much more important for research code which often has several different pieces delicately stitched together, just to show the specific point that you are trying to make in your project. There’s no way even you would remember how it worked once you are done with it.

In one of my current projects I have some code from four different sources, all written in¬†different programming languages. My code (like most other projects) builds upon a couple of projects and work done by other people. It certainly doesn’t have to be the way it has been structured right now and it wouldn’t be unacceptable to do so for any other use but a research project. It seemed quite logical to reuse the existing code as much as possible to save time and effort. However, this makes it very hard to compile and run the project when you don’t remember the steps involved in between.

One way to tackle this problem is to write an elaborate readme file. You could even use simple markdown tags to format it nicely as well. But that is not quite elegant enough when used as a substitute for build scripts. You wouldn’t know how many “not-so-obvious” steps you’d skip during documentation. Besides it wouldn’t be as simple as to running a build command to try out the cool thing that you made. A readme on the other hand should carry other important stuff like a short introduction to the code, how to use it and a description of the “two”-step build process that you chose for it.

Luckily this is not a new problem, and generations of programmers have provided us with excellent tools for getting around it. They offer a mechanism to document your readme steps in a very systematic way. And there’s no reason you shouldn’t use them!

One such program that you may already know about is make. Here’s a short and sweet introduction to make by @mattmight. Allow me to take this a little further to demonstrate why these tools are indeed so useful. Let’s start from something simple. A very basic makefile could read something like:

But its advantage seems more clear when you’d like to handle a more complicated scenario. So let’s cook up an example for that; say, I’d like to convert some Python code to C (don’t ask why!) using Cython and then create an executable by compiling the converted C code. Here’s how I’d probably write a makefile for it:

Now the wins are quite obvious. It saves you from remembering such a long build command and also documents the steps you need to follow for building the code. But we still have a couple of issues left if you were to distribute your code. You’d notice that I have hard-coded my python versions as well as the path to the include directories in my makefile. Running this on a different computer would certainly cause problems. One way to handle this is to declare all the variables in the beginning of your make file:

This makes it quite easy for the poor souls using your code to edit the variables according to their configurations. All of the things to change are conveniently located at the top. But wouldn’t it be nice if you could save them from all of this manual labor of finding the right paths for linking libraries, versions of the software installed etc. as well? Reading and understanding your code is already hard enough :D. A shell script could have been quite useful, no?

These awesome people at GNU Autotools have already done the hard work and have given us a bunch of tools just to do exactly what we need here. These tools includes libtool, automake and autoconf to help you create and configure your makefiles.

To write a configure script, you’d first need a configure.ac file. This can be used by the autoconf tool to generate a script to fill the variables in the makefile. Using these tools will make sure that all of your projects have a consistent two-step build process. So that anyone wanting to run your code would have to simply run the configure script followed by make to build your project. No manual tweaking of variables is required during these steps.

There are couple of other helper tools that offer you the luxury of using macros that cut your work further in writing these files. Let us continue with our cython example here.

With just two statements in my configure.ac, I’d be able to create configuration file to fill in my makefile variables:

And to tell what to fill in, I’ll add some placeholder text in my makefile and call it Makefile.in:

At this point I can run autoconf to generate the configure script that would do all the work of figuring out and filling in the variables.

I can even code my own checks here. So let’s add a couple: With my configure script, I’d like to not only assign the path for linking python libraries but also check if the user has all the pre-requisites installed on the system to be able to compile the code. You have an option to prompt the user to install the missing pieces or even start an installation for them. We’ll stop ourselves at just printing a message for the user to do the needful. So let’s go back to our configure.ac.

Here I have added some code to check if cython is available on the user’s machine. Also note that with the AC_PYTHON_DEVEL macro, I am also making sure that the python installed on the user’s machine is newer than version 2.5. You can add more checks here depending on what else is needed for your code to build and run. The best part is that a lot of macros are already available so you don’t have to write them from scratch.

There’s more stuff that you could explore here: alternatives like cmake provide a more cross-platform approach¬†to managing your build processes and also have GUIs to do these steps. A couple of other tools which could handle the configuration portions such as pkg-config exist as well but may not come pre-installed on most OS, unlike make. There are a few language specific project managers that you could also consider (like Rake for Ruby). If you are dealing with a Java project then Ant or Maven are also good candidates. IDEs such as Netbeans create configuration files for them automatically. There are a lot of newer (relatively speaking) projects out there that let you easily package code involving web applications (more on this here) and make them ready for deployment on other machines.

Footnotes

  1. You might also be interested in this article in response to the article raising questions on reproducibility ^

The Story of Digital Color

Earlier this year, I did some work on digital color management for a project. During my readings for the project, I accumulated a lot of interesting articles that I thought I could share.¬†The festive colors around inspired me to finally write about them (and also in case I need to refer them again :D). In this post, I have presented a collection of articles, papers, wikis, comics, podcasts …, that you may refer to find out more about the subject. Let’s then begin our story, starting from all the way back to how we see and perceive colors:

I. The background

Dispersion of light - Prism experiment.
The ‘splitting of white light into seven colors’ experiment. In reality, you see more of a continuous spectrum than the discrete seven colors shown above.

Before we get started on digital color, let’s refresh some¬† high-school science topics. It is kind of mind-boggling to think about it, but the concept of colors is something that you make up in your own head. Fundamentally they are electromagnetic radiation with frequencies in the visible range. Our eye’s retina is layered with mainly two types of photoreceptor cells: the rods (black-and-white vision) and the cones. The cones enable us to see color and are of three types: rho (more sensitive to longer wavelengths), gamma (medium) and beta (short). At this point I would like to introduce you to the applets designed by Prof. Mark Levoy. I’d strongly recommend you to play around with them, at least the ones on the Introduction to color theory page.

Radiation with different wavelengths (or frequencies) excite these color receptors in our eyes to varying levels which is then processed by the brain to give us a perception of seeing color. This phenomenon is known as metamerism or the tri-stimulus response in humans.  Such type of color reproduction is cheaper to process and is easier to control. IA similar technique is also exploited in building displays for our computer screens and mobile phones as well Рthe objects that we cherish the most and spend most of our time staring at. They also use three types of sources to produce all the colors on the display.

There may be differences in how we see the world by adding more types of color receptors. Most men have 3 types of cones (8% have even fewer types and are color-blind), while women can have up-to four due to genetic factors. This Oatmeal comic beautifully illustrates how the number of colors affects color vision in erm.. the Oatmeal way. As a bonus, you also get to find out about how Mantis Shrimp’s vision is powered by technology superior to humans. [1] All of this and the search for a tetra-chromat woman, can be found in this Radiolab podcast on colors.

Now that you understand that the beauty is indeed in the eye, let’s get a little further into the color theory and move on to our next topic.

II. Color Theory Basics

In the previous section, we learned that the illusion of color can be created by three primary colors. Based on this we have two types of color systems:

a) Additive: We add varying quantities of primaries to get other colors. If we are using R, G and B as our primaries: we can have R+G = yellow, R+B = magenta and B+G = cyan. This kind of color mixing is used in digital displays when we have individual sources for each primaries.

b) Subtractive: A paint or ink based medium would follow such a system. It is named so because of the fact that we perceive the color of object as the kind of light that it reflects back, while absorbing the rest of the colors. This can be imagined to be like subtracting color by reflecting it. An example of this system could have Cyan, Magenta and Yellow as the primaries. We also add black to increase contrast and for other practical concerns in the popular CMYK color format.

The other type of system that you may have heard about deals with Hue, Saturation and Value (HSV). These three dimensions are supposed to describe how we actually understand colors:

200px-Munsell-system.svg
Representation of a HSV color system. Hue is depicted as an angle of of the circle, saturation along the radial line and value along the vertical axis through the center.
  1. Hue: name of the color – red, yellow, blue
  2. Saturation:¬† a color’s ‘strength’. A neutral gray would have 0% saturation while saturated, apple red would be 100%. Pink would be an example of something in between – an unsaturated red.
  3. Value: It deals with the intensity of light. You can kind of understand it as seeing colors in dark and bright light. You don’t see any color in very dim environments and also when it is blinding bright.

This color system is more suited for image processing and manipulation uses.

III. Color Spaces

Finally we have arrived at the computer science portion of our discussion. Since computer displays have to process and present all of these different types of colors, we must find a good way to represent them as well. Most color spaces have 3 to 4 components (or channels or dimensions). A complete digital image reproduction system would involve three phases: 1) acquiring the image (say using a camera), 2) transmitting it (saving it in an image format / using an A/V cable etc.) and finally 3) displaying it (on a screen, printing or projecting it). Some color formats are more suited for a particular phase in this system. These color spaces would be based on one of the color systems that we learned about in the section above.

The simplest of the color spaces would be a Gray color space. It only has a single channel with values varying from black to white. The common 3-channel color space families are:

RGB family: These are mainly used in displays and scanners. Members of this family included sRGB, Adobe RGB color formats etc. These formats are defined by international standards defined by various organizations.

YUV / YCbCr / YCC family: These are the most unintuitive types of color spaces. They were designed keeping in mind the transmission efficiency and for efficient storing.

Device Independent Colors:¬†All the colors spaces that we have discussed till now may produced varied results on different output devices unless calibrated. Different devices have different ranges of colors that they can produce. [2] As a result they are called device dependent colors. To counter this, some clever folks at CIE developed imaginary color formats (although not useful for any making output devices [3] ) that specify color as perceived by a ‘standard’ human. Examples of these colors spaces include CIE XYZ, L*a*b and L*u*v.

The Apple developer article on color management is a good source to read more on this topic.

IV. Color Display: Techniques and Terminologies

Now that we have covered most of the basic stuff. Let’s talk about the other common terms in brief that you may have encountered about color reproduction.

  • Color Depth and Bits per pixel (BPP)
    These parameters define the number of bits used to define a single pixel’s color. If you are using 8 bit color, you will use 3 bits (or 8 levels) for R & G and 2 for B. This is assuming that your 3 channels are red, green and blue. Similary you can have other color depths like 16-bit and 24-bit (True color) which can represent 256 shades of red, green and blue. Modern displays support something known as deep color (up to 64-bit) with gamut comprising of a billion or more colors. Although our human eye can not distinguish between so many colors, we need this bigger gamuts for high dynamic range imaging. This also affects image perception by the humans as we do perceive red, green and blue in equal capacities. So even though we may be producing more colors on the screen, we may not have sufficient number of shades for the colors we are more sensitive to. Having a larger gamut takes care of all those shades to which our eyescan distinguish but need more information in order to be represented in the digital space.
  • Color Temperature
    Color temperature is derived from the color of radiation emitted by a black body when heated to a particular temperature. Hence, it is commonly specified in units of Kelvin. Our main interest here is adjusting the white point or the chromaticity of the color reproduced by equal red, green and blue components in an output device. This allows us to adjust the colors appear “warmer” or “cooler”.
  • Dynamic Range and Quantization
    You may have heard about the newer camera phones having an HDR mode. These phones are able to process a photograph so that it can have both clear shadows and also brighter regions in the frame. The dynamic range of the image is what they are referring to here. Dynamic range is the ratio of the brightest to the darkest light levels. These levels are quantized into several intensity levels in this range. An 8-bit device would have 256 such intensity levels.
  • Gamma
    Gamma
    We are able to better distinguish between colors intensities at lower levels.

    Our eye is sensitive to the various intensities of colors in a non-linear or power relationship. This allows us to see clearly both indoors (or at night) and outdoors in bright daylight. [4] This leads us to have something known as gamma correction in computer graphics.¬† You can map the linear levels of your images to a curve of your choice. This must be done according to the characteristics of the output device like the monitor. When you adjust the brightness, contrast or gamma settings on your display, you are essentially manipulating this curve. This GPU Gems article from the Nvidia’s Developer zone tells you more about Gamma that you need to know.¬† I think, I’ll probably stop here but this topic probably deserves more space than a short paragraph. There are a couple of excellent articles by Charles Poynton on this such as The Rehabilitation of Gamma and the Gamma FAQ.

  • Dithering
    Our eyes tends to smear adjacent pixel colors together. This phenomenon is exploited to simulated higher color depth images than what that could be supported by an output device or possible in an image format. You can see some examples of dithering here. In another type of dithering known as temporal dithering, colors are changed in consecutive frames to create a similar illusion.

V. The sRGB color format

Although now a bit dated, most of the consumer devices still use sRGB as the default color spaces. When you see sRGB content on compatible devices, you will enjoy the same colors. You can find out more about what goes into making a standard color space here:¬†http://www.w3.org/Graphics/Color/sRGB.html. After reading about the fundamentals of digital color, I hope that you’d have a good understanding of how to read a specification like that.

This is a very short post considering the breadth of topics that it deals with. I have tried to highlight the human factors that influenced the development of color theory and technologies throughout this post. They sure were able to piqu√© my curiosity to find out more. I hope that you’d also like this collection of resources to read about color. I would be glad if you could point out any errors and typos here.

Image Credits: Munsell System. © 2007, Jacob Rus

Footnotes

  1. Update: Study reveals that Mantis shrimp uses color to communicate! http://www.livescience.com/42797-mantis-shrimp-sees-color.html?cmpid=514636 ^
  2. More info here: http://graphics.stanford.edu/courses/cs178-10/applets/colormatching.html ^
  3. Device independent colors are useful for studying the color theory. They are also used as intermediaries when converting between different colors spaces. ^
  4. This could be similar to other psychometric curves: http://en.wikipedia.org/wiki/Psychometric_function ^

The Stroop Test

The Stroop task is among the popular research tools used in experimental psychology. It involves creating a conflict situation using words and colors. The original experiment was conducted by John Ridley Stroop way back in 1935. The participants are asked to do an oral reading of color words – like “red“, “green“, “blue” etc. in these tasks. In his first experiment, Stroop compared the reading times of words in two conditions: a) the neutral condition: words are presented in a normal black ink on a white background; and b) Incongruent condition: having incompatible color combinations e.g. “red“. It was during his second experiment that he found the reading times were much faster when using colored rectangles as compared to incongruent color-word combinations.

Other Stroop paradigms have also compared incongruent with congruent conditions. The Wikipedia article on the subject summarizes their results:

Three experimental findings are recurrently found in Stroop experiments:

  1. A first finding is semantic interference, which states that naming the ink color of neutral stimuli (e.g. when the ink color and word do not interfere with each other) is faster than in incongruent conditions. It is called semantic interference since it is usually accepted that the relationship in meaning between ink color and word is at the root of the interference.
  2. Semantic facilitation, explains the finding that naming the ink of congruent stimuli is faster (e.g. when the ink color and the word match) than when neutral stimuli are present (e.g. when the ink is black, but the word describes a color).
  3. The third finding is that both semantic interference and facilitation disappear when the task consists of reading the word instead of naming the ink. It has been sometimes called Stroop asynchrony, and has been explained by a reduced automatization when naming colors compared to reading words.

I needed a mobile (Yay, HTML5!) Stroop task as one my experiments in a class project. First, I tried using the Google Speech API but it was failing to recognize my own speech inputs, so I resorted to using regular buttons instead. I also wanted to vary the difficulty of the task, so I added an option of adding more color variations (More buttons, more targets, Fitts’ law …). Here’s what I could come up with in a couple of hours: