Skip to content
CLEARER IDEAS. BETTER EXECUTION.PROGRAMMING · CREATIVE AI · WORKFLOWS
Menu & topics
Programming

File Hashes Differ but Pixels Match: Define a Decoded Image Identity

Original code, local tests and clear limits for Pillow PNG pixel hash metadata difference. Separate observed results from proposed integration.

Two prints of a red ceramic bowl in pale oak and dark frames beside a memory card case on a worktable
Two prints of a red ceramic bowl in pale oak and dark frames beside a memory card case on a worktable.
The short answerTwo PNG files can have different file bytes while decoding to the same RGBA samples. This project hashes a version label, dimensions and decoded sample bytes for a narrowly defined pixel identity. Nine synthetic tests separate metadata changes from sample changes; this is not a perceptual or color-managed image comparison.

Two PNG byte streams, one decoded sample sequence

The first pair in this project is deliberately small: two PNG files made from the same two-pixel RGBA image, with a text note containing a in one file and b in the other. Their encoded file hashes differ. Their pixel_id values match. Both statements come from the actual synthetic fixtures, and the files are retained with the project. There is no contradiction between the results. One operation identifies an encoded file, while the other identifies a decoded representation under a contract we define in the helper.

This distinction can help diagnose an image-project report such as a changed asset hash after a metadata edit. Before changing the hash function, ask what the application meant by the same image. The original file is not byte-for-byte the same when its metadata changes. Its decoded RGBA samples can nevertheless match under this specific conversion. A cache concerned with those samples may have a different requirement from an archive preserving the source file, its metadata and its history. A single unspecified field named image_hash conceals that decision.

The lead photograph shows two prints of a red ceramic bowl in pale oak and dark frames beside a memory-card case. The prints illustrate comparison, but they are not the paired synthetic PNG outputs and are not evidence of pixel equality. The runnable checks use tiny solid-color images built by the supplied test helper. Keeping the editorial photograph separate from those fixtures makes the experiment reproducible: a reader can inspect the exact colors, dimensions and metadata instead of trying to infer equality from similar-looking photographic props.

Read the identity function as a format contract

The helper opens an in-memory byte sequence with Pillow, checks that the decoded source format is PNG, and converts the image to RGBA. That conversion selects the sample representation used for identity. The function then builds a payload from a literal version label, a zero byte, the width and height packed as two big-endian unsigned integers, and the raw sample bytes returned by image.tobytes. Finally, it returns the SHA-256 hexadecimal digest of that payload. None of those steps calculates a perceptual similarity score or compares a subject recognized in a photograph.

Image.tobytes returns raw pixel data for the current image representation; this differs from the bytes of an encoded PNG file. Pillow Image.tobytes reference

The label rgba-pixels-v1 belongs to our own helper. It is not a claim that this is an industry-standard image identifier. Including the label makes the chosen representation visible in the input to the digest, while the fixed-width dimensions describe how those samples are arranged. If the application later chooses a different representation, such as a background-composited image or a resized preview, it should give that new contract a distinct identity. Reusing the same label after changing the payload semantics would make historical comparisons difficult to interpret.

The PNG-only check is also an application choice. It does not mean Pillow cannot read JPEG, nor does it mean all PNG metadata has been removed from the original input. The function reads the encoded source and hashes a derived payload; it does not rewrite or sanitize the uploaded file. test_non_png_refused supplies a JPEG fixture and expects ValueError. test_bad_bytes supplies invalid bytes and expects UnidentifiedImageError. Those selected cases document this wrapper, not every malformed image, resource-exhaustion condition or possible decoder error.

pixel_ids.py

from io import BytesIO
import hashlib,struct
from PIL import Image

def pixel_id(blob):
    with Image.open(BytesIO(blob)) as source:
        if source.format!='PNG':raise ValueError('This fixture accepts PNG only')
        image=source.convert('RGBA')
        payload=b'rgba-pixels-v1\0'+struct.pack('>II',*image.size)+image.tobytes()
        return hashlib.sha256(payload).hexdigest()

Nine final local unittest methods passed on Python 3.12.3 for Windows with Pillow 12.3.0. The fixtures are tiny synthetic PNGs, with seven actual outputs retained separately. The initial failed test-module import is preserved in the history. No perceptual, browser, animation or performance comparison was run.

Metadata changes explain the first pair without rewriting history

The test helper creates an RGBA image with dimensions 2 by 1 and a fixed color, then uses PngInfo to add a text note before saving to an in-memory PNG. Changing the note from a to b is enough to make the file bytes differ in the fixture. test_metadata_changes_file_hash hashes the encoded PNG bytes directly and asserts that the digests differ. test_metadata_keeps_pixel_id passes those two encoded files through the helper and asserts equal identities. These are separate assertions about separate inputs to SHA-256.

Seven actual synthetic PNG outputs are saved under the example's fixtures directory: the two metadata variants, a changed-red sample, two alternative dimensions and two hidden-red samples with zero alpha. evidence-results.json records each filename, encoded length, encoded file hash and pixel identity from the actual helper. The saved files let a reader check the pair used in the discussion. Their role is technical evidence for the small example; they are not alternate lead photographs or outputs of a generation model.

Other encoding changes might also be relevant in a real asset workflow, but we did not run a PNG-compression-settings comparison here. Do not turn the metadata test into a claim that every possible re-encoding was measured. When investigating an actual changed file, retain both originals and inspect the operation that produced the second one. A matching pixel identity can answer the defined sample question, while the distinct file hash remains useful for identifying which encoded artifact was received, stored or delivered. Neither result cancels the other record.

Dimensions prevent two arrangements from becoming one identity

The function includes width and height before the raw RGBA bytes because sample bytes alone do not describe their arrangement. Our fixture uses the same solid color in a 1-by-2 image and a 2-by-1 image. Both contain two samples, but their shapes differ. test_dimensions_part_of_identity expects different pixel_id results. This is a compact counterexample to a helper that simply hashes tobytes without any shape contract. It makes a horizontal strip and a vertical strip distinguishable even when every sample has the same value.

The dimensions are packed with the explicit >II format, rather than a casual concatenation of decimal strings. That provides two fixed-width values with a defined byte order in this payload. This detail is part of the implementation being tested; the article does not propose that every system must use this exact format. If you reproduce the identity elsewhere, you must reproduce the same label, separator, dimension packing and RGBA sample sequence. Merely choosing the same digest algorithm is not enough to produce the same identifier.

A proposed manifest can store width and height alongside the digest for inspection even though they also contribute to the payload. That makes a report easier to understand when two outputs differ in shape. It does not require guessing whether a mismatch came from dimensions or a sample value by examining the hexadecimal digest. The current helper returns only a string and does not create such a manifest. Keeping the inspectable representation fields in a caller is a proposed integration, separate from the equality assertions in the local suite.

Alpha and hidden RGB make the equality decision explicit

The chosen RGBA representation includes all four channel values. test_alpha_changes_identity changes the alpha value from 255 to 254 and expects a different identity. test_changed_pixel_color changes the red component and also expects a different result. These cases document what enters the payload. They do not establish whether a person viewing the images at a particular size would notice a difference, or whether a browser would render them distinguishably against a chosen background. The helper is not a visual-quality measurement.

The less obvious case is test_hidden_rgb_still_counts. It compares colors with different red values while both have alpha zero. The raw RGBA samples still differ, and the test expects different identities. That result is intentional under our contract. A displayed composite may hide RGB values where alpha is zero, but the helper has not composited the image. Do not describe this identity as matching every image that appears identical to a viewer: the transparent samples provide a direct local reason why that would be an incorrect claim.

If the proposed application cares about the result over a fixed white background, it could define a separate transformation and identity for that representation. The existing guide to transparent PNG compositing addresses that different operation. Decide the background, output mode and other transformation details before comparing its output. This project did not run a browser comparison or a range of compositing backgrounds. Our saved hidden-red fixtures preserve the original sample distinction rather than silently normalizing away values that another consumer might still need.

Nine methods passed after a test-source correction

The final suite contains nine methods: the two metadata cases, changed pixel color, dimensions, hidden RGB, alpha, repeat-call equality, non-PNG refusal and invalid bytes. test_repeat_call runs pixel_id twice for the same fixture and asserts equal results. That checks repeatability of this input in the recorded environment. It does not prove that any decoder version, color pipeline or future modification will produce the same representation. The function and its test module therefore have their own retained source hashes in addition to the sample-file evidence.

An initial version of the test module contained unmatched closing parentheses in two assertions. The loader could not import it, so that attempt was an error rather than a passing pixel test. We corrected the test syntax and retained the failed source and output before running the final nine methods successfully. The helper implementation did not need a pixel-algorithm change to fix that import error. Distinguishing a test-module failure from a failed assertion prevents the record from inventing an algorithm defect or claiming that the first run passed.

The measured environment is Python 3.12.3 on Windows with Pillow 12.3.0. The current online Image reference consulted for the concise tobytes definition identifies Pillow 13.0.0; it is not the version we ran. The actual run record supplies the tested environment. If you repeat the experiment on another version, record that version and compare the retained fixtures before asserting compatibility. This article contains no timing results, decoder-version benchmark, real photographic duplicate-detection rate or image-generation model comparison.

Choose manifest fields for the artifact you must preserve

A proposed asset manifest can give the two identities separate names, such as file_sha256 and rgba_pixel_id, and store the pixel contract label with the latter. It can also retain original_path, dimensions, decoder version and the operation that produced a derived artifact. These fields serve different questions. file_sha256 can identify the exact file delivered to storage. rgba_pixel_id can identify the helper's decoded sample payload. The path identifies where a particular artifact is kept. None should silently overwrite another because their current values happened to agree on one simple fixture.

A metadata edit creates an especially useful manifest scenario. The two source files remain distinct artifacts even when their pixel identities match. If the application needs captions, embedded notes, provenance or the original encoded file, reusing one entire file solely because a sample identity matched could discard information it intended to preserve. Our fixture changes only a small note, but it makes that decision visible. A proposed cache may reuse a pixel-derived computation while still retaining both source records and their separate encoded hashes.

Matching identities should also not trigger automatic deletion of an asset without the application's own retention policy. A digest is an identifier under its input contract, not an instruction about ownership or which file a user wanted to keep. The helper does not choose a canonical source, merge catalog records or resolve conflicting metadata. A proposed duplicate-review interface could present both artifact records with the two identity fields and ask for an explicit decision. No such interface or deletion workflow was built or tested as part of this example.

Orientation, color and resizing are separate transformations

Converting to RGBA selects a channel representation, but this helper does not call an EXIF-transpose routine, perform an ImageCms color-management conversion, resize a preview or composite against a background. If an application intends equality after one of those transformations, it needs to define that operation before hashing. The current identity should be read literally: PNG opened by this Pillow environment, converted to RGBA, with dimensions and sample bytes. Do not rename it visual_identity and assume that the missing operations are somehow implied by that name.

For a proposed thumbnail cache, the required contract may include target dimensions, a fit rule, orientation handling, resampling choices and background treatment in addition to source identity. Those are design inputs, not measured properties of our helper. A source-level pixel match alone cannot tell the caller whether a previously cached preview was created with the same choices. Retain the transformation settings alongside the cached result so that a future comparison can identify what was actually requested rather than inferring it from a matching source digest.

The function also does not iterate through an animation's frames. Its source contains one conversion of the opened image and one sample payload. It should therefore not be presented as a complete animated-PNG identity. We did not create or test an animation fixture. A proposed animation-aware design would need to specify frame selection, durations and other relevant sequence information, then build separate assertions for that representation. The same caution applies to any image property outside the bytes deliberately included in the current payload.

Reproduce the saved fixtures without treating the photo as a test

Save pixel_ids.py and test_example.py in one directory with a compatible Pillow installation, then inspect the fixture helper before running it. The module creates tiny synthetic images in memory; it does not read a user photo or rewrite the lead image. From your copy, python -m unittest discover -s . -p test_example.py -v runs the nine methods. This is a reproduction instruction. The saved execution record uses the actual interpreter and absolute discovery path from our local run, rather than pretending that every reader has the same folder layout.

The fixture evidence is useful when you want to inspect outputs independently of the assertions. Compare metadata-a.png with metadata-b.png for encoded identity versus decoded identity, one-by-two.png with two-by-one.png for dimensions, and hidden-red-1.png with hidden-red-2.png for RGB under zero alpha. Use the recorded fields in evidence-results.json to check which equality was observed. A normal image viewer may not reveal the hidden-channel distinction, so a visually identical display is not a substitute for inspecting the sample contract used by the function.

When modifying the helper, keep the old fixture outputs and source revision available. A change from RGBA samples to a white composite should produce a new named contract and its own tests instead of silently replacing the current evidence. Likewise, correcting a failed test-source import should not be recorded as a successful earlier run. The purpose of retaining artifacts is to let a later reader explain why two identifiers matched or differed using the actual files and code, without relying on a general statement that an image looked unchanged.

Inspect the payload before interpreting a digest mismatch

For the retained metadata-a.png fixture, we also inspected the payload assembled by the helper. The version label and its zero-byte separator occupy 15 bytes. The packed dimensions occupy 8 bytes, with values 0, 0, 0, 2 followed by 0, 0, 0, 1 for width 2 and height 1. The two RGBA samples occupy another 8 bytes: 200, 10, 20, 255 repeated twice. The complete payload therefore has 31 bytes. A separate recorded inspection recomputed its digest and confirmed that it matches the original helper for this file.

That inspection is one additional recorded check, not a tenth unittest method. It helps explain what the digest summarizes without treating the hexadecimal output as a description of the image. The 31 bytes are not the encoded PNG and do not include the note text or PNG container structure. Changing a or b in that note changes the encoded artifact while leaving these particular samples and dimensions the same. Conversely, exchanging the width and height changes the packed dimension bytes even when the sample sequence remains the same solid color.

For a proposed diagnostic tool, report the contract name, mode, dimensions and sample length beside the identity before displaying a mismatch. Those inspectable fields can reveal that two callers prepared different representations. They do not recover the original image from its digest, and they do not prove visual equivalence. The current helper returns only the hexadecimal identifier; the small payload-layout record was produced separately for this fixture. If you add an inspection endpoint to an application, decide which derived fields it should expose rather than returning arbitrary source metadata or private file paths.

Define the next check before expanding the claim

A next compatibility check could run the retained synthetic inputs through another deliberately selected decoder environment and compare the resulting payload identities. That is proposed future work, not a completed result here. Specify the decoder version and conversion contract before interpreting any difference. A changed digest might reflect changed representation behavior or changed code, while an equal digest says only that the defined payloads produced equal identifiers in that check. Neither result alone establishes equivalent appearance on every display or proves that no other metadata changed.

A deployment-facing wrapper would also need a resource policy for the files it accepts. Our helper does not add a complete upload-size, dimension or memory-use boundary. The nine small fixtures cannot demonstrate safe handling of arbitrary untrusted image files. Decide where such limits belong in the proposed input pipeline and test them there, rather than attaching a broad safety claim to a successful SHA-256 call. This limitation concerns the surrounding service; it does not invalidate the small metadata and sample-identity distinctions the current tests actually demonstrate.

For the immediate debugging task, report both questions explicitly: did the encoded file change, and did the defined decoded sample payload change? Retain the originals, the helper contract and the measured environment with the result. The metadata pair answers yes to the first and no to the second, while the dimensions and hidden-RGB pairs explain why other plausible definitions would differ. That gives an image project a concrete basis for choosing its identifiers without claiming a perceptual comparison, a field photograph experiment or a universal duplicate detector.

test_example.py

from io import BytesIO
import unittest,hashlib
from PIL import Image,UnidentifiedImageError
from PIL.PngImagePlugin import PngInfo
from pixel_ids import pixel_id
def png(size=(2,1),color=(200,10,20,255),note=''):
 image=Image.new('RGBA',size,color);info=PngInfo();info.add_text('note',note);out=BytesIO();image.save(out,format='PNG',pnginfo=info);return out.getvalue()
class PixelTests(unittest.TestCase):
 def test_metadata_changes_file_hash(self):self.assertNotEqual(hashlib.sha256(png(note='a')).digest(),hashlib.sha256(png(note='b')).digest())
 def test_metadata_keeps_pixel_id(self):self.assertEqual(pixel_id(png(note='a')),pixel_id(png(note='b')))
 def test_changed_pixel_color(self):self.assertNotEqual(pixel_id(png()),pixel_id(png(color=(201,10,20,255))))
 def test_dimensions_part_of_identity(self):self.assertNotEqual(pixel_id(png((1,2))),pixel_id(png((2,1))))
 def test_hidden_rgb_still_counts(self):self.assertNotEqual(pixel_id(png(color=(1,0,0,0))),pixel_id(png(color=(2,0,0,0))))
 def test_alpha_changes_identity(self):self.assertNotEqual(pixel_id(png()),pixel_id(png(color=(200,10,20,254))))
 def test_repeat_call(self):self.assertEqual(pixel_id(png()),pixel_id(png()))
 def test_non_png_refused(self):
  out=BytesIO();Image.new('RGB',(2,1)).save(out,format='JPEG')
  with self.assertRaises(ValueError):pixel_id(out.getvalue())
 def test_bad_bytes(self):
  with self.assertRaises(UnidentifiedImageError):pixel_id(b'not png')

Prepared with AI assistance and automated reviews. The original code was run locally within the recorded test scope. The lead image is illustrative; it is not a field photograph or evidence of a browser, spreadsheet or video test.