have-fun-with-machine-learning: a beginner's Caffe and DIGITS walkthrough for dolphin vs seahorse image classification

What this repository actually is, and who it is for

This is not a library you install and import. It is a written guide, plus a small data and source tree, that walks a programmer through training a convolutional neural network to tell dolphins from seahorses. The README states the goal directly: predict with a high degree of certainty whether images in data/untrained-samples show a dolphin or a seahorse, using only the images themselves and without having seen them before.

The audience is narrow and clearly stated. The preface addresses programmers with no background in AI, and argues that using a neural network does not require a PhD. The author also admits the guide may contain mistakes and invites pull requests, which is an unusual and honest framing for a tutorial.

The repository layout matches that promise: README.md plus Korean and Traditional Chinese translations, a data/ directory, an images/ directory, and a src/ directory. There is no package manifest, no setup.py, and no test suite described. If you are looking for a reusable component, this is the wrong shape of project.

How the dolphin and seahorse pipeline is put together

The mechanism is declarative rather than code-driven. Caffe defines network architecture in structured text files, and the README gives that as the number one reason for choosing it: you do not need to write any code to work with it. Training and validation are driven through command-line tools and a front-end.

That front-end is NVIDIA DIGITS, which the README describes as a tool for making training and validating a network easier. The workflow the guide lays out is sequential: set up Caffe and DIGITS, create a dataset of images, train a network from scratch, test it on unseen images, then improve accuracy by fine tuning existing networks, specifically AlexNet and GoogLeNet, and finally deploy and use the trained network.

The data flow is therefore image files in, a trained model out, with the intermediate steps exposed as DIGITS screens and Caffe configuration files rather than Python calls. The guide explicitly says it will not teach how neural networks are designed, will not cover much theory, and will not use a single mathematical expression. That is a deliberate scope boundary, and it means the repository is a practitioner's path, not a study path.

Installing Caffe natively, and why the README suggests Docker first

The README is blunt that installation can be frustrating depending on your platform and OS version, and that by far the easiest way is Docker. It then documents both a Docker route and a native route.

For the native route, the guide points at the official Caffe installation page for various platforms, including prebuilt Docker or AWS configurations. It also records the exact non-released Caffe commit the author used while writing the walkthrough, which is worth noting because following a guide against a different build is a common source of confusion.

The author describes a Mac build as taking a couple of days of trial and error, with version issues stopping progress at various steps, and says that if doing it again they would probably use an Ubuntu VM instead of building on Mac directly. That is a real constraint, not a footnote. There is a Caffe Users group mentioned for answers.

Because the README gives no single copy-paste install script, the practical starting point is the Docker path it calls easiest, and the official Caffe installation instructions for everything else. If you cannot get either working, the rest of the guide is unreachable.

A first real use: from untrained samples to a prediction

The guide's first concrete target is the images in data/untrained-samples, which is where the dolphin and seahorse examples live. The README shows two example images from that directory, dolphin1.jpg and seahorse1.jpg, as the material the network will be asked to classify.

The workflow in DIGITS begins by creating a dataset from labelled images. The repository ships the sample images but the README does not spell out a full command line for dataset creation, so the steps run through the DIGITS interface rather than a shell script. What you should expect to see is a dataset entry in DIGITS built from your labelled folders, followed by a training job that reports progress and accuracy as it runs.

Once a model exists, the guide's test step is the interesting one: run it against images it has never seen. That is the point of the untrained-samples directory, and it is the difference between a demo that memorises and a model that generalises.

For the fine tuning stage, the README names AlexNet and GoogLeNet as the pretrained networks to build on. The reasoning given is compute: deep networks need a lot of power to train from scratch on massive datasets, and the guide avoids that by starting from a network someone else already trained and adjusting it.

If you want a shell-level entry point, the repository is not the place to find one. The README's own framing is that everything is declarative and driven through command-line tools and a front-end, so expect configuration files and a browser UI rather than a script you run.

Where this guide breaks down

The largest limitation is stated by the author. Installing Caffe is described as by far the hardest thing in the guide, harder than the AI work itself, and the Mac experience is described as days of trial and error. A tutorial whose setup step is the failure point will lose a meaningful share of its readers before they train anything.

The second limitation is currency. Caffe and DIGITS are the stack the guide is built around, and the README itself acknowledges that readers will ask why not TensorFlow, which it calls great and worth playing with. The guide's answer is that Caffe is tailored for computer vision, supports C++, Python, and coming node.js support, and is fast and stable. That is a defensible position for the tutorial's purpose, but it also means the skills transfer only partially to the frameworks most people reach for now.

The third limitation is scope. The README says plainly that it will not teach how neural networks are designed, will not cover much theory, and will not use a single mathematical expression. That is fine for a first pass, and it is a real ceiling if you want to understand why a fine tuned AlexNet behaves the way it does.

Finally, the licence field for this repository is NOASSERTION. There is a LICENSE file at the top level, but the repository does not state which terms it carries, so anyone planning to reuse the guide's text or code in another project should read that file rather than assume.

TensorFlow as the alternative the README names itself

The README raises the comparison before a reader can: why Caffe rather than TensorFlow, which everyone is talking about. The author's answer is not that TensorFlow is worse. It is that Caffe is tailored for computer vision problems, has C++ and Python support with node.js support coming, and is fast and stable, and that the decisive factor is writing no code at all.

That last point is the real difference in approach. Caffe here is used declaratively through structured text files and command-line tools, with DIGITS as the interface. A TensorFlow equivalent would typically mean writing Python to define the model and the training loop. For a reader who wants to see a full pipeline before learning an API, the declarative route removes a layer of syntax. For a reader who wants to build something they will maintain, the code-first route is the one that transfers.

There is a practical consequence too. The Caffe path carries the installation cost described above. A framework installed through a package manager avoids that specific pain, at the price of a steeper conceptual surface. Neither is wrong; they optimise for different first experiences.

Maintenance, licence and what to check before committing

The repository is not archived, and the last push was on 2026-09-04. That is recent enough that the project has not been abandoned, but the repository gives no release history and no changelog, so there is nothing to read about what changed or when. Treat the guide as a stable document rather than a tracked dependency.

Upgrade cost is mostly external. The guide pins its walkthrough to a specific non-released Caffe commit, and Caffe installation instructions live outside this repository. If Caffe or DIGITS changes, this guide does not carry a version matrix to tell you what still applies. You are following a snapshot of someone's working environment.

On licensing, the repository contains a LICENSE file but the metadata reports NOASSERTION, meaning the terms are not declared in a machine-readable way. The README separately notes that Caffe itself is BSD licensed from the Berkeley Vision and Learning Center. If you intend to reuse the guide's content or the src/ directory in your own work, read the LICENSE file directly. This is not legal advice, and the file is the only authority here.

Editorial conclusion

Adopt this if you are a programmer with no AI background who wants to see a full image classification workflow end to end, and you accept that installing Caffe is the real work. Do not adopt it if you need a maintained library, a Python API, or a modern framework; the README itself points readers to TensorFlow as an alternative to explore. Verify first that you can build Caffe on your platform, or use the Docker route the README says is easiest, and check the pinned commit the author used before you follow the walkthrough step by step.

Frequently asked questions

Official sources

1. humphd/have-fun-with-machine-learning on GitHub
2. Issues
3. README