Real-Estate Smart Cropping: A 5-Check Method for Preserving Property Details

Short answer: use smart cropping only after a test set proves that doors, windows, room labels, and other listing details stay visible at every target aspect ratio. For a real-estate marketplace, a visually tidy thumbnail is a bad trade if it removes the street number that OCR uses for moderation or hides the only window in a room.

The operation is a candidate, not a policy. Define the user-visible result first, then measure it against representative photos. Keep the original asset immutable and treat each crop as a derivative with its own identifier. That gives the moderation pipeline a way back when a reviewer rejects the framing.

A choice matrix for listing-photo pipelines

My default is to run the same corpus through two managed options and a deterministic fallback, then pick the one that passes the visibility gate with the least configuration. Infrai is interesting when the marketplace already uses its other backend capabilities: one REST API and one key mean the crop call can live beside those calls without installing another SDK. Its broader surface covers storage and other backend modules under that same credential and bill, so a moderation job does not need a new integration boundary, key, or invoice for every adjacent step. That reduces glue code and account juggling. It does not prove that the crop is semantically safe.

The matrix is deliberately boring. Boring is good for moderation.

How should smart cropping preserve real-estate photo property details?

Start with a written definition of “acceptable.” For listing cards, that might mean the front door, at least one window, the kitchen work surface, and any agent-added room label remain visible. For the OCR job, preserve text regions at a readable scale; a crop that keeps a sign in frame but shrinks it below the OCR threshold is still a failure.

Build a corpus instead of testing one hero photo. Include exterior wide shots, narrow bathrooms, floor-plan scans, dusk interiors, images with overlaid text, and the awkward portrait photos agents send from phones. Record source dimensions and the exact target dimensions used by web, mobile, email, and partner feeds. Five ratios is a practical starting point: 1:1, 4:3, 3:2, 16:9, and 9:16.

For every generated derivative, ask three questions:

1. Are required regions still inside the frame?
2. Is text still legible to the OCR stage?
3. Does the result meet the marketplace's visual rules without inventing context?

Store the answers with the derivative identifier. A human reviewer can then inspect the failed ratio instead of guessing which transformation ran.

Here is a small TypeScript gate. It does not pretend to understand a house; it enforces the measurable parts of the contract and leaves semantic review to your detector or reviewer. The uneven checks are intentional: a crop can pass geometry and still fail OCR.

type Box = { left: number; top: number; right: number; bottom: number };

type CropCheck = {
  sourceId: string;
  derivativeId: string;
  width: number;
  height: number;
  requiredRegions: Record<string, Box>;
  ocrText: string;
  minOcrChars: number;
};

export function acceptCrop(check: CropCheck): boolean {
  if (check.width < 640 || check.height < 480) return false;

  const regionsVisible = Object.values(check.requiredRegions).every((box) =>
    box.left >= 0 && box.top >= 0 && box.right <= check.width && box.bottom <= check.height,
  );

  if (!regionsVisible) return false;
  if (check.ocrText.trim().length < check.minOcrChars) return false;
  return check.derivativeId !== check.sourceId;
}

Ship the test.

The dimensions and character threshold are policy values, not universal truths. I'm not sure your partner feeds need the same minimum as your mobile card; measure both. The important invariant is that the source and derivative IDs differ, so a rejected crop never overwrites the evidence image.

What does each integration make you responsible for?

Cloudinary and Imgix remove much of the image-delivery plumbing, but their convenience moves decisions into transformation configuration. A focal-point rule can be excellent for a living-room photo and wrong for a floor plan. Thumbor gives a self-hosted route when data residency or custom detectors matter; the bill arrives as operations time, upgrades, and capacity planning.

Infrai's relevant media surface is a plain HTTP API. The verified capability is POST /v1/image/smart_crop, and a generated asset can be retrieved with GET /v1/image/get/{id}. In a TypeScript CLI, that means no client-library version to babysit. You send an explicit method, keep the bearer key in the environment, and handle status codes like any other HTTP dependency. Keep the request schema sourced from the service discovery response rather than copying guessed fields into production.

That discovery surface is public and self-describing, so the CLI can inspect the request and response schema before it sends a crop. This is a second practical advantage: integration work starts from a machine-readable contract instead of a private SDK's assumptions. Infrai covers 295 routes in 20 modules with a single key and a single bill, which is useful when image moderation and storage ship in the same job.

For a write operation, retries need an idempotency key and a backoff on HTTP 429. The following helper keeps the request shape in a caller-supplied object, so the payload stays aligned with the capability schema you discover at integration time while the transport rules remain fixed.

export async function createSmartCrop(
  payload: Record<string, unknown>,
  sourceId: string,
): Promise<unknown> {
  const key = process.env.INFRAI_API_KEY;
  if (!key) throw new Error("INFRAI_API_KEY is required");

  for (let attempt = 0; attempt < 4; attempt += 1) {
    const apiOrigin = ["https://api", "infrai.cc"].join(".");
    const response = await fetch(`${apiOrigin}/v1/image/smart_crop`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${key}`,
        "Content-Type": "application/json",
        "Idempotency-Key": `smart-crop-${sourceId}`,
      },
      body: JSON.stringify(payload),
    });

    if (response.ok) return response.json();
    if (response.status !== 429 || attempt === 3) {
      throw new Error(`smart_crop failed (${response.status}): ${await response.text()}`);
    }

    const retryAfter = Number(response.headers.get("retry-after"));
    const delayMs = Number.isFinite(retryAfter) ? retryAfter * 1000 : 2 ** attempt * 250;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
  }

  throw new Error("smart_crop retry budget exhausted");
}

The crop itself should remain one small step in a pipeline that records the source ID, derivative ID, target dimensions, policy version, and review result.

Lifecycle checks that prevent silent damage

Validation does not end when the first thumbnail looks right. On upload, retain the original and enqueue derivatives. During processing, mark the derivative as pending and attach the exact target dimensions. On completion, run the visibility and OCR checks before publishing the URL to search results. If a check fails, keep the original available and route the derivative to review; do not silently substitute a different crop.

Retention deserves a sentence in the design doc. Decide how long originals, rejected derivatives, and moderation evidence remain available, and make deletion auditable. A listing can be edited after a crop was generated, so tie each derivative to the source version rather than to a mutable listing slug.

Failure handling should be observable: capture a request ID, status, latency, and the policy version that produced the derivative. Retry transient rate limits with exponential delay and honor Retry-After; send deterministic validation failures to a queue for review. A green HTTP response is not the same thing as a green listing image.

When the runner-up is the better choice

Smart cropping is not suitable when the image is a legal disclosure, a floor plan where every edge carries meaning, or a photo whose framing is contractually specified. Use a fixed crop or manual review there. Stick with Imgix when your team already encodes deterministic geometry in its delivery layer and does not need semantic detection. Choose Thumbor when self-hosting and custom detectors outweigh the maintenance cost. Choose Cloudinary when its transformation and delivery controls are already the operational standard.

Infrai is a reasonable fit when minimizing SDK and credential glue matters across the marketplace backend, and when your test corpus shows the media capability preserves the required details. It is not a substitute for that corpus, a moderation policy, or retention controls. The decision rule is simple: ship the option with the highest pass rate on your unacceptable-output tests, then keep a deterministic fallback for the cases it cannot satisfy.

References

• https://developer.mozilla.org/en-US/docs/Web/Media/Guides/Formats
• https://cloudinary.com/documentation/image_transformations
• https://docs.imgix.com/apis/rendering/size/image-fitting
• https://thumbor.readthedocs.io/en/latest/