|
DeveloperNotes
Miscellaneous information of use to developers
Calling ZXing in a programUsing ZXing within a Java program is quite easy. First, you need an implementation of com.google.zxing.Reader. You might use an implementation that can detect all formats the library reads: Reader reader = new MultiFormatReader(); Or, for example, if you knew you were only reading QR Codes, you might instantiate an implementation that only understands QR Codes. This is more efficient. Reader reader = new QRCodeReader(); Next you need an image to decode. Readers read implementations of com.google.zxing.MonochromeBitmapSource, which are abstractions on top of various classes representing images, presenting them as a monochrome image to be decoded. For example, an implementation exists for instances of java.awt.BufferedImage: BufferedImage myImage = ...; MonochromeBitmapSource source = new BufferedImageMonochromeBitmapSource(myImage); Now you're ready to decode: Result result = reader.decode(source); com.google.zxing.Result has several methods that give you access to the raw bytes or text encoded by the barcode found, if any, as applicable. It will also reveal key points in the image related to the barcode that was found, such as the three finder patterns in a QR Code and the bottom-right alignment pattern. String text = result.getText(); byte[] rawBytes = result.getRawBytes(); BarcodeFormat format = result.getBarcodeFormat(); ResultPoint[] points = result.getResultPoints(); Finally, the decoders support a system of "hints" that help the decoder work more efficiently, or trade off accuracy for speed more appropriately. For example, the "TRY_HARDER" hint asks the decoders to spend much more time searching for a barcode: Hashtable<DecodeHintType, Object> hints = new Hashtable<DecodeHintType, Object>(); hints.put(DecodeHintType.TRY_HARDER, Boolean.TRUE); Result result = reader.decode(source, hints); Change LogThe list of latest changes is always available in Subversion. JavadocSourceYou can easily browse the source code in Subversion instead of retrieving it. zxing.org notesYou too can run your own online decoder. Complete source code for zxing.org is available in the zxingorg/ module. While you probably don't wish to deploy this exactly as-is, since it references this project, we provide some instructions on how to build and deploy it in case you wish to modify and deploy it for your own purposes. Email configurationIf you wish to enable decode-by-email functionality, you will need to ensure that the parameters like POP host in com.google.zxing.web.DecodeEmailTask are correct for your mail server. Change them if needed. The standard configuration works for a Google Apps-hosted domain. In web/WEB-INF/web.xml.template, look for <context-param> entries. Change emailAddress to the account that receives images by email. Don't change emailPassword. Instead, create a file called secrets.properties in the zxingorg/ directory. It should have one line: emailPassword=(your password) If you want to disable this functionality, just comment out the <listener> in web/WEB-INF/web.xml.template called com.google.zxing.web.DecodeEmailListener. SetupOn the machine that will host the service, first make sure Java is installed -- does the java command work, and is the version at least 1.5? If not, download and install the latest JDK (not JRE) from Sun. Make sure the JAVA_HOME environment variable is set to the location where Java 1.5 or later is installed. On Unix-like operating systems this is accomplished by the shell command: JAVA_HOME=(where the JDK is installed) Next download Apache Tomcat -- version 6 is recommended. Install anywhere you like; /usr/local/tomcat is a common loaction. We recommend you delete everything you see under Tomcat's webapps directory to start, to disable everything but your application. In the build.properties file at the top level of zxing, set tomcat-home to the location where Tomcat was installed. Note, if you are using Windows, and therefore using backslashes to separate path elements, you will need to use a double backslash instead of single backslash since backslash is a special character in this file. BuildIn core/, run ant to build core. Likewise for javase/. Finally, in zxingorg/ do the same to produce zxingorg.war. This file may be placed in Tomcat's webapps directory. Now, find the startup.sh script in Tomcat's bin directory and run it. Tomcat should start and you will be able to access your service at http://localhost:8080/zxingorg/decode.jspx. Further ConfigurationDon't like the "zxingorg" path? change the name of the .war file. Don't like using port 80? You will have to modify Tomcat's server.xml file to use port 80, and run Tomcat as root -- or take other measures to expose Tomcat on port 80. These topics are beyond this quick documentation. Errata observed in the wildIn the course of building the decoders we've observed, in the wild, some barcodes that don't quite follow the spec. We thought it would be interesting to document these variations. QR CodesCharacter encodingQR Code offers four modes for encoding text: numeric, alpha, Kanji, and byte mode. Byte mode is tricky, because, byte mode is still used to encode text, not raw bytes. The question then is, how is character encoding specified, or, what is the character encoding that is always used? There is no mechanism for specifying character encoding (well, see note below on ECI). The ISO 18004 spec strongly implies that ISO-8859-1 should be used. Its predecessor, JIS X 0510, leaves the question more open and suggests ISO-8859-15 or UTF-8. However, it's clear that Shift_JIS is widely used in practice in Japan. Text may decode improperly if a reader expects or assumes one encoding but reads text in another. Fortunately, the encodings mentioned here encode the exact same bytes for typical Latin characters, digits and punctuation, so for most applications, the choice of encoding will happen to not matter. (Developer note: the ISO-8859-1, ISO-8859-15, UTF-8 and Shift_JIS encodings map code points 0x20 to 0x7E to the same characters. Well, this is 99% true; Shift_JIS defines one or two characters slightly differently. In this range these encodings also match US-ASCII.) The ZXing library uses crude heuristics to guess when Shift_JIS or UTF-8 is being used, and decode accordingly. It defaults to ISO-8859-1. It is advisable to use only the characters that are common to all these common encodings (see the ISO-8859-1 codepage, from 0x20 to 0x7E). In a situation where one must encode other characters, it is advisable to choose UTF-8 encoding for the whole string. Shift_JIS may be preferable when Japanese language characters must be encoded. There is a mechanism to define character encoding, sort of, called ECI (Extended Channel Interpretation). ECI messages in a QR Code can be used to affect how the reader construes the remainder of the bytes in the message, which includes defining a character encoding. There is no public reference, it seems, for which ECI codes map to which character encodings, making this mechanism of questionable usefulness to a developer; I have never seen it used in the wild and am not sure if readers support it in general. We will strive to support it. Format information not maskedThe "format information" bits are supposed to be XOR-masked with the pattern 0x5412. Quite simply, some encoders don't seem to do this. If you unmask and don't match a valid format pattern, see if the raw "unmasked" pattern is in fact a valid format pattern. No alignment patterns in version 1 QR CodeIn detecting 2D barcodes, one must detect and account for not just rotation, but perspective disortion, wherein the barcode plane is not parallel to that of the camera. (And then there is the problem of a warped barcode and barrel distortion, which this library does not account for.) The QR Code format requires three finder patterns at three corners of the image. Unfortunately this is not enough to determine perspective distortion correctly. Fortunately, the current QR Code also calls for alignment patterns, small finder-pattern-like patterns, throughout the barcode as well. These additional points, when located, provide at least a fourth data point. This library looks for the bottom-right alignment pattern as the fourth point to use when calculating perspective distortion. (And again, note that you can use the additional alignment patterns to correct for warp. This is significantly more computationally expensive and at this point is not supported. Keep those barcodes flat, folks. It is really an issue for very large QR Codes, which are generally impractical anyhow.) But, brilliantly, the smallest "version 1" QR Codes are so small that they do not include alignment patterns. We're back to three points, and can't reliably correct for perspective distortion based on those three points alone. This is a real issue, since version 1 is commonly used, and a little distortion can easily throw off enough pixels to make the code unreadable. One could resort to more sophisticated techniques in this situation to determine perspective, like attempting to trace the edge of the barcode. I highlight it here since it strikes me as a real deficiency in the specification -- unless I am completely misunderstanding. |
Sign in to add a comment
The issue of the reader not downloading properly on Sprint network phones is similar to the situation of that of Opera Mini 4.1. It would not download onto many LG phones. The situation was solved by an Opera programmer who provided a tweaked version of the .jad file.
The situation is discussed on this Opera Mini support forum post:
http://my.opera.com/community/forums/topic.dml?id=233058
The solution is midway down in the post dated Thursday, 29. May 2008, 15:12:34.
What QR Code detection algorithm did you use? Did you follow an existing algorithm, or develop your own?
This is a nice project, thanks.
-Brian
It is just an algorithm we made up, though I expect the basic approach is the obvious one, to scan quickly for 1-1-3-1-1 patterns in the modules, close to it, to locate possible finder patterns. It is not the reference detection algorithm which is somewhat vague on details and not efficient. I have purposely avoided reading other detection algorithms to avoid inadvertently copying someone's ideas.
Thanks for the quick reply.
So then, does the algorithm scale from image pixels to bits first? Or rather, how do you do the scaling?
Please follow up on the discussion group -- this is just wiki comments. http://groups.google.com/group/zxing/
Does the detector operate on binary black/white data? yes. If I understand your question correctly, the image is dithered first. How its done is in the source I suppose I could say, and we can cover questions in more detail on the mailing list.
I'm a brazilian developer and my software need a datamatrix barcode generator. as I put the zxing in my sofware?
Sorry the library does not have a datamatrix generator.
I am unable to read Data Matrix Barcodes using C# port or Java. Is the datamatrix reader strong? The images are slightly damaged but its very very little damage... is there any other ways apart from changing the scanner I can get this to work ?
Please post to the discussion group for comments not related to the wiki http://groups.google.com/group/zxing/
There is no port to C# of Data Matrix, and the Java decoder is not enabled by default. The decoder is great; the detector is not very effective.
Hello,
I'm a Swiss developer and I'm making an iPhone application that has need to use the QR-Code. Can I put the zxing in my application? Thanks
Please post to the discussion group with questions: http://groups.google.com/group/zxing/
You can use the code within the terms of the Apache license. Please also look at the wiki on licensing in this project.
The perspective of a version 1 QR code could be determined using the corners of one of the finder patterns.