Lesson 4: Toy Edge Detect Library

Image matrices, grayscale conversion, convolution, Sobel edge detection, pixel math, normalization, clamped sampling, and PNG output.

scripts/run.sh lesson_4 demo
scripts/run.sh lesson_4 exercise
scripts/apply_answers.sh lesson_4
scripts/run.sh lesson_4 verify
scripts/reset_exercises.sh lesson_4

Lesson README

Lesson 4: Toy Edge Detect Image Preprocess Library

This lesson builds a small Java library around image preprocessing, convolution, and Sobel edge detection.

120-Minute Plan

Exercise

Use workbook.md for the full two-hour learner path. It includes image tracing, numeric implementation rounds, and boundary edge cases.

Edit src/exercise/java/tutorial/lesson4/exercise/PixelMath.java.

Functions to implement:

• clamp
• invertGray
• threshold
• luma
• packGray
• normalizeToByte
• blend
• sobelMagnitude
• sampleClamped
• mean3x3

The toy library itself is runnable independent of the exercise answers.

After applying answers, run scripts/run.sh lesson_4 verify to check byte validation, luma math, packed pixels, normalization, blending, Sobel clamping, rectangular image validation, and boundary sampling.

Learner Workbook

Learner Workbook: Lesson 4 Toy Edge Detect Image Library

This workbook is designed to take about two hours. The goal is to understand Java library structure and image preprocessing through small numeric functions.

What You Should Understand By The End

• How a grayscale image can be represented as a matrix.
• Why image code clamps values to 0..255.
• How RGB channels are packed into an integer.
• How a convolution kernel samples neighboring pixels.
• How Sobel edge magnitude combines horizontal and vertical gradients.
• How boundary handling changes results at image edges.

0-15 Minutes: Generate Images

Run:

scripts/reset_exercises.sh lesson_4
scripts/run.sh lesson_4 demo
scripts/run.sh lesson_4 exercise

Open:

build/out/lesson_4/synthetic-input.png
build/out/lesson_4/sobel-edges.png

Write down what changed between the input and edge output.

15-35 Minutes: Trace The Library

Open src/demo/java/tutorial/lesson4/demo/EdgeDetectDemo.java.

Trace:

• Input image creation or loading
• Grayscale representation
• Sobel edge detection
• Output writing

Then open:

• ImageMatrix.java
• Kernel.java
• Convolution.java
• EdgeDetector.java

For ImageMatrix, pay attention to the difference between (x, y) coordinates and values[y][x] storage.

35-50 Minutes: Read The Exercise API

Open src/exercise/java/tutorial/lesson4/exercise/PixelMath.java.

Group functions by skill:

• Bounds and byte validation: clamp, invertGray, threshold
• Color conversion: luma, packGray
• Range conversion: normalizeToByte, blend
• Edge math: sobelMagnitude
• Image boundary handling: sampleClamped, mean3x3

Before editing, write expected outputs for at least four functions.

50-95 Minutes: Implement In Rounds

Round 1:

• Implement clamp.
• Validate min <= max.

Round 2:

• Implement invertGray and threshold.
• Validate all gray values are bytes.

Round 3:

• Implement luma.
• Extract red, green, and blue using bit shifts and masks.

Round 4:

• Implement packGray.
• Return an opaque ARGB integer.

Round 5:

• Implement normalizeToByte.
• Values below range map to 0; values above range map to 255.

Round 6:

• Implement blend.
• Test alpha 0, 0.25, 0.5, 1, and invalid values.

Round 7:

• Implement sobelMagnitude.
• Clamp large gradient magnitudes to 255.

Round 8:

• Implement sampleClamped.
• Validate non-empty rectangular images.

Round 9:

• Implement mean3x3.
• At corners, use clamped sampling rather than skipping missing neighbors.

95-110 Minutes: Verify Answers

Run:

scripts/apply_answers.sh lesson_4
scripts/run.sh lesson_4 verify
scripts/run.sh lesson_4 demo
scripts/reset_exercises.sh lesson_4

The verifier checks numerical edge cases that are easy to miss by visual inspection alone.

110-120 Minutes: Edge-Case Drill

Try these cases:

• Clamp with equal min and max
• Threshold exactly equal to cutoff
• Pure red, green, blue, black, and white luma
• Normalize a value below and above range
• Blend with alpha 0, 1, and invalid values
• Sample outside each image corner
• Run mean3x3 on a one-pixel image

Reset when done:

scripts/reset_exercises.sh lesson_4

Instructor Notes

Instructor Notes: Lesson 4 Toy Edge Detect Image Preprocess Library

Session Goal

Teach Java library organization through a small image preprocessing library. Learners should understand package layout, matrix-style data structures, grayscale conversion, convolution kernels, Sobel edge detection, file I/O, and numerical helper functions.

Learning Outcomes

By the end of 120 minutes, learners should be able to:

• Explain how BufferedImage data becomes a grayscale matrix.
• Trace a convolution kernel across an image.
• Explain clamping, boundary handling, and Sobel magnitude.
• Run a Java program that writes generated PNG output.
• Implement reusable pixel math helpers.

Before Class

Run:

scripts/reset_exercises.sh lesson_4
scripts/run.sh lesson_4 demo
scripts/run.sh lesson_4 exercise

Open the generated files:

• build/out/lesson_4/synthetic-input.png
• build/out/lesson_4/sobel-edges.png

Know the key files:

• src/demo/java/tutorial/lesson4/demo/EdgeDetectDemo.java
• src/demo/java/tutorial/lesson4/image/ImageMatrix.java
• src/demo/java/tutorial/lesson4/image/Convolution.java
• src/demo/java/tutorial/lesson4/image/EdgeDetector.java
• src/exercise/java/tutorial/lesson4/exercise/PixelMath.java

Minute-By-Minute Plan

Teaching Script

Start with:

"This is a toy library, not a full image framework. That is intentional. The smaller surface lets us see Java package design and numeric processing without extra dependencies."

For ImageMatrix:

• The class owns double[][] values.
• Coordinates are (x, y), while the array is indexed [y][x].
• getClamped handles edges by repeating border pixels.
• toBufferedImage clamps numeric values into displayable byte range.

Checkpoint question:

"What bug would appear if we indexed values[x][y] instead?"

For convolution:

Explain that every output pixel is a weighted sum of neighboring input pixels. The kernel is centered over the current pixel. Boundary handling matters because the kernel extends past the image edge.

For Sobel:

• sobelX responds to vertical edges.
• sobelY responds to horizontal edges.
• Math.hypot(gx, gy) combines gradient components safely.
• The output is clamped because images need a finite display range.

Exercise Facilitation

Learners edit PixelMath.java.

Recommended order:

• Implement clamp and validation.
• Implement byte helpers such as invertGray and threshold.
• Implement luma by extracting red, green, and blue.
• Implement packGray, normalizeToByte, and blend.
• Implement sobelMagnitude using Math.hypot.
• Implement sampleClamped and mean3x3.

Hints:

• "Use bit shifts and masks: red is (rgb >> 16) & 0xff."
• "Round luma before returning."
• "Clamp all display values to 0..255."
• "Validation belongs in helpers because callers will reuse them."

Expected Answer Behavior

After applying answers:

scripts/apply_answers.sh lesson_4
scripts/run.sh lesson_4 verify
scripts/run.sh lesson_4 demo

Expected important lines:

lesson_4 answers verified

The demo should also write:

build/out/lesson_4/synthetic-input.png
build/out/lesson_4/sobel-edges.png

Common Mistakes

• Forgetting that RGB channels are packed into one integer.
• Returning a negative or above-255 grayscale value.
• Confusing x/y coordinates with row/column array indices.
• Using gx * gx + gy * gy without considering overflow for larger values.
• Writing image output before creating the parent directory.

Discussion Prompts

• Should ImageMatrix store double, int, or byte values?
• Should kernels normalize themselves?
• Should boundary strategy be configurable?
• How would you test image code without visually inspecting every PNG?
• Where would a command-line API belong if this became a real library?

Extension Challenge

Ask learners to add a threshold step that turns edge magnitudes above 100 white and everything else black. Then ask whether thresholding should be part of EdgeDetector.sobel, a separate preprocessing function, or a caller option.

Functions In This Lesson

private PixelMath() {

public static int clamp(int value, int min, int max) {

public static int invertGray(int gray) {

public static int threshold(int gray, int cutoff) {

public static int luma(int rgb) {

public static int packGray(int gray) {

public static int normalizeToByte(double value, double min, double max) {

public static int blend(int leftGray, int rightGray, double alpha) {

public static int sobelMagnitude(int gx, int gy) {

public static int sampleClamped(int[][] image, int x, int y) {

public static int mean3x3(int[][] image, int centerX, int centerY) {

private static void requireByte(int value, String name) {

private static void validateImage(int[][] image) {

private EdgeDetectDemo() {

public static void main(String[] args) throws IOException {

private Convolution() {

public static ImageMatrix apply(ImageMatrix input, Kernel kernel) {

private EdgeDetector() {

public static ImageMatrix sobel(ImageMatrix input) {

private ImageIo() {

public static ImageMatrix readGrayscale(Path path) throws IOException {

public static void writeGrayscale(ImageMatrix matrix, Path path) throws IOException {

public ImageMatrix(int width, int height) {

public int width() {

public int height() {

public double get(int x, int y) {

public double getClamped(int x, int y) {

public void set(int x, int y, double value) {

public static ImageMatrix syntheticTestPattern(int width, int height) {

public static ImageMatrix fromBufferedImage(BufferedImage image) {

public BufferedImage toBufferedImage() {

private static int clampToByte(double value) {

public Kernel {

public int width() {

public int height() {

public double at(int x, int y) {

public static Kernel sobelX() {

public static Kernel sobelY() {

public static Kernel boxBlur3() {

private AnswerVerifier() {

public static void main(String[] args) {

private static void expectEquals(int expected, int actual, String label) {

private static void expectThrows(Runnable action, String label) {

private ExerciseRunner() {

public static void main(String[] args) {

private PixelMath() {

public static int clamp(int value, int min, int max) {

public static int invertGray(int gray) {

public static int threshold(int gray, int cutoff) {

public static int luma(int rgb) {

public static int packGray(int gray) {

public static int normalizeToByte(double value, double min, double max) {

public static int blend(int leftGray, int rightGray, double alpha) {

public static int sobelMagnitude(int gx, int gy) {

public static int sampleClamped(int[][] image, int x, int y) {

public static int mean3x3(int[][] image, int centerX, int centerY) {

private PixelMath() {

public static int clamp(int value, int min, int max) {

public static int invertGray(int gray) {

public static int threshold(int gray, int cutoff) {

public static int luma(int rgb) {

public static int packGray(int gray) {

public static int normalizeToByte(double value, double min, double max) {

public static int blend(int leftGray, int rightGray, double alpha) {

public static int sobelMagnitude(int gx, int gy) {

public static int sampleClamped(int[][] image, int x, int y) {

public static int mean3x3(int[][] image, int centerX, int centerY) {