User Guide & Science Explanation

Welcome to the Smart AI Acid–Base Detector guide. This document explains how to use the app in your laboratory, the chemistry science behind it, and the junior school mathematics we used to make it work.

📋 1. How to Test Your Sample (Step-by-Step)

1. Prepare the Solution: Place your liquid sample (e.g. lemon juice, water, soap) in a clear test tube or glass vial. Add 3 drops of Universal Liquid Indicator and mix gently.
2. Upload a Photo:
   • Tap 📸 Take Live Photo to open your phone's camera and take a fresh picture. Make sure to tap "Allow" if your phone asks for camera permissions.
   • Or tap 🖼️ Choose from Gallery to select a photo you already took.
3. Position the Crop Box:
   • Tap or drag on the photo to slide the cyan crop box directly over the colored liquid.
   • Use the 📏 Crop Box Size slider to shrink or expand the box. Make sure it covers only the colored solution, avoiding any white glare or container glass edges.
4. Analyze: Click ⚡ Analyze Color. The app will immediately display your pH level outcome!

🌐 2. Loading the App on Your Phone

The application can be accessed on your mobile phone in two ways:

• Online Server (Recommended): Simply visit the public web domain in your phone's browser:

  https://lab.kingori.co.ke

• Local PC Server (Offline Backup): If there is no internet connection at the science fair venue, you can run it locally using XAMPP on your computer:
  1. Connect both your computer and phone to the same network (or turn on your phone's mobile hotspot and connect the computer to it).
  2. On your Windows computer, open the Start menu, type cmd, and press Enter. Type ipconfig and write down the IPv4 Address (e.g. 192.168.x.x).
  3. Open your phone's browser and navigate to: http://[your-computer-ip]/indicator/.

🧪 3. The Science Behind pH (Chemistry Made Simple)

What makes a solution an acid or a base? It is all about tiny particles called Ions:

• Acids (pH 0 to 6): Acidic substances release Hydrogen ions (H⁺) in water. The more H⁺ ions there are, the stronger the acid, and the lower the pH number (e.g. lemon juice or stomach acid).
• Neutrals (pH 7): Neutral substances have a perfect balance of ions. Pure distilled water has pH 7.
• Bases / Alkalis (pH 8 to 14): Alkaline substances release Hydroxide ions (OH^-) in water. The more OH^- ions there are, the stronger the base, and the higher the pH number (e.g. soap or wood ash).

🌈 Why does the indicator change color?

Universal Indicator is a chemical dye mixture. It is highly sensitive to the concentration of H⁺ and OH^- ions. When the chemical environment changes, the dyes undergo structural changes that cause them to absorb and reflect different wavelengths of light, producing a clean color spectrum:

Red (Strong Acid) ➔ Green (Neutral) ➔ Purple (Strong Alkali)

📐 4. The Math (3D Pythagoras' Theorem [Euclidean Distance])

In school, you learn Pythagoras' Theorem (a² + b² = c²) to calculate the hypotenuse of a right-angled triangle on flat paper (2D):

2D Distance = √((x₂ - x₁)² + (y₂ - y₁)²)

How we apply this to colors:

Every digital color is represented by a mixture of three channels: Red (R), Green (G), and Blue (B). Because there are three channels, we can think of any color as a point inside a 3D "color room" where the walls are Red, Green, and Blue.

To match your cropped lab photo to our calibrated standard colors database, our software applies Pythagoras' Theorem in 3D [Euclidean Distance] to find the distance (d) between the sample color and the textbook standard references:

$$d = \sqrt{(R_{\text{avg}} - R_{\text{ref}})^2 + (G_{\text{avg}} - G_{\text{ref}})^2 + (B_{\text{avg}} - B_{\text{ref}})^2}$$

Whichever pH reference card has the shortest distance (lowest d) in the color room is selected as the matching outcome. If the colors align perfectly, the distance is 0, resulting in a 100% match confidence!

💻 5. The Software Workflow (Under the Hood)

When you click analyze, the server processes your crop in three fast steps:

1. Resampling (Averaging): Instead of running a slow loop through millions of pixels, the server resizes your crop box down to a single 1x1 pixel image. The server's graphics processor automatically averages all color channels into a single R, G, and B value instantly.
2. Saturation Guard: The app checks if your crop is black, grey, or white (glare). If the difference between the highest and lowest color channel is less than 18 (delta < 18), it warns you that you cropped a glare or shadow, protecting the math from bad inputs.
3. AI Verification: The server transmits the cropped image to Google Gemini AI (using gemini-3.1-flash-lite), which serves as a virtual laboratory assistant. It verifies your image crop quality and writes a simple Grade 9-appropriate explanation of the chemical properties.

🧪 6. Calibrating for Your School's Chemical Brand

Different chemical manufacturers (such as SEPU [School Equipment Production Unit], Kobian, or local Kenyan laboratory suppliers) distribute Universal Indicator solutions that might have slightly different shades of red, green, or blue.

If you notice the app consistently matches your water to pH 6 instead of pH 7, you can easily custom-calibrate the database to match your school's indicator brand!

1. Open the file ph_reference.json located in your website folder using a text editor.
2. Locate the pH number you want to adjust. You will see its RGB values, like:

   { "ph": 7, "name": "Neutral", "rgb": [75, 175, 75] }

3. Take a photo of your school brand's pH 7 standard color, crop it, and read the Average RGB Measured values shown on the app screen.
4. Change the [75, 175, 75] values in the JSON file to your brand's measured RGB values, and save the file. The app is now perfectly calibrated to your specific school chemicals!