############################################################################## GROCERY GUARDIAN README / OPERATING INSTRUCTIONS v1.1, 2010.05.07 CS160 FINAL PROJECT, SPRING 2010 Andrew Finch Divya Banesh Arpad Kovacs Saba Khalilnaji Daniel Nguyen ############################################################################## 0. Overview ----------- This archive contains the complete Objective-C source code and resource files for Grocery Guardian, a proof-of-concept iPhone application developed as our final project for the CS160 User Interfaces class at UC Berkeley, taught in Spring 2010. This document contains notes on how to install the application, as well as a description of the application's functionality and key user-interface elements. INDEX 1. Installation Notes 2. Introduction 3. Interface Walkthrough: Products 4. Interface Walkthrough: Analyze 5. Interface Walkthrough: Profiles 6. Interface Walkthrough: Help 7. Troubleshooting 8. Disclaimer 9. Attribution / Credits 1. Installation Notes --------------------- Grocery Guardian is written in Objective-C using the Cocoa Touch framework. In order to build the application, you will need to obtain and install the following hardware and software: * "Apple-branded" computer running Mac OS X 10.5 or later * Xcode 3.0 or later (3.1 or later for Camera functionality) * [Optional] iPhone device running iPhone OS 3.1 or later To run the application, please open the GGuardian.xcodeproj file in Xcode, and then select the "Build and Run" command. Note that due to the large number of resource files in this application, it will take a long time to complete the "Build and Run" operation (between 10 and 20 minutes). Please be patient. 2. Introduction --------------- Grocery Guardian makes grocery shopping easier and more convenient for people who must take food allergies, intolerances, or dietary restrictions into account when shopping for themselves or their friends and family members. The application provides a quick, accurate, and simple tool for detecting offending ingredients in food products that any shopper can use effectively. It allows users to set up a descriptive profile for each person with dietary restrictions. Users can then use the iPhone's camera to scan the barcode of a food product, or simply search for the product in a built-in database. Once a product is selected, it is instantly analyzed with respect to the allergens defined in each active profile. The user is shown which profiles the product is safe for, and if he/she desires, can see more details about the product, its ingredients, and its safety for a particular person. The application resides in 4 tabs: "Product", "Analyze", "Profiles", and "Help". The following sections will provide a brief overview of the salient user-interface elements and functionality contained within each tab. Key Application Features: * Search over 27,397 products found in US Grocery stores by UPC or product name using real-time dynamic text queries. * Scan the barcode of your product of interest, and get instant feedback. * Add allergens to your profile from a predefined list of 80 allergens, or define your own custom allergen. * View unsafe ingredients and product images immediately. * Works without an Internet connection. * Free basic version, more accurate subscription-based service coming soon... 3. Interface Walkthrough: Product --------------------------------- This is where the user selects the product that he/she would like to analyze. There are 3 ways to do this: 1) The user can browse an alphabetical list of all 30,000 products available in the application's built-in database. 2) He/she can enter any terms associated with a product into the search box, and the application will dynamically filter the list accordingly. 3) He/she can scan the barcode of a product. To do this, the user simply taps on "Scan Barcode". The user will be provided with a live view of what the camera sees, and must position the camera so that it lines up with the barcode and is in focus. Once the application reads the barcode, it will automatically look up the corresponding product based on the UPC. Once a product is selected by any of these methods, the user is taken to the "Analyze" tab. The user can also view a list of the 20 most recently analyzed products by tapping on "Recents". 4. Interface Walkthrough: Analyze --------------------------------- After scanning a barcode or searching for an item, the application will show detailed information about the product in the analyze tab. The "Analyze Overview" screen appears first, which displays the name, UPC code, and an image of the selected product. Below this, it lists each active profile, and indicates whether the product is safe to consume for the owners of each of these profiles. If the user can safely consume the product, then a green checkmark appears next to the user's name with the word "Safe" below. If the product is unsafe, a red circle with a slash appears next to the user's name with the caption "Unsafe" below, along with a list of the unsafe ingredients. Once a user taps of one of the profiles, he/she is taken to the "Analyze Details" screen. This screen shows the number of problem ingredients in red if the product is unsafe, or in green if the product is safe to consume. Below this is a full list of the ingredients contained in the product, with any ingredients that conflict with the user's profile highlighted in yellow. 5. Interface Walkthrough: Profiles ---------------------------------- This tab allows the user to manage the profiles in the application. The overview page shows a table of all profiles that the user has created, and allows the user to specify which profiles the application will consider during analysis by toggling the "On"/"Off" switches next to each profile. From this screen, the user can edit the details of existing profiles, or create a new profile. To create a new profile, the user taps the "Add Profile" button, and enters the name of the person that the profile is intended for. Next, the user clicks on the "Add Allergen" button to select an allergen. The user can choose from the built-in database containing 80-allergen, or tap "Create Custom Allergen" to add a user-defined allergen to the list. In either case, the user can review and change the list of ingredients associated with the particular allergen. The user can then save the profile and see it appear in the list of profiles. To edit or delete an existing profile, the user selects the profile to modify. The user can then add another allergen by tapping "Add Allergen" or remove allergens from the profile by tapping the allergen and selecting "Delete Allergen". They can also remove a profile by selecting the profile and then tapping "Delete Profile". 6. Interface Walkthrough: Help ------------------------------ The help screen provides a quick-start guide for users who are new to the application. It outlines the basic functionality and the steps a new user should take in order to begin using the app. 7. Troubleshooting ------------------ At the time of writing of this document, there were no known outstanding bugs or stability issues. This application was tested on Mac OS X 10.5 and Xcode 3.1.3, and we could successfully deploy and run the app on an iPhone GS running iPhone OS 3.1.3. It may be possible to run the application on an older or lower-spec'd device, but any configuration deviating from the above is not officially supported, due to the data-intensive nature of our application which stresses the iPhone's processor, RAM, and storage I/O bandwidth to its limits. If you encounter any compile/build errors, please make sure that the following dependencies are satisfied and correctly configured: * Foundation, UIKit, CoreGraphics, CFNetwork, SystemConfiguration, AudioToolbox frameworks (should be included in your Xcode distribution) * libsqlite3.dylib, libz.1.2.3.dylib libraries (should be included in Xcode) * libRedLaserSDK_sim.a, libRedLaserSDK.a (included in RedLaser SDK) Please note that our database is from 2007, and therefore products that have emerged since then or existing products whose packaging has been revised may not be detected in the database, since their UPC numbers / SKU (Stock-keeping unit identification numbers) may have changed during the past 3 years. Also note that the database only consists of valid 12-digit US UPC codes; EAN-8 and EAN-13 or international barcodes are not recognized by Grocery Guardian. If you still encounter a bug, please notify the developers listed at the top of this document. 8. Disclaimer ------------- The services, information or data (collectively, "Information") made available in this Grocery Guardian application are provided "AS IS," without warranties of any kind. The Grocery Guardian team (henceforth "GG") expressly disclaims any representations and warranties, including without limitation, the implied warranties of merchantability and fitness for a particular purpose. GG shall have absolutely no liability in connection with the services including without limitation, any liability for damage to your computer hardware, computer software, iPhone hardware, iPhone firmware, iPhone software, data, information, materials and business resulting from the information or the lack of information available in the Grocery Guardian application. GG shall have no liability for: * Any loss, injury, or death caused, in whole or in part, by its actions, omissions, or negligence, or for contingencies beyond its control, in procuring, compiling, or delivering the Information; * Any errors, omissions, or inaccuracies in the Information regardless of how caused, or delays or interruptions in delivery of the Information; or * Any decision made or action taken or not taken in reliance upon the Information furnished hereunder. GG makes no warranty, representation or guaranty as to the content, sequence, accuracy, timeliness or completeness of the Information or that the Information may be relied upon for any reason. GG makes no warranty, representation or guaranty that the Information will be uninterrupted or error free or that any defects can be corrected. For purposes of this section, "GG" shall include the Grocery Guardian team members, and its divisions, subsidiaries, successors, parent companies, and their employees, partners, principals, agents, family members, and representatives, and any third-party providers or sources of information or data. 9. Attribution / Credits ------------------------ 1) Since we were unable to license a product/UPC/ingredient database from a commercial vendor, we decided to use Avidan Ackerson's senior design project thesis as a datasource, which consists of product name, UPC, and ingredient data. This information was scraped specifically from grocery store websites rather than the Internet as a whole, therefore it should be quite accurate. * http://www.seas.upenn.edu/~cse400/CSE400_2007_2008/AvidanAckerson/index.html 2) Product image results were collected from Amazon.com using a custom webcrawler written in-house. Please see the Product Advertising API page for more details. * https://affiliate-program.amazon.com/gp/advertising/api/detail/main.html 3) Section 8: Disclaimer text is a modified version of the Software Bisque, Inc. Disclaimer of Warranty. * http://www.bisque.com/help/theskyv6/telescope/Warranty_Disclaimer.htm 4) ASCII Image Art generated using Photo to Text and Figlet * http://www.photo2text.com * http://www.figlet.org/ 5) All other code, images, and other resources contained within this archive were written by us, and are copyrighted by Grocery Guardian LLC. /jk 6) Thank you CloudFusion and the GNU/Linux project for creating excellent, free data-processing tools, without which this project would not be possible. * http://getcloudfusion.com/ * http://kernel.org/ * http://www.gnu.org/ 7) Thank you CS160 staff for your encouragement and support; we really enjoyed taking the class and learned a lot this semester. 8) Thank you for RTFM, we hope you enjoy using our application. @@ir;r@@ @ .,;;. @ @@.:;:::,.@@ @ .:;:::::,. @ @ :;;;;;;;:, @ @.;;;;;;;;;:.@ @@ :;;:;;;;;;;,@@ @@@@@@@@@@@ @,;rr;rrrr;;;,,@@ @@@@ :.,., @@@@@@ @::rrsrrrrsrrr;: @ @@ s:;;;;;;::,,:@@@@@irsssrssssrrsr;.@ @@@r;;rrrrrsrr;;;::,,@@:rssssisiisssir;@ @@.:;rsssiiisrrrrrr;;::@rrsissiiiissiir;@ @@:;sssssssssssssrrsr;;:sS5SSiSSSSSi5Si;@ @@:rsrrssiiissssssssssrrri332XXXXXXXXX22i@ @@,;rsrsssisissssssssssssrsGG9hGGGGGhhGh9i@ @@,rssssssssssssssiiiisrirsAHAAAAAAAAAAA&X@ @@;siSSSiiiSSSSSSSSS555S22&M#MMMMMBBBBBBHA@ @@ 2222XXXXXXXXXX3333333h&HHAAABM#######MH@ @@@@#&9hhhGGGGGG&&&&&&&&&Gh9333hAM@@@@@##H@ @@@@AGAAAAAAAAAAAHAHAAGGhh999933GB@@@@@@#@ @##M#@@@@@@@@BAHBBBBBBBBBBMBBAhhhhh9h993XX&@@@@@@@@ @#Gr:;XH@@@@@#MM############MA3X3333333X259@@@@@@@@@ @@Ms,,::;5B@@@@@@@@@@@@@@@@@@B92X99999h993A@@@@@@@@@@@ @@@2;:;;::;iA@@@@@@@@@@@@@@@@@#BBMMM######@@@@@@@@@@@@@ @@Airrrr;::;sh@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@MXsrrsrr;;:;r2H@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @@#9irsssssrr;::rX#@@@@#MMMMMMMMMM#MBAGhh999h3X5SiSSirsXM@ @@#&irrssssssrr;;s9Ah5r;;;;;;;;;;;;;::,,,,,,,,. .5@@ @@@HSrrssssssssrr2h9s, ............,,,,:,,,::::::;;:,;A@ @@M5rrssssssssrs2AA2;,:;;;;;;;;;;;;;;;;;:::;;;;rrrrr;rH@ @@#2rrsssssiisrsXHB3r;;;;;;rrrrrrrrrrrri5Sisrr;;;;;;;iM@ @@Xrrsssssiisrs&#M2r;;rrrrrrrrrrrrrri&@@@@#Ah2Siisii3#@ @@@@@@@@ @@XrrsssiisisrsA@As;;;rrrrrrrrrrrr;i#@#&GA#@@@@@@@@@@@@@@@@@@@@#BAhGM@@ @@XrrssssssisrsA@As;;;rrrrrrrrrrrsSA@@2::;rsiiSX&A&Xirri2X25iiSS5552&#@@ @@Xrrssssssisrs#@G;:;rrrrrrrrsssriA#MXr::;;;:::;rrr;;;;rrrrrrsiS52XX3A#@@ @@XrriissssssrS@@9::rrrrrrrrssssri#@&r;rrrrrrrrrrrrssiiiiiiS222X3999XhM@@@ @@Xrrsisssssss2#@X;;rrrrrrssssssr5@@h;;rsssssssssiiiiSSS5522XXX33hhh9GB@@@ @@XrrsissssssS9BH5;;rrrrrrssssiiiX#@2;;rsssssssiiiiiSSSS5522XXX339hhhGH#@@ @@Xrrsisssiss2AMAi;;rrrrrsssiiii59MM2;;rsssssssiiiiiiSS552222XX399hGG&A#@@ @@2rrsisssirs9MBXs;;rrrrssssiiiiS9##2;;ssssssssiiiiiiSS55222XX3399hGG&H#@@ @@#5rrsissssrsA@Hi;;;rrrrsssiiiiS5h##2;;rsssssssiiiiiiSS55222XXX399hGG&H#@@ @@@HSrrsissisrrH@Ar;;rrrrrssiiiiiS2G##2;;rssssssiiiiiiSS555222XX339hhGG&B#@@ @@#&irriissisrsM@A;:rrrrrsssiiiSSSSh@@9;;rrssssssiiiiiSSS55222XX399hhGGAM@@ @@B9irrisssssi2#@9;:rrrrrsssiiiSSSi2@@G;;rrssssssiiiiiSSS55222XX339hGGGAM@ @@M9irrississiXM#X;;rrrrrsssiiiS5Si2#@HirrrssssssiiiiSSSS55222XX339hGGhA#@ @@H2srsisssss5GBAS;;rrrrrsssiiiS55i2H@#3srrssssssiiiiiSS555222XX339hGG&H@@ @@Airrsisssrs2AM&i;;rrrrrsssiiiS55S5h#@#5;rsssssiiiiiiSS55522XXX399hh&H#@ @@&isssisisrs9#B2r;;rrrrrsssiiiS555S5A@@3;;rssssiiiiiiSS555222XX39hh9GM@@ @@AirrsisisrrG#Hi;;;rrrrrsssiiiSS55SiX@@M5rrrsssiiiiiiSS555222XX399hGA#@ @@Airrrssisrr&@Bs;;;rrrrrrsssiiiS555S5G@@@2;rsssiiiiiiSS55222XXX393hA#@@ @@#G5srrrssrrB@B;,;rrrrrrrsssiiiSS525SS&@@HirrssiiiiiiSS552222X3393G#@@ @@@@#9irrr;rH@H;,;rrrrrrrrsssiiSS5525S2H@@MS;rsiiiiiSSS55222XX3X3&#@@ @@@@&ir;;H@H;:;rrrrrrrrsssiiiSS5525S5A@@BSrrsiiiiSSS55222XXXXhM@@ @@@3;;A@B;:;rrrrrrrrrrrsssiiiSS5Si2G@@@2rrsiiiSSS5522222XA@@@ @@AiA@H;:;;;;;;;;;rrrrrrrssiiiiiii9@@@AirriiSSS5222529B@@ @@@@@&:,;;::;;si23hhA##########MHAH@@@@hsrsiSS55SS2A@@@ @@@G;;i3H#@@@@@@@@@@@@@@@@@@@@@@@@@@@@#9issiii2&@@@ @@@#@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@AXS2A@@@ @@@@@ @@@@@@@@@ ____ ____ @@@@@ _ _ / ___|_ __ ___ ___ ___ _ __ _ _ / ___|_ _ __ _ _ __ __| (_) __ _ _ __ | | _| '__/ _ \ / __/ _ \ '__| | | | | _| | | |/ _` | '__/ _` | |/ _` | '_ \ | |_| | | | (_) | (_| __/ | | |_| | |_| | |_| | (_| | | | (_| | | (_| | | | | \____|_| \___/ \___\___|_| \__, |\____|\__,_|\__,_|_| \__,_|_|\__,_|_| |_| |___/ # AKDoc 2010.05.07