Small object detection for WordPress media libraries

Most tutorials about detector architecture end with the same advice: build it from scratch if you want to understand it. Muhammad Ardi’s walkthrough of the Feature Pyramid Networks paper follows that advice faithfully, with a dummy CNN backbone, an FPN neck and an RPN head typed out in plain PyTorch. As a learning exercise it works. The from-scratch part is the least useful lesson in the piece for anyone arriving from WordPress work, and small object detection, the reason the paper exists, is the part that transfers.

Small object detection fails because of how the backbone is built, and once you can name that reason you start finding it in your own pipeline. WordPress generates thumbnails at upload. Feed a thumbnail to a detector and you recreate the exact problem FPN was designed to fix.

Where small object detection breaks first

Older detectors like YOLOv1 and YOLOv2 predicted everything from the deepest feature map. Every stride-2 layer halves the spatial resolution, so near the end of the network a single activation stands in for a whole patch of neighboring pixels. Semantic content grows as you go deeper, which is what lets the model know a region contains a dog, but the pixel detail a tight bounding box needs is already blended away. Large objects survive that loss, but a small object in the corner of the frame does not.

The brute force fix is the featurized image pyramid: resize the input to several scales, run the network on each, and predict at every scale. It is accurate and expensive, because you pay for the full network once per scale. SSD made the pass cheap by predicting from several internal layers of one run, but the shallow layers it leaned on carry detail without much meaning. FPN closes the gap from the other direction. It takes the deepest, most semantic map, upsamples it by 2x with nearest neighbor interpolation, matches channel counts through a 1×1 conv, adds the result element-wise to the shallow map, and smooths the sum with a 3×3 conv to cut the aliasing that upsampling introduces. Ardi covers each of those steps with code and diagrams, and if the mechanism is new to you, his article is a good way in. The paper itself is short and reads quickly next to it.

What the neck adds, and what it costs

The neck is small. In the paper’s ResNet-50 setup the backbone hands over C2 through C5, every lateral 1×1 conv outputs 256 channels so the tensors can be summed, and the authors state that no nonlinearity is needed inside the neck. In Ardi’s notebook the FPN class is about 30 lines. The abstract’s claim is that all of this comes at marginal extra cost compared to scale pyramids, which is why most detectors shipped since have some version of it.

That smallness is also the argument against writing it for a client. TorchVision ships fasterrcnn_resnet50_fpn with COCO-pretrained weights, and it recognizes the usual 80 categories out of the box. The work left over is input handling, score thresholding and taxonomy plumbing, which is WordPress work rather than ML work.

Wiring it into WordPress without retraining anything

This is where I’d spend the hours, in three steps.

Feed the detector the original file

WordPress makes intermediate sizes at upload. If your integration reads the medium or large thumbnail because it’s faster to send, you have shrunk every object before detection starts. FPN handles scale variation inside the image it receives, and it cannot recover detail that resizing already destroyed. Use wp_get_original_image_path( $attachment_id ) and let the model’s own preprocessing handle sizing (TorchVision’s detection models resize internally before the backbone runs). A 300px thumbnail and the full-size photo are different problems for a detector.

Get inference out of the request

add_attachment fires inside wp_insert_attachment, during the upload request itself. A ResNet-50 forward pass on a full-size image does not belong between the uploader and its success message, and PHP workers on busy shared hosting get killed long before heavy jobs finish. Schedule the work and let a queue or cron own it. Uploads processed entirely client-side can skip your PHP hooks altogether, which I covered separately.

add_action( 'add_attachment', 'bbioon_queue_detection' );

function bbioon_queue_detection( $attachment_id ) {
    $path = wp_get_original_image_path( $attachment_id );

    if ( ! $path ) {
        return;
    }

    wp_schedule_single_event(
        time() + MINUTE_IN_SECONDS,
        'bbioon_run_detection',
        array( $attachment_id, $path )
    );
}

add_action( 'bbioon_run_detection', 'bbioon_run_detection', 10, 2 );

function bbioon_run_detection( $attachment_id, $path ) {
    $response = wp_remote_post( 'http://127.0.0.1:8000/detect', array(
        'timeout' => 30,
        'body'    => array( 'path' => $path ),
    ) );

    if ( is_wp_error( $response ) ) {
        return;
    }

    $data = json_decode( wp_remote_retrieve_body( $response ), true );

    if ( empty( $data['tags'] ) || ! is_array( $data['tags'] ) ) {
        return;
    }

    foreach ( $data['tags'] as $tag ) {
        $tag = sanitize_text_field( $tag );

        if ( '' !== $tag ) {
            wp_set_object_terms( $attachment_id, $tag, 'detected_object', true );
        }
    }
}

Threshold before you write terms

A detector emits a prediction for every anchor. Filter to scores above roughly 0.5 in the service before anything touches the database, or the noise becomes permanent taxonomy terms. Then append to a dedicated taxonomy you registered on init, so detected objects stay separate from editorial tags. If you want to see where this kind of auto-tagging goes once it grows real features, the AI tagging plugin notes cover the later stages.

When the from-scratch version still matters

I’d still type the walkthrough’s code once, just not for the architecture. When a pretrained model returns junk on your images, you need to know which side to blame. If the objects are small in the frame and your input was a thumbnail, their boxes never reached a pyramid level that could represent them, and the fix is the input. If COCO has never seen a bracelet clasp, no input size saves you, and you are into fine-tuning: replacing the predictor head and training on your own annotations. Knowing the pyramid levels by name makes that diagnosis fast, and that’s the real return on the exercise.

If you’re weighing this for a store, I’m glad to look at the media pipeline and work out where detection should run and what each upload will cost in time and memory. It’s cheaper to settle that before the library grows than to retrofit a queue through a live site.

The question I still can’t answer cleanly is where inference should physically live. Shared hosting can’t run PyTorch, a small Python service on the same box is one more process most hosts won’t babysit, and a hosted vision API makes per-upload cost predictable in exchange for an external dependency on every upload. That choice shapes the running cost and the failure modes of the whole feature more than anything inside the FPN paper does, and the paper never had to think about it.

author avatar
Ahmad Wael
I'm a WordPress and WooCommerce developer with 15+ years of experience building custom e-commerce solutions and plugins. I specialize in PHP development, following WordPress coding standards to deliver clean, maintainable code. Currently, I'm exploring AI and e-commerce by building multi-agent systems and SaaS products that integrate technologies like Google Gemini API with WordPress platforms, approaching every project with a commitment to performance, security, and exceptional user experience.

Leave a Comment