I found a bug! What do I do now?
While we strive for the ultimate goal of bug-free software, bugs do happen unfortunately. If you run into a bug, here are some steps to help resolve the problem.
First, if you are using an older version of SimpleCV, please upgrade to the latest version of SimpleCV. The bug you ran into might be something that was already reported and fixed in a later release.
If you are using the latest version of SimpleCV, and you are still having issues, the next step is to file a bug ticket on GitHub. To fix your bug, we will first need to replicate it, so please make sure you include as much information as possible in your bug ticket. If you could please include the offending code and/or any images, that would be very helpful. Also, if you let us know what platform and hardware (camera) you are using, that will also be very helpful for us when we try to replication the problem.
Once you have submitted a ticket, we will try to replicate the problem and find a solution as quickly as we can. Be forewarned that it might take us a little while to replicate the problem, since that can sometimes be tricky. With that in mind, if you have debugging skills and want a speedy solition, the fastest answer might be to look under the hood yourself and tinker with it a bit.
I fixed a bug! What do I do now?
First: you rule! Pat yourself on the back for supporting an Open Source project. To patch your bug, we need you to put together a good pull request. Once you have your pull request put together, fire it off. If it is put together correctly we should be able to merge it into the main repository really quickly.
Is this a bug or am I doing something wrong?
This is a great question! Not everything is a bug. The best place to find out if you are doing something wrong is to look at our documentation and example code. If you are still having problems the next best resource is our support forum. We check the help forum just about every day.
If you are working with a method that has a couple of parameters, try tweaking the parameters a little bit. Sometimes degenerate image cases can cause methods to blow up. Also make sure all of the inputs to your method are correct. The SimpleCV shell is a good tool for this. If you are still having problems you should submit a bug ticket on GitHub.
I found a bug, but it is mainly a SciPy/Numpy/Pygame/OpenCV issue. What should I do?
SimpleCV is a melting pot of different libraries, and sometimes one of the libraries it depends on has some problems. We try to fix these problems in two ways. First, we try to get to the root of the problem by working with the library authors to help squish their bugs. If there's an issue with fixing it at the source, and it's a signifiant enough issue, then we try to create a patch that at least prevents the bug from happening in SimpleCV.
Here is what you can do to help:
1. First, make sure what you have is a bug. We're all users, and we've all made user errors. They happen. The support staff and software developers of the world will shower praise upon you, though, if before you say something is a bug, you check to make sure it's not a user error issue.
2. If you think it really is a bug, then submit a bug notice to the offending library. Here are links for where you can submit bugs:
- NumPy: http://projects.scipy.org/numpy
- SciPy: http://projects.scipy.org/scipy
- OpenCV: http://code.opencv.org/projects/opencv/issues
- PyGame: http://www.pygame.org
3. Then also submit a ticket to us. Please include a link to the ticket you filed with the other library, so we can more easily coordinate with them about the issue.
Depending on how bad the bug is, we may try to create a temporary patch in it for SimpleCV.
Hey guys - have you seen this totally sweet library?
We might already know of it, but send it to us anyway. If it is open source and can help SimpleCV, we'd love to hear about it. You can also file a new ticket on GitHub saying something like, “look into supporting library X.” We’ll gladly look into it.
This thing works but it is like totally slow. What do we do?
SimpleCV isn’t always the fastest library, although we are always trying to increase the performance. If you are having run-time speed problems, we'll try to help you out. A lot of speed issues can be solved by adding some 1337 sp33d hax (which usually involves making your image smaller). The help forum is a great place to ask questions about speeding up an operation. If you've tried these types of things, and are still having problems, we suggest you file a ticket on GitHub.
I have/had an installation issue, how do we fix it?
We're sorry you ran into a problem! A good first step is to look and see if your installation issue has been solved on the help forum. If this doesn’t help, and you are trying to install from the superpack, the first thing we suggest is that you try and install SimpleCV from source. The directions for installing from source can be found here. If you are still having problems, try asking a question on the help forum. Generally, installation issues will be solved faster using the help forum versus submitting a GitHub ticket.
I want a feature/change/extension/pony. How do I request it?
The short answer is to file a feature request on GitHub. In general, your feature request should include example applications, images, and code which can help us solve a problem. If you have a data set that we can use to tackle the problem, even better. A good feature request tells us what you want to do, why you want to do, how the code should look, and how we will know when it is working correctly.
I have a feature/change/extension/pony I want to submit. How do I give back?
Great! Thanks for helping out! To submit code you should wrap your new feature up into a pull request and send it to us. In general, we prefer pull requests that are well formed and ready to go. For help with this, please see our answer on how to create a good pull request.
I have some spare time. How can I help out?
The first step to helping out is contacting us. The best way to get in touch is by using the help forum, or you can try twitter. We can discuss what tickets are outstanding, and find you a few that should be fun to solve. Once you solve the ticket, put together a good pull request and we can merge it back in to the main repository.
I am a student, and I'd like to help. What can I do?
Not to sound like your mom, but during the school year it is best that you focus on your studies. If you want to use SimpleCV for school, though, we would be more than happy to help you out. Just get in touch with us by using the help forum. If you want to ignore our advice, then you still want to get in touch with us so we can talk about what issues you might want to work on. If you would like to sponsor a SimpleCV class at your school, we would also be interested in helping you out. First step? You guessed it. Get in touch with us using the help forum.
During the summers, SimpleCV also participates in Google Summer of Code, and every year we take a few summer interns. Details come out every March. For more information, please see our Summer of Code page.
I want to learn more. How can I help out?
If you want to learn how to use SimpleCV, and help us out at the same time, we suggest that you start out by writing a short example program. Nothing too fancy, perhaps a couple of hundred lines of code solving a practical problem you have. This example program can use one of our existing examples as a template, and go from there. A good place to find ideas for a program is to look at the features that we have added to the repository.
I wrote this totally cool thing in SimpleCV. Do you guys want to feature it?
YES! We are working on a featured projects page. Please tweet at us (@Simple_CV) and we’ll be in touch.
I have a video of my SimpleCV project. Would you want to feature it?
Again: YES! You can tweet at us (@Simple_CV) or let us know in the help forum.
I wrote this code for work/school/fun, but it is in (some language). Can you use it?
The short answer is maybe. Let us know about it in the help forum, and we’ll set up a time to chat.
I work on another FOSS project, and we want to collaborate. Are you interested?
We totally love collaboration. We are particularly interested if your project needs help creating python bindings that will play well with SimpleCV. Please let us know in the help forum, or tweet at us (@Simple_CV), and we’ll be in touch.
I work at an academic research lab and I would like to collaborate. Are you interested?
Awesome! We are always looking for collaborators. If you want to just use SimpleCV, go to town, but please drop us a note in the help forum. If you need some assistance with your research, we can help you out. For example, we can arrange to do a short tutorial for your research group, or set up a meeting where we can organize a way for you to contribute to the library.
I'm an educator, and want some course materials using SimpleCV. Can you lend me a hand?
Absolutely! We are working very hard to create education course work for SimpleCV and Python. Please drop us a note in the help forum, and we’ll go from there. We should be able to provide you with slides, problems, example code and demos, and bulk discounts to our book.
Can I hire you to help me solve this problem?
I am a manufacturer. How do I use SimpleCV on my assembly line?
Sight Machine is very interested in helping to solve manufacturing problems. You can get in touch by using the Sight Machine contact form. They'll get in touch with you to discuss your problem, and outline ways that SimpleCV might help.
I wrote this application specific package. Where does it go?
You should submit a pull request to GitHub, and we’ll see what we can do. We’re working on creating a plug-in interface for solving domain specific problems. We would love to have a few projects to help pilot this effort. If you're interested, please let us know in the help forum.
I have some photos or a dataset you can use. Do you want it?
Most likely we can work with you for a place to stash and share your stuff. Please contact us about it by posting in the help forum.
I want to teach a SimpleCV class, or use it at a hack-a-thon. What do I do?
Great! Please let us know about it in the help forum. We can get you our training materials, bulk discounts for the book, and potentially send you some keen SimpleCV schwag.
Where do I get your book?
I found this error in the book. Do you want to fix it?
An error? In our book? Impossible! Seriously, though, if you've found an error, we definitely want to hear about it so we can fix it. Just let us know about it in the help forum - and thank you for taking the time to help us this way. We're also interested, by the way, in any general feedback you might have about the book. We'd love to hear what you think!
What books should I read to learn more about computer vision?
There are a lot of good books out there. Here are some of the latest books on the subject:
- Programming Computer Vision with Python by Jan Erik Solem
- Computer Vision: Algorithms and Applications by Richard Szeliski
- Computer Vision: Models, Learning, and Inference by Simon J.D. Prince
Here are some other good books:
- OpenCV 2 Computer Vision Application Programming Cookbook by Robert Laganière
- Learning OpenCV: Computer Vision with the OpenCV Library by Gary Bradski and Adrian Kaehler
- An Introduction to 3D Computer Vision Techniques and Algorithms by Boguslaw Cyganek and J. Paul Siebert
- Multiple View Geometry in Computer Vision by Richard Hartley and Andrew Zisserman
Where do I get more help on computer vision problems that aren't related to SimpleCV?
We really like to use the OpenCV and Python reddits for more general questions:
Other good resources include:
How do I get my questions answered?
How do I put together a good pull request?
Okay, first to understand more about GitHub and how pull requests work, please read this GitHub article on using pull requests.
Now let’s talk about what is in a good SimpleCV pull request (i.e. the code and such).
The text in the pull request should summarize what the code does, and why it is needed. If it is a bug or a feature request, the text should describe exactly what you did.
A good pull request has three things:
- The code: what you have added or changed
- Unit tests: your test should cover most of your feature, or replicate your bug
- Documentation: please comment your code following the style in our documentation guide
- BONUS: an example using the new functionality
If your pull request is non-trivial, and it does not contain these three things, chances are we’ll deny it and ask you to make the changes. Please also make sure to add any images used in your unit tests to the sample images folder.
How do I get my problem solved quickly?
The best way to get your problem solved is to route it to the right place and provide us with enough information to repeat the problem. Also getting you problem solved may require you to do your own leg work first (i.e. did you google it and did you search the forum).
Steps to solving a code problem:
- Check the documentation (help()) in the simplecv shell. Or try reading the docs: http://examples.simplecv.org/en/latest/index.html
- Check the documentation again (i.e. open the offending file and see what it is doing).
- Look at the unit test for the method. That should show it working in the wild.
- Look at your image. Is anything wonky? Step through your image processing chain in the simplecv shell. Save each image in the chain for later! Try changing the method parameters. Does that help? Try another input image. Does the pipeline work for that image?
- Just as a sanity check, run the test suite (see running tests). Do all of the tests pass?
- Okay -- you made it this far. Google it, then search the help forum.
- Okay -- still having problems. Post to the help forum, the email list, or find us on IRC.
- If we say it is a bug escalate it to GitHub.
Steps to solving an installation problem:
- If you are working from a superpack, did the super pack fail? If so where in the process?
- Did you try installing from source? Try that?
- Can you get an ipython shell? Can you import SimpleCV and cv/cv2? If not check your path variables. Maybe restart is necessary.
- Check the forum. Has someone had the same issue?
- Okay, you may have a bug, please submit a question to the forum or the email list.
How do I create a good GitHub ticket?
tl:dr - Tell us the specific problem (i.e. error, OS, version, line number, code, image, etc). - Tell us what you want. - Show us how it should work (i.e. what the code should look like). - Point us to resources (like code in some other repo). - Give us something to test on (i.e. images). A good ticket should give us a complete description of the problem you want us to solve, the feature you want us to add, or the thing you would like us to look into. Generally GitHub tickets should only be used for confirmed software bugs. This is to say that bugs should start out on the help forum and then get escalated from the help forum to a GitHub ticket. Bug tickets should include any information that may help us solve the problem. If you do not include the code and the images that generated the bug we may choose not to fix it. A good bug ticket includes a brief description of the problem, the OS, the SimpleCV version, and all of the hardware. A feature request ticket should tell us what functionality you want and WHY. The ticket should then go on to give us example code of how you think it should function (the syntax doesn’t need to be perfect). Finally it is very helpful if you include images of potential input and potential output. This helps speed up the development process by providing us a sketch for a unit test. Finally you should link any resources that may help us work on the problem. If the desired code has an analog in OpenCV/SciPy/Numpy link to the documentation. IF you have an algorithm in mind, link to pseudo code or an implementation in some other language. EXAMPLE: https://github.com/sightmachine/SimpleCV/issues/70