├── .github
└── workflows
│ └── rust.yml
├── .gitignore
├── Cargo.toml
├── LICENSE
├── README.md
├── src
├── image.rs
└── lib.rs
└── tests
└── stats.rs
/.github/workflows/rust.yml:
--------------------------------------------------------------------------------
1 | name: Rust
2 |
3 | on:
4 | push:
5 | branches: [ "main" ]
6 | pull_request:
7 | branches: [ "main" ]
8 |
9 | env:
10 | CARGO_TERM_COLOR: always
11 |
12 | jobs:
13 | build:
14 |
15 | runs-on: ubuntu-latest
16 |
17 | steps:
18 | - uses: actions/checkout@v4
19 | - name: Build
20 | run: cargo build --verbose
21 | - name: Run tests
22 | run: cargo test --verbose
23 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | /target
2 | /Cargo.lock
3 | .idea/
4 | *.iml
5 | *.jpg
6 | .DS_Store
--------------------------------------------------------------------------------
/Cargo.toml:
--------------------------------------------------------------------------------
1 | [package]
2 | name = "image-match"
3 | version = "0.2.4-dev"
4 | edition = "2021"
5 | description = "Derives an image signature to be used in quick image comparisons"
6 | license = "GPL-3.0"
7 | homepage = "https://alt-text.org"
8 | repository = "https://github.com/alt-text-org/image-match-rs"
9 | documentation = "http://www.cs.cmu.edu/~hcwong/Pdfs/icip02.ps"
10 | keywords = ["image", "similarity", "vector", "signature"]
11 |
12 | [dependencies]
13 | image = { version = "0.24.6", optional = true}
14 | num = "0.4.0"
15 |
16 | [features]
17 | img = ["image"]
18 |
19 | [dev-dependencies]
20 | pretty_assertions = "1.4.0"
21 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | The implemented paper is available for free from the location linked
2 | in the README. The sections of that paper in the comments around the
3 | primary logic of signature generation are wholly owned by the authors,
4 | with a belief that our presentation of that text is fair use.
5 |
6 | All other content is licensed as follows:
7 |
8 | GNU GENERAL PUBLIC LICENSE
9 | Version 3, 29 June 2007
10 |
11 | Copyright (C) 2007 Free Software Foundation, Inc.
12 | Everyone is permitted to copy and distribute verbatim copies
13 | of this license document, but changing it is not allowed.
14 |
15 | Preamble
16 |
17 | The GNU General Public License is a free, copyleft license for
18 | software and other kinds of works.
19 |
20 | The licenses for most software and other practical works are designed
21 | to take away your freedom to share and change the works. By contrast,
22 | the GNU General Public License is intended to guarantee your freedom to
23 | share and change all versions of a program--to make sure it remains free
24 | software for all its users. We, the Free Software Foundation, use the
25 | GNU General Public License for most of our software; it applies also to
26 | any other work released this way by its authors. You can apply it to
27 | your programs, too.
28 |
29 | When we speak of free software, we are referring to freedom, not
30 | price. Our General Public Licenses are designed to make sure that you
31 | have the freedom to distribute copies of free software (and charge for
32 | them if you wish), that you receive source code or can get it if you
33 | want it, that you can change the software or use pieces of it in new
34 | free programs, and that you know you can do these things.
35 |
36 | To protect your rights, we need to prevent others from denying you
37 | these rights or asking you to surrender the rights. Therefore, you have
38 | certain responsibilities if you distribute copies of the software, or if
39 | you modify it: responsibilities to respect the freedom of others.
40 |
41 | For example, if you distribute copies of such a program, whether
42 | gratis or for a fee, you must pass on to the recipients the same
43 | freedoms that you received. You must make sure that they, too, receive
44 | or can get the source code. And you must show them these terms so they
45 | know their rights.
46 |
47 | Developers that use the GNU GPL protect your rights with two steps:
48 | (1) assert copyright on the software, and (2) offer you this License
49 | giving you legal permission to copy, distribute and/or modify it.
50 |
51 | For the developers' and authors' protection, the GPL clearly explains
52 | that there is no warranty for this free software. For both users' and
53 | authors' sake, the GPL requires that modified versions be marked as
54 | changed, so that their problems will not be attributed erroneously to
55 | authors of previous versions.
56 |
57 | Some devices are designed to deny users access to install or run
58 | modified versions of the software inside them, although the manufacturer
59 | can do so. This is fundamentally incompatible with the aim of
60 | protecting users' freedom to change the software. The systematic
61 | pattern of such abuse occurs in the area of products for individuals to
62 | use, which is precisely where it is most unacceptable. Therefore, we
63 | have designed this version of the GPL to prohibit the practice for those
64 | products. If such problems arise substantially in other domains, we
65 | stand ready to extend this provision to those domains in future versions
66 | of the GPL, as needed to protect the freedom of users.
67 |
68 | Finally, every program is threatened constantly by software patents.
69 | States should not allow patents to restrict development and use of
70 | software on general-purpose computers, but in those that do, we wish to
71 | avoid the special danger that patents applied to a free program could
72 | make it effectively proprietary. To prevent this, the GPL assures that
73 | patents cannot be used to render the program non-free.
74 |
75 | The precise terms and conditions for copying, distribution and
76 | modification follow.
77 |
78 | TERMS AND CONDITIONS
79 |
80 | 0. Definitions.
81 |
82 | "This License" refers to version 3 of the GNU General Public License.
83 |
84 | "Copyright" also means copyright-like laws that apply to other kinds of
85 | works, such as semiconductor masks.
86 |
87 | "The Program" refers to any copyrightable work licensed under this
88 | License. Each licensee is addressed as "you". "Licensees" and
89 | "recipients" may be individuals or organizations.
90 |
91 | To "modify" a work means to copy from or adapt all or part of the work
92 | in a fashion requiring copyright permission, other than the making of an
93 | exact copy. The resulting work is called a "modified version" of the
94 | earlier work or a work "based on" the earlier work.
95 |
96 | A "covered work" means either the unmodified Program or a work based
97 | on the Program.
98 |
99 | To "propagate" a work means to do anything with it that, without
100 | permission, would make you directly or secondarily liable for
101 | infringement under applicable copyright law, except executing it on a
102 | computer or modifying a private copy. Propagation includes copying,
103 | distribution (with or without modification), making available to the
104 | public, and in some countries other activities as well.
105 |
106 | To "convey" a work means any kind of propagation that enables other
107 | parties to make or receive copies. Mere interaction with a user through
108 | a computer network, with no transfer of a copy, is not conveying.
109 |
110 | An interactive user interface displays "Appropriate Legal Notices"
111 | to the extent that it includes a convenient and prominently visible
112 | feature that (1) displays an appropriate copyright notice, and (2)
113 | tells the user that there is no warranty for the work (except to the
114 | extent that warranties are provided), that licensees may convey the
115 | work under this License, and how to view a copy of this License. If
116 | the interface presents a list of user commands or options, such as a
117 | menu, a prominent item in the list meets this criterion.
118 |
119 | 1. Source Code.
120 |
121 | The "source code" for a work means the preferred form of the work
122 | for making modifications to it. "Object code" means any non-source
123 | form of a work.
124 |
125 | A "Standard Interface" means an interface that either is an official
126 | standard defined by a recognized standards body, or, in the case of
127 | interfaces specified for a particular programming language, one that
128 | is widely used among developers working in that language.
129 |
130 | The "System Libraries" of an executable work include anything, other
131 | than the work as a whole, that (a) is included in the normal form of
132 | packaging a Major Component, but which is not part of that Major
133 | Component, and (b) serves only to enable use of the work with that
134 | Major Component, or to implement a Standard Interface for which an
135 | implementation is available to the public in source code form. A
136 | "Major Component", in this context, means a major essential component
137 | (kernel, window system, and so on) of the specific operating system
138 | (if any) on which the executable work runs, or a compiler used to
139 | produce the work, or an object code interpreter used to run it.
140 |
141 | The "Corresponding Source" for a work in object code form means all
142 | the source code needed to generate, install, and (for an executable
143 | work) run the object code and to modify the work, including scripts to
144 | control those activities. However, it does not include the work's
145 | System Libraries, or general-purpose tools or generally available free
146 | programs which are used unmodified in performing those activities but
147 | which are not part of the work. For example, Corresponding Source
148 | includes interface definition files associated with source files for
149 | the work, and the source code for shared libraries and dynamically
150 | linked subprograms that the work is specifically designed to require,
151 | such as by intimate data communication or control flow between those
152 | subprograms and other parts of the work.
153 |
154 | The Corresponding Source need not include anything that users
155 | can regenerate automatically from other parts of the Corresponding
156 | Source.
157 |
158 | The Corresponding Source for a work in source code form is that
159 | same work.
160 |
161 | 2. Basic Permissions.
162 |
163 | All rights granted under this License are granted for the term of
164 | copyright on the Program, and are irrevocable provided the stated
165 | conditions are met. This License explicitly affirms your unlimited
166 | permission to run the unmodified Program. The output from running a
167 | covered work is covered by this License only if the output, given its
168 | content, constitutes a covered work. This License acknowledges your
169 | rights of fair use or other equivalent, as provided by copyright law.
170 |
171 | You may make, run and propagate covered works that you do not
172 | convey, without conditions so long as your license otherwise remains
173 | in force. You may convey covered works to others for the sole purpose
174 | of having them make modifications exclusively for you, or provide you
175 | with facilities for running those works, provided that you comply with
176 | the terms of this License in conveying all material for which you do
177 | not control copyright. Those thus making or running the covered works
178 | for you must do so exclusively on your behalf, under your direction
179 | and control, on terms that prohibit them from making any copies of
180 | your copyrighted material outside their relationship with you.
181 |
182 | Conveying under any other circumstances is permitted solely under
183 | the conditions stated below. Sublicensing is not allowed; section 10
184 | makes it unnecessary.
185 |
186 | 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
187 |
188 | No covered work shall be deemed part of an effective technological
189 | measure under any applicable law fulfilling obligations under article
190 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or
191 | similar laws prohibiting or restricting circumvention of such
192 | measures.
193 |
194 | When you convey a covered work, you waive any legal power to forbid
195 | circumvention of technological measures to the extent such circumvention
196 | is effected by exercising rights under this License with respect to
197 | the covered work, and you disclaim any intention to limit operation or
198 | modification of the work as a means of enforcing, against the work's
199 | users, your or third parties' legal rights to forbid circumvention of
200 | technological measures.
201 |
202 | 4. Conveying Verbatim Copies.
203 |
204 | You may convey verbatim copies of the Program's source code as you
205 | receive it, in any medium, provided that you conspicuously and
206 | appropriately publish on each copy an appropriate copyright notice;
207 | keep intact all notices stating that this License and any
208 | non-permissive terms added in accord with section 7 apply to the code;
209 | keep intact all notices of the absence of any warranty; and give all
210 | recipients a copy of this License along with the Program.
211 |
212 | You may charge any price or no price for each copy that you convey,
213 | and you may offer support or warranty protection for a fee.
214 |
215 | 5. Conveying Modified Source Versions.
216 |
217 | You may convey a work based on the Program, or the modifications to
218 | produce it from the Program, in the form of source code under the
219 | terms of section 4, provided that you also meet all of these conditions:
220 |
221 | a) The work must carry prominent notices stating that you modified
222 | it, and giving a relevant date.
223 |
224 | b) The work must carry prominent notices stating that it is
225 | released under this License and any conditions added under section
226 | 7. This requirement modifies the requirement in section 4 to
227 | "keep intact all notices".
228 |
229 | c) You must license the entire work, as a whole, under this
230 | License to anyone who comes into possession of a copy. This
231 | License will therefore apply, along with any applicable section 7
232 | additional terms, to the whole of the work, and all its parts,
233 | regardless of how they are packaged. This License gives no
234 | permission to license the work in any other way, but it does not
235 | invalidate such permission if you have separately received it.
236 |
237 | d) If the work has interactive user interfaces, each must display
238 | Appropriate Legal Notices; however, if the Program has interactive
239 | interfaces that do not display Appropriate Legal Notices, your
240 | work need not make them do so.
241 |
242 | A compilation of a covered work with other separate and independent
243 | works, which are not by their nature extensions of the covered work,
244 | and which are not combined with it such as to form a larger program,
245 | in or on a volume of a storage or distribution medium, is called an
246 | "aggregate" if the compilation and its resulting copyright are not
247 | used to limit the access or legal rights of the compilation's users
248 | beyond what the individual works permit. Inclusion of a covered work
249 | in an aggregate does not cause this License to apply to the other
250 | parts of the aggregate.
251 |
252 | 6. Conveying Non-Source Forms.
253 |
254 | You may convey a covered work in object code form under the terms
255 | of sections 4 and 5, provided that you also convey the
256 | machine-readable Corresponding Source under the terms of this License,
257 | in one of these ways:
258 |
259 | a) Convey the object code in, or embodied in, a physical product
260 | (including a physical distribution medium), accompanied by the
261 | Corresponding Source fixed on a durable physical medium
262 | customarily used for software interchange.
263 |
264 | b) Convey the object code in, or embodied in, a physical product
265 | (including a physical distribution medium), accompanied by a
266 | written offer, valid for at least three years and valid for as
267 | long as you offer spare parts or customer support for that product
268 | model, to give anyone who possesses the object code either (1) a
269 | copy of the Corresponding Source for all the software in the
270 | product that is covered by this License, on a durable physical
271 | medium customarily used for software interchange, for a price no
272 | more than your reasonable cost of physically performing this
273 | conveying of source, or (2) access to copy the
274 | Corresponding Source from a network server at no charge.
275 |
276 | c) Convey individual copies of the object code with a copy of the
277 | written offer to provide the Corresponding Source. This
278 | alternative is allowed only occasionally and noncommercially, and
279 | only if you received the object code with such an offer, in accord
280 | with subsection 6b.
281 |
282 | d) Convey the object code by offering access from a designated
283 | place (gratis or for a charge), and offer equivalent access to the
284 | Corresponding Source in the same way through the same place at no
285 | further charge. You need not require recipients to copy the
286 | Corresponding Source along with the object code. If the place to
287 | copy the object code is a network server, the Corresponding Source
288 | may be on a different server (operated by you or a third party)
289 | that supports equivalent copying facilities, provided you maintain
290 | clear directions next to the object code saying where to find the
291 | Corresponding Source. Regardless of what server hosts the
292 | Corresponding Source, you remain obligated to ensure that it is
293 | available for as long as needed to satisfy these requirements.
294 |
295 | e) Convey the object code using peer-to-peer transmission, provided
296 | you inform other peers where the object code and Corresponding
297 | Source of the work are being offered to the general public at no
298 | charge under subsection 6d.
299 |
300 | A separable portion of the object code, whose source code is excluded
301 | from the Corresponding Source as a System Library, need not be
302 | included in conveying the object code work.
303 |
304 | A "User Product" is either (1) a "consumer product", which means any
305 | tangible personal property which is normally used for personal, family,
306 | or household purposes, or (2) anything designed or sold for incorporation
307 | into a dwelling. In determining whether a product is a consumer product,
308 | doubtful cases shall be resolved in favor of coverage. For a particular
309 | product received by a particular user, "normally used" refers to a
310 | typical or common use of that class of product, regardless of the status
311 | of the particular user or of the way in which the particular user
312 | actually uses, or expects or is expected to use, the product. A product
313 | is a consumer product regardless of whether the product has substantial
314 | commercial, industrial or non-consumer uses, unless such uses represent
315 | the only significant mode of use of the product.
316 |
317 | "Installation Information" for a User Product means any methods,
318 | procedures, authorization keys, or other information required to install
319 | and execute modified versions of a covered work in that User Product from
320 | a modified version of its Corresponding Source. The information must
321 | suffice to ensure that the continued functioning of the modified object
322 | code is in no case prevented or interfered with solely because
323 | modification has been made.
324 |
325 | If you convey an object code work under this section in, or with, or
326 | specifically for use in, a User Product, and the conveying occurs as
327 | part of a transaction in which the right of possession and use of the
328 | User Product is transferred to the recipient in perpetuity or for a
329 | fixed term (regardless of how the transaction is characterized), the
330 | Corresponding Source conveyed under this section must be accompanied
331 | by the Installation Information. But this requirement does not apply
332 | if neither you nor any third party retains the ability to install
333 | modified object code on the User Product (for example, the work has
334 | been installed in ROM).
335 |
336 | The requirement to provide Installation Information does not include a
337 | requirement to continue to provide support service, warranty, or updates
338 | for a work that has been modified or installed by the recipient, or for
339 | the User Product in which it has been modified or installed. Access to a
340 | network may be denied when the modification itself materially and
341 | adversely affects the operation of the network or violates the rules and
342 | protocols for communication across the network.
343 |
344 | Corresponding Source conveyed, and Installation Information provided,
345 | in accord with this section must be in a format that is publicly
346 | documented (and with an implementation available to the public in
347 | source code form), and must require no special password or key for
348 | unpacking, reading or copying.
349 |
350 | 7. Additional Terms.
351 |
352 | "Additional permissions" are terms that supplement the terms of this
353 | License by making exceptions from one or more of its conditions.
354 | Additional permissions that are applicable to the entire Program shall
355 | be treated as though they were included in this License, to the extent
356 | that they are valid under applicable law. If additional permissions
357 | apply only to part of the Program, that part may be used separately
358 | under those permissions, but the entire Program remains governed by
359 | this License without regard to the additional permissions.
360 |
361 | When you convey a copy of a covered work, you may at your option
362 | remove any additional permissions from that copy, or from any part of
363 | it. (Additional permissions may be written to require their own
364 | removal in certain cases when you modify the work.) You may place
365 | additional permissions on material, added by you to a covered work,
366 | for which you have or can give appropriate copyright permission.
367 |
368 | Notwithstanding any other provision of this License, for material you
369 | add to a covered work, you may (if authorized by the copyright holders of
370 | that material) supplement the terms of this License with terms:
371 |
372 | a) Disclaiming warranty or limiting liability differently from the
373 | terms of sections 15 and 16 of this License; or
374 |
375 | b) Requiring preservation of specified reasonable legal notices or
376 | author attributions in that material or in the Appropriate Legal
377 | Notices displayed by works containing it; or
378 |
379 | c) Prohibiting misrepresentation of the origin of that material, or
380 | requiring that modified versions of such material be marked in
381 | reasonable ways as different from the original version; or
382 |
383 | d) Limiting the use for publicity purposes of names of licensors or
384 | authors of the material; or
385 |
386 | e) Declining to grant rights under trademark law for use of some
387 | trade names, trademarks, or service marks; or
388 |
389 | f) Requiring indemnification of licensors and authors of that
390 | material by anyone who conveys the material (or modified versions of
391 | it) with contractual assumptions of liability to the recipient, for
392 | any liability that these contractual assumptions directly impose on
393 | those licensors and authors.
394 |
395 | All other non-permissive additional terms are considered "further
396 | restrictions" within the meaning of section 10. If the Program as you
397 | received it, or any part of it, contains a notice stating that it is
398 | governed by this License along with a term that is a further
399 | restriction, you may remove that term. If a license document contains
400 | a further restriction but permits relicensing or conveying under this
401 | License, you may add to a covered work material governed by the terms
402 | of that license document, provided that the further restriction does
403 | not survive such relicensing or conveying.
404 |
405 | If you add terms to a covered work in accord with this section, you
406 | must place, in the relevant source files, a statement of the
407 | additional terms that apply to those files, or a notice indicating
408 | where to find the applicable terms.
409 |
410 | Additional terms, permissive or non-permissive, may be stated in the
411 | form of a separately written license, or stated as exceptions;
412 | the above requirements apply either way.
413 |
414 | 8. Termination.
415 |
416 | You may not propagate or modify a covered work except as expressly
417 | provided under this License. Any attempt otherwise to propagate or
418 | modify it is void, and will automatically terminate your rights under
419 | this License (including any patent licenses granted under the third
420 | paragraph of section 11).
421 |
422 | However, if you cease all violation of this License, then your
423 | license from a particular copyright holder is reinstated (a)
424 | provisionally, unless and until the copyright holder explicitly and
425 | finally terminates your license, and (b) permanently, if the copyright
426 | holder fails to notify you of the violation by some reasonable means
427 | prior to 60 days after the cessation.
428 |
429 | Moreover, your license from a particular copyright holder is
430 | reinstated permanently if the copyright holder notifies you of the
431 | violation by some reasonable means, this is the first time you have
432 | received notice of violation of this License (for any work) from that
433 | copyright holder, and you cure the violation prior to 30 days after
434 | your receipt of the notice.
435 |
436 | Termination of your rights under this section does not terminate the
437 | licenses of parties who have received copies or rights from you under
438 | this License. If your rights have been terminated and not permanently
439 | reinstated, you do not qualify to receive new licenses for the same
440 | material under section 10.
441 |
442 | 9. Acceptance Not Required for Having Copies.
443 |
444 | You are not required to accept this License in order to receive or
445 | run a copy of the Program. Ancillary propagation of a covered work
446 | occurring solely as a consequence of using peer-to-peer transmission
447 | to receive a copy likewise does not require acceptance. However,
448 | nothing other than this License grants you permission to propagate or
449 | modify any covered work. These actions infringe copyright if you do
450 | not accept this License. Therefore, by modifying or propagating a
451 | covered work, you indicate your acceptance of this License to do so.
452 |
453 | 10. Automatic Licensing of Downstream Recipients.
454 |
455 | Each time you convey a covered work, the recipient automatically
456 | receives a license from the original licensors, to run, modify and
457 | propagate that work, subject to this License. You are not responsible
458 | for enforcing compliance by third parties with this License.
459 |
460 | An "entity transaction" is a transaction transferring control of an
461 | organization, or substantially all assets of one, or subdividing an
462 | organization, or merging organizations. If propagation of a covered
463 | work results from an entity transaction, each party to that
464 | transaction who receives a copy of the work also receives whatever
465 | licenses to the work the party's predecessor in interest had or could
466 | give under the previous paragraph, plus a right to possession of the
467 | Corresponding Source of the work from the predecessor in interest, if
468 | the predecessor has it or can get it with reasonable efforts.
469 |
470 | You may not impose any further restrictions on the exercise of the
471 | rights granted or affirmed under this License. For example, you may
472 | not impose a license fee, royalty, or other charge for exercise of
473 | rights granted under this License, and you may not initiate litigation
474 | (including a cross-claim or counterclaim in a lawsuit) alleging that
475 | any patent claim is infringed by making, using, selling, offering for
476 | sale, or importing the Program or any portion of it.
477 |
478 | 11. Patents.
479 |
480 | A "contributor" is a copyright holder who authorizes use under this
481 | License of the Program or a work on which the Program is based. The
482 | work thus licensed is called the contributor's "contributor version".
483 |
484 | A contributor's "essential patent claims" are all patent claims
485 | owned or controlled by the contributor, whether already acquired or
486 | hereafter acquired, that would be infringed by some manner, permitted
487 | by this License, of making, using, or selling its contributor version,
488 | but do not include claims that would be infringed only as a
489 | consequence of further modification of the contributor version. For
490 | purposes of this definition, "control" includes the right to grant
491 | patent sublicenses in a manner consistent with the requirements of
492 | this License.
493 |
494 | Each contributor grants you a non-exclusive, worldwide, royalty-free
495 | patent license under the contributor's essential patent claims, to
496 | make, use, sell, offer for sale, import and otherwise run, modify and
497 | propagate the contents of its contributor version.
498 |
499 | In the following three paragraphs, a "patent license" is any express
500 | agreement or commitment, however denominated, not to enforce a patent
501 | (such as an express permission to practice a patent or covenant not to
502 | sue for patent infringement). To "grant" such a patent license to a
503 | party means to make such an agreement or commitment not to enforce a
504 | patent against the party.
505 |
506 | If you convey a covered work, knowingly relying on a patent license,
507 | and the Corresponding Source of the work is not available for anyone
508 | to copy, free of charge and under the terms of this License, through a
509 | publicly available network server or other readily accessible means,
510 | then you must either (1) cause the Corresponding Source to be so
511 | available, or (2) arrange to deprive yourself of the benefit of the
512 | patent license for this particular work, or (3) arrange, in a manner
513 | consistent with the requirements of this License, to extend the patent
514 | license to downstream recipients. "Knowingly relying" means you have
515 | actual knowledge that, but for the patent license, your conveying the
516 | covered work in a country, or your recipient's use of the covered work
517 | in a country, would infringe one or more identifiable patents in that
518 | country that you have reason to believe are valid.
519 |
520 | If, pursuant to or in connection with a single transaction or
521 | arrangement, you convey, or propagate by procuring conveyance of, a
522 | covered work, and grant a patent license to some of the parties
523 | receiving the covered work authorizing them to use, propagate, modify
524 | or convey a specific copy of the covered work, then the patent license
525 | you grant is automatically extended to all recipients of the covered
526 | work and works based on it.
527 |
528 | A patent license is "discriminatory" if it does not include within
529 | the scope of its coverage, prohibits the exercise of, or is
530 | conditioned on the non-exercise of one or more of the rights that are
531 | specifically granted under this License. You may not convey a covered
532 | work if you are a party to an arrangement with a third party that is
533 | in the business of distributing software, under which you make payment
534 | to the third party based on the extent of your activity of conveying
535 | the work, and under which the third party grants, to any of the
536 | parties who would receive the covered work from you, a discriminatory
537 | patent license (a) in connection with copies of the covered work
538 | conveyed by you (or copies made from those copies), or (b) primarily
539 | for and in connection with specific products or compilations that
540 | contain the covered work, unless you entered into that arrangement,
541 | or that patent license was granted, prior to 28 March 2007.
542 |
543 | Nothing in this License shall be construed as excluding or limiting
544 | any implied license or other defenses to infringement that may
545 | otherwise be available to you under applicable patent law.
546 |
547 | 12. No Surrender of Others' Freedom.
548 |
549 | If conditions are imposed on you (whether by court order, agreement or
550 | otherwise) that contradict the conditions of this License, they do not
551 | excuse you from the conditions of this License. If you cannot convey a
552 | covered work so as to satisfy simultaneously your obligations under this
553 | License and any other pertinent obligations, then as a consequence you may
554 | not convey it at all. For example, if you agree to terms that obligate you
555 | to collect a royalty for further conveying from those to whom you convey
556 | the Program, the only way you could satisfy both those terms and this
557 | License would be to refrain entirely from conveying the Program.
558 |
559 | 13. Use with the GNU Affero General Public License.
560 |
561 | Notwithstanding any other provision of this License, you have
562 | permission to link or combine any covered work with a work licensed
563 | under version 3 of the GNU Affero General Public License into a single
564 | combined work, and to convey the resulting work. The terms of this
565 | License will continue to apply to the part which is the covered work,
566 | but the special requirements of the GNU Affero General Public License,
567 | section 13, concerning interaction through a network will apply to the
568 | combination as such.
569 |
570 | 14. Revised Versions of this License.
571 |
572 | The Free Software Foundation may publish revised and/or new versions of
573 | the GNU General Public License from time to time. Such new versions will
574 | be similar in spirit to the present version, but may differ in detail to
575 | address new problems or concerns.
576 |
577 | Each version is given a distinguishing version number. If the
578 | Program specifies that a certain numbered version of the GNU General
579 | Public License "or any later version" applies to it, you have the
580 | option of following the terms and conditions either of that numbered
581 | version or of any later version published by the Free Software
582 | Foundation. If the Program does not specify a version number of the
583 | GNU General Public License, you may choose any version ever published
584 | by the Free Software Foundation.
585 |
586 | If the Program specifies that a proxy can decide which future
587 | versions of the GNU General Public License can be used, that proxy's
588 | public statement of acceptance of a version permanently authorizes you
589 | to choose that version for the Program.
590 |
591 | Later license versions may give you additional or different
592 | permissions. However, no additional obligations are imposed on any
593 | author or copyright holder as a result of your choosing to follow a
594 | later version.
595 |
596 | 15. Disclaimer of Warranty.
597 |
598 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
599 | APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
600 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
601 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
602 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
603 | PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
604 | IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
605 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
606 |
607 | 16. Limitation of Liability.
608 |
609 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
610 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
611 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
612 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
613 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
614 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
615 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
616 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
617 | SUCH DAMAGES.
618 |
619 | 17. Interpretation of Sections 15 and 16.
620 |
621 | If the disclaimer of warranty and limitation of liability provided
622 | above cannot be given local legal effect according to their terms,
623 | reviewing courts shall apply local law that most closely approximates
624 | an absolute waiver of all civil liability in connection with the
625 | Program, unless a warranty or assumption of liability accompanies a
626 | copy of the Program in return for a fee.
627 |
628 | END OF TERMS AND CONDITIONS
629 |
630 | How to Apply These Terms to Your New Programs
631 |
632 | If you develop a new program, and you want it to be of the greatest
633 | possible use to the public, the best way to achieve this is to make it
634 | free software which everyone can redistribute and change under these terms.
635 |
636 | To do so, attach the following notices to the program. It is safest
637 | to attach them to the start of each source file to most effectively
638 | state the exclusion of warranty; and each file should have at least
639 | the "copyright" line and a pointer to where the full notice is found.
640 |
641 |
642 | Copyright (C)
643 |
644 | This program is free software: you can redistribute it and/or modify
645 | it under the terms of the GNU General Public License as published by
646 | the Free Software Foundation, either version 3 of the License, or
647 | (at your option) any later version.
648 |
649 | This program is distributed in the hope that it will be useful,
650 | but WITHOUT ANY WARRANTY; without even the implied warranty of
651 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
652 | GNU General Public License for more details.
653 |
654 | You should have received a copy of the GNU General Public License
655 | along with this program. If not, see .
656 |
657 | Also add information on how to contact you by electronic and paper mail.
658 |
659 | If the program does terminal interaction, make it output a short
660 | notice like this when it starts in an interactive mode:
661 |
662 | Copyright (C)
663 | This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
664 | This is free software, and you are welcome to redistribute it
665 | under certain conditions; type `show c' for details.
666 |
667 | The hypothetical commands `show w' and `show c' should show the appropriate
668 | parts of the General Public License. Of course, your program's commands
669 | might be different; for a GUI interface, you would use an "about box".
670 |
671 | You should also get your employer (if you work as a programmer) or school,
672 | if any, to sign a "copyright disclaimer" for the program, if necessary.
673 | For more information on this, and how to apply and follow the GNU GPL, see
674 | .
675 |
676 | The GNU General Public License does not permit incorporating your program
677 | into proprietary programs. If your program is a subroutine library, you
678 | may consider it more useful to permit linking proprietary applications with
679 | the library. If this is what you want to do, use the GNU Lesser General
680 | Public License instead of this License. But first, please read
681 | .
682 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | image-match-rs
2 | ==============
3 |
4 | An implementation of the image matching algorithm described in
5 | [An Image Signature For Any Kind Of Image by H. Chi Wong, Marshall Bern, and David Goldberg](https://www.semanticscholar.org/paper/An-image-signature-for-any-kind-of-image-Wong-Bern/f0d7ae4a781b61dbf1c4fdcdc50dd82cc294d89f)
6 | . The algorithm is designed to detect nearly identical images, not images with the same conceptual content.
7 |
8 |
9 | Usage
10 | =====
11 |
12 | By default, the library offers two primary functions: `get_buffer_signature(rgba, width)` and `cosine_similarity(a, b)`.
13 | The former takes a pre-processed slice of `u8`s with each chunk of four representing the 8-bit red, green, blue, and
14 | alpha of a pixel, the latter two result vectors to compute their similarity. Per the source paper and our experiments
15 | in [this research](https://github.com/alt-text-org/image-algo-testing) images with a similarity greater than `0.6` can
16 | be considered likely matches. If the tuning methods described below are used, additional research will likely be needed
17 | to assess a new cutoff.
18 |
19 | If the `img` feature is used, also provided are `get_image_signature(image)` and `get_file_signature(path)` which use
20 | the [image library](https://crates.io/crates/image) to handle unpacking the image into an rgba buffer. All signature
21 | functions also expose `tuned` versions which allow tweaking the crop percentage used during the signature computation,
22 | the size of the collection grid which controls the length of the feature vector produced, and the size of the
23 | square around each grid point averaged to produce a value for that point. It's recommended to study the algorithm
24 | closely before embarking on tuning, as the effects of these nobs are not immediately obvious.
25 |
26 |
27 | Future Work
28 | ===========
29 | - Additional unit testing.
30 | - Experimenting with parameter choice is underway in [this repo](https://github.com/alt-text-org/image-match-params).
31 | - Experiment with widening the possible values of each dimension in the produced signature. Presently per the paper they
32 | are all integers in `[-2, 2]`. It will likely require experimentation around a new suggested vector similarity cutoff.
--------------------------------------------------------------------------------
/src/image.rs:
--------------------------------------------------------------------------------
1 | use std::cmp::{max, min};
2 | use std::error::Error;
3 | use std::fmt::{Debug, Display, Formatter};
4 | use std::io;
5 | use std::path::Path;
6 |
7 | use image::{GenericImageView, ImageError, Pixel};
8 | use image::io::Reader as ImageReader;
9 | use num::ToPrimitive;
10 |
11 | use ImageReadError::{DecodeError, IoError};
12 |
13 | use crate::{compute_from_gray, DEFAULT_CROP, DEFAULT_GRID_SIZE, pixel_gray};
14 |
15 | /// Produces a 544 signed byte signature for a provided image. The result is designed to be compared
16 | /// to other vectors computed by a call to this method using [cosine-similarity(a, b)].
17 | pub fn get_image_signature(img: I) -> Vec {
18 | let gray = grayscale_image(img);
19 |
20 | let average_square_width_fn = |width, height| {
21 | max(
22 | 2_usize,
23 | (0.5 + min(width, height) as f32 / 20.0).floor() as usize,
24 | ) / 2
25 | };
26 |
27 | compute_from_gray(gray, DEFAULT_CROP, DEFAULT_GRID_SIZE, average_square_width_fn)
28 | }
29 |
30 | /// Produces a variable length signed byte signature for a provided image. The result is designed to
31 | /// be compared to other vectors computed by a call to this method with identical tuning parameters
32 | /// using [cosine-similarity(a, b)]. `crop` is a value in [0, 0.5] indicating what percentage of the
33 | /// image to crop on all sides before grid placement. Note that this percentage is based not on the
34 | /// raw width but a calculation of color density. `grid_size` indicates how many points to place on
35 | /// the image for measurement in the resulting signature. Changing `grid_size` will alter the length
36 | /// of the signature to `8 * (grid_size - 1)^2 - 12 * (grid_size - 3) - 20`. The
37 | /// `average_square_width_fn` controls the size of the box around each grid point that's averaged
38 | /// to produce that grid point's brightness value. The paper proposes
39 | /// `max(2, floor(0.5 + min(cropped_width, cropped_height) / 20))` but provides no information about
40 | /// how that was chosen.
41 | pub fn get_tuned_image_signature(
42 | img: I,
43 | crop: f32,
44 | grid_size: usize,
45 | average_square_width_fn: fn(width: usize, height: usize) -> usize,
46 | ) -> Vec {
47 | let gray = grayscale_image(img);
48 | compute_from_gray(gray, crop, grid_size, average_square_width_fn)
49 | }
50 |
51 | /// Produces a 544 signed byte signature for a provided image file. The result is designed to be
52 | /// compared to other vectors computed by a call to this method using [cosine-similarity(a, b)].
53 | pub fn get_file_signature>(path: P) -> Result> {
54 | let image = ImageReader::open(path)?.decode()?;
55 | Ok(get_image_signature(image))
56 | }
57 |
58 | /// Produces a variable length signed byte signature for a provided image file. The result is
59 | /// designed to be compared to other vectors computed by a call to this method with identical tuning
60 | /// parameters using [cosine-similarity(a, b)]. `crop` is a value in [0, 0.5] indicating what
61 | /// percentage of the image to crop on all sides before grid placement. Note that this percentage is
62 | /// based not on the raw width but a calculation of color density. `grid_size` indicates how many
63 | /// points to place on the image for measurement in the resulting signature. Changing `grid_size`
64 | /// will alter the length of the signature to `8 * (grid_size - 1)^2 - 12 * (grid_size - 3) - 20`.
65 | /// The `average_square_width_fn` controls the size of the box around each grid point that's
66 | /// averaged to produce that grid point's brightness value. The paper proposes
67 | /// `max(2, floor(0.5 + min(cropped_width, cropped_height) / 20))` but provides no information about
68 | /// how that was chosen.
69 | pub fn get_tuned_file_signature>(
70 | path: P,
71 | crop: f32,
72 | grid_size: usize,
73 | average_square_width_fn: fn(width: usize, height: usize) -> usize,
74 | ) -> Result> {
75 | let image = ImageReader::open(path)?.decode()?;
76 | Ok(get_tuned_image_signature(image, crop, grid_size, average_square_width_fn))
77 | }
78 |
79 | pub enum ImageReadError {
80 | IoError(io::Error),
81 | DecodeError(ImageError),
82 | }
83 |
84 | impl Debug for ImageReadError {
85 | fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
86 | match self {
87 | IoError(e) => Debug::fmt(e, f),
88 | DecodeError(e) => Debug::fmt(e, f),
89 | }
90 | }
91 | }
92 |
93 | impl Display for ImageReadError {
94 | fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
95 | match self {
96 | IoError(e) => Display::fmt(e, f),
97 | DecodeError(e) => Display::fmt(e, f),
98 | }
99 | }
100 | }
101 |
102 | impl Error for ImageReadError {
103 | fn cause(&self) -> Option<&dyn Error> {
104 | match self {
105 | IoError(e) => Some(e),
106 | DecodeError(e) => Some(e)
107 | }
108 | }
109 | }
110 |
111 | impl From for ImageReadError {
112 | fn from(e: io::Error) -> Self {
113 | IoError(e)
114 | }
115 | }
116 |
117 | impl From for ImageReadError {
118 | fn from(e: ImageError) -> Self {
119 | DecodeError(e)
120 | }
121 | }
122 |
123 | pub type Result = std::result::Result;
124 |
125 | fn grayscale_image(img: I) -> Vec> {
126 | let pixels = img.pixels()
127 | .map(|(_, _, p)| p.to_rgba().0);
128 |
129 | let mut result = Vec::with_capacity(img.width() as usize);
130 | let mut row = Vec::with_capacity(img.height() as usize);
131 | let mut col = 0;
132 | for pixel in pixels {
133 | row.push(pixel_gray(
134 | pixel[0].to_u8().unwrap(),
135 | pixel[1].to_u8().unwrap(),
136 | pixel[2].to_u8().unwrap(),
137 | pixel[3].to_u8().unwrap(),
138 | ));
139 | col += 1;
140 | if col >= img.width() {
141 | result.push(row);
142 | row = Vec::with_capacity(img.height() as usize);
143 | col = 0;
144 | }
145 | }
146 |
147 | result
148 | }
149 |
--------------------------------------------------------------------------------
/src/lib.rs:
--------------------------------------------------------------------------------
1 | use std::cmp::{max, min};
2 | use std::collections::HashMap;
3 |
4 | #[allow(unused_imports)] // It's actually used, I promise
5 | use num::Signed;
6 |
7 | #[cfg(feature = "img")]
8 | pub mod image;
9 |
10 | const DEFAULT_CROP: f32 = 0.05;
11 | const DEFAULT_GRID_SIZE: usize = 10;
12 |
13 | /// Produces a 544 signed byte signature for a provided image that's encoded as an array of
14 | /// conceptually grouped RGBA bytes with the provided width. The result is designed to be compared
15 | /// to other vectors computed by a call to this method using [cosine-similarity(a, b)].
16 | pub fn get_buffer_signature(rgba_buffer: &[u8], width: usize) -> Vec {
17 | let gray = grayscale_buffer(rgba_buffer, width);
18 |
19 | let average_square_width_fn = |width, height| {
20 | max(
21 | 2_usize,
22 | (0.5 + min(width, height) as f32 / 20.0).floor() as usize,
23 | ) / 2
24 | };
25 |
26 | compute_from_gray(gray, DEFAULT_CROP, DEFAULT_GRID_SIZE, average_square_width_fn)
27 | }
28 |
29 | /// Produces a variable length signed byte signature for a provided image, encoded as an array of
30 | /// conceptually grouped RGBA bytes with the provided width. The result is designed to be compared
31 | /// to other vectors computed by a call to this method with identical tuning parameters using
32 | /// [cosine-similarity(a, b)]. `crop` is a value in [0, 0.5] indicating what percentage of the image
33 | /// to crop on all sides before grid placement. Note that this percentage is based not on the raw
34 | /// width but a calculation of color density. `grid_size` indicates how many points to place on the
35 | /// image for measurement in the resulting signature. Changing `grid_size` will alter the length of
36 | /// the signature to `8 * (grid_size - 1)^2 - 12 * (grid_size - 3) - 20`.The
37 | /// `average_square_width_fn` controls the size of the box around each grid point that's averaged
38 | /// to produce that grid point's brightness value. The paper proposes
39 | /// `max(2, floor(0.5 + min(cropped_width, cropped_height) / 20))` but provides no information about
40 | /// how that was chosen.
41 | pub fn get_tuned_buffer_signature(
42 | rgba_buffer: &[u8],
43 | width: usize,
44 | crop: f32,
45 | grid_size: usize,
46 | average_square_width_fn: fn(width: usize, height: usize) -> usize,
47 | ) -> Vec {
48 | let gray = grayscale_buffer(rgba_buffer, width);
49 | compute_from_gray(gray, crop, grid_size, average_square_width_fn)
50 | }
51 |
52 | /// Computes the cosine of the angle between two feature vectors. Those vectors must have been both
53 | /// produced by calls to an un-tuned signature function or identical calls to a tuned version. Per
54 | /// the source paper and out own research, when using the un-tuned signature calculation a cosine of
55 | /// 0.6 or greater indicates significant similarity.
56 | /// If either vector is all zeros,
57 | pub fn cosine_similarity(a: &Vec, b: &Vec) -> f64 {
58 | // For our purposes here, unequal lengths are a sign of major issues in client code.
59 | // One of my favorite professors always said "Crash early, crash often."
60 | assert_eq!(a.len(), b.len(), "Compared vectors must be of equal length");
61 |
62 | let a_length = vector_length(a);
63 | let b_length = vector_length(b);
64 | if a_length == 0.0 || b_length == 0.0 {
65 | if a_length == 0.0 && b_length == 0.0 {
66 | 1.0
67 | } else {
68 | 0.0
69 | }
70 | } else {
71 | let dot_product: f64 = a.iter().zip(b.iter())
72 | .map(|(av, bv)| *av as f64 * *bv as f64)
73 | .sum();
74 |
75 | dot_product / (a_length * b_length)
76 | }
77 | }
78 |
79 | fn vector_length(v: &[i8]) -> f64 {
80 | v.iter().map(|vi| *vi as i32).map(|vi| (vi * vi) as f64).sum::().sqrt()
81 | }
82 |
83 | /// Core computation steps of image signatures. Descriptions for each step can be found on the
84 | /// called functions and are pulled directly from the implemented paper.
85 | fn compute_from_gray(
86 | gray: Vec>,
87 | crop: f32,
88 | grid_size: usize,
89 | average_square_width_fn: fn(width: usize, height: usize) -> usize,
90 | ) -> Vec {
91 | let bounds = crop_boundaries(&gray, crop);
92 | let points = grid_points(&bounds, grid_size);
93 | let averages = grid_averages(gray, points, bounds, average_square_width_fn);
94 | compute_signature(averages, grid_size)
95 | }
96 |
97 | /*
98 | Step 1.
99 | "If the image is color, we first convert it to 8-bit grayscale .. Pure white is represented by 255
100 | and pure black by 0."
101 | */
102 | fn grayscale_buffer(rgba_buffer: &[u8], width: usize) -> Vec> {
103 | let height = (rgba_buffer.len() / 4) / width;
104 | let mut result = Vec::with_capacity(height);
105 | let mut idx: usize = 0;
106 | while idx < rgba_buffer.len() {
107 | let mut row = Vec::with_capacity(width);
108 | for _ in 0..width {
109 | let avg = pixel_gray(
110 | rgba_buffer[idx],
111 | rgba_buffer[idx + 1],
112 | rgba_buffer[idx + 2],
113 | rgba_buffer[idx + 3],
114 | );
115 |
116 | row.push(avg);
117 | idx += 4;
118 | }
119 | result.push(row);
120 | }
121 |
122 | result
123 | }
124 |
125 | fn pixel_gray(r: u8, g: u8, b: u8, a: u8) -> u8 {
126 | let rgb_avg = (r as u16 + g as u16 + b as u16) / 3;
127 | ((rgb_avg as f32) * (a as f32 / 255.0)) as u8
128 | }
129 |
130 | #[derive(Debug, PartialEq)]
131 | struct Bounds {
132 | lower_x: usize,
133 | upper_x: usize,
134 | lower_y: usize,
135 | upper_y: usize,
136 | }
137 |
138 | /*
139 | Step 2, part 1
140 | We define the grid in a way that is robust to mild cropping, under the assumption that such
141 | cropping usually removes relatively featureless parts of the image, for example, the margins of a
142 | document image or the dark bottom of the Mona Lisa picture.
143 |
144 | For each column of the image, we compute the sum of absolute values of differences
145 | between adjacent pixels in that column. We compute the total of all columns, and crop the image
146 | based on the `crop` parameter, which determines how much of the image to discard. For a `crop` of
147 | 0.05, we crop the image at the 5% and 95% columns, that is, the columns such that 5% of the total
148 | sum of differences lies on either side of the cropped image. We crop the rows of the image the
149 | same way (using the sums of original uncropped rows).
150 | */
151 | fn crop_boundaries(pixels: &Vec>, crop: f32) -> Bounds {
152 | let row_diff_sums: Vec = (0..pixels.len()).map(|y|
153 | (1..pixels[y].len()).map(|x|
154 | pixels[y][x].abs_diff(pixels[y][x - 1]) as i32).sum()
155 | ).collect();
156 |
157 | let (top, bottom) = get_bounds(row_diff_sums, crop);
158 |
159 | let col_diff_sums: Vec = (0..pixels[0].len()).map(|x|
160 | (1..pixels.len()).map(|y|
161 | pixels[y][x].abs_diff(pixels[y - 1][x]) as i32).sum()
162 | ).collect();
163 |
164 | let (left, right) = get_bounds(col_diff_sums, crop);
165 |
166 | Bounds {
167 | lower_x: left,
168 | upper_x: right,
169 | lower_y: top,
170 | upper_y: bottom,
171 | }
172 | }
173 |
174 | /// Returns the max number of contiguous values on each end of `diff_sums` that are, when summed,
175 | /// below `crop` times the total of `diff_sums`
176 | fn get_bounds(diff_sums: Vec, crop: f32) -> (usize, usize) {
177 | let total_diff_sum: i32 = diff_sums.iter().sum();
178 | let threshold = (total_diff_sum as f32 * crop) as i32;
179 | let mut lower = 0;
180 | let mut upper = diff_sums.len() - 1;
181 | let mut sum = diff_sums[lower];
182 |
183 | while sum < threshold {
184 | lower += 1;
185 | sum += diff_sums[lower];
186 | }
187 | sum = diff_sums[upper];
188 | while sum < threshold {
189 | upper -= 1;
190 | sum += diff_sums[upper];
191 | }
192 | (lower, upper)
193 | }
194 |
195 | /*
196 | Step 2, part 2
197 | "We next impose a 9x9 grid of points on the image. (For large databases, a bigger grid such as 11x11
198 | would give greater first-stage filtering.)
199 | ...
200 | Conceptually, we then divide the cropped image into a 10x10 grid of blocks. We round each interior
201 | grid point to the closest pixel (that is, integer coordinates), thereby setting a 9x9 grid of
202 | points on the image."
203 |
204 | - grid_size: size of superimposed grid (10 in the above example)
205 | */
206 | fn grid_points(bounds: &Bounds, grid_size: usize) -> HashMap<(i8, i8), (usize, usize)> {
207 | let x_width = (bounds.upper_x - bounds.lower_x + 1) as f32 / grid_size as f32;
208 | let y_width = (bounds.upper_y - bounds.lower_y + 1) as f32 / grid_size as f32;
209 |
210 | let mut points = HashMap::new();
211 | for x in 1..grid_size {
212 | for y in 1..grid_size {
213 | points.insert(
214 | (x as i8, y as i8),
215 | (
216 | bounds.lower_x + (x as f32 * x_width).trunc() as usize,
217 | bounds.lower_y + (y as f32 * y_width).trunc() as usize,
218 | ),
219 | );
220 | }
221 | }
222 |
223 | points
224 | }
225 |
226 | /*
227 | Step 3
228 | "At each grid point, we compute the average gray level of the PxP square centered at the grid point.
229 | We ran our experiments with P = max(2, floor(0.5 + min(n, m) / 20)) where n and m are the dimensions
230 | of the image in pixels. The squares are slightly soft-edged, meaning that instead of using the
231 | pixel’s gray levels themselves, we use an average of a 3x3 block centered at that pixel."
232 | */
233 | fn grid_averages(
234 | pixels: Vec>,
235 | points: HashMap<(i8, i8), (usize, usize)>,
236 | bounds: Bounds,
237 | average_square_width_fn: fn(width: usize, height: usize) -> usize,
238 | ) -> HashMap<(i8, i8), u8> {
239 | let width = bounds.upper_x - bounds.lower_x;
240 | let height = bounds.upper_y - bounds.lower_y;
241 | let square_edge = average_square_width_fn(width, height) as i32;
242 |
243 | let mut result = HashMap::new();
244 | for (grid_coord, (point_x, point_y)) in points {
245 | let mut sum: f32 = 0.0;
246 | for delta_x in -square_edge..=square_edge {
247 | for delta_y in -square_edge..=square_edge {
248 | let average = pixel_average(
249 | &pixels,
250 | (point_x as i32 + delta_x) as usize,
251 | (point_y as i32 + delta_y) as usize,
252 | );
253 | sum += average;
254 | }
255 | }
256 |
257 | let i = sum / ((square_edge * 2 + 1) * (square_edge * 2 + 1)) as f32;
258 | result.insert(grid_coord, i as u8);
259 | }
260 |
261 | result
262 | }
263 |
264 | /*
265 | Step 4
266 | For each grid point, we compute an 8-element array whose elements give a comparison of the average
267 | gray level of the grid point square with those of its eight neighbors. The result of a comparison
268 | can be “much darker”, “darker”, “same”, “lighter”, or “much lighter”, represented numerically as
269 | -2, -1, 0, 1 and 2, respectively. The “same” values are those averages that differ by no more than
270 | 2 on a scale of 0 to 255. We set the boundary between “much darker” and “darker” so that these two
271 | values are equally popular; we do the same for “lighter” and “much lighter”. The rationale in this
272 | step is that “same” may be very common in images with flat backgrounds (such as text documents), and
273 | hence it should not be included in the histogram equalization applied to the other values. Grid
274 | points in the first or last rows or column have fewer than 8 neighbors..."
275 |
276 | (The authors pad missing neighbors with 0's, we just omit them.)
277 |
278 | Step 5
279 | "The signature of an image is simply the concatenation of the 8-element arrays corresponding to the
280 | grid points, ordered left-to-right, top-to-bottom..."
281 | */
282 | const GRID_DELTAS: [(i8, i8); 9] = [
283 | (-1, -1), (0, -1), (1, -1),
284 | (-1, 0), (0, 0), (1, 0),
285 | (-1, 1), (0, 1), (1, 1)
286 | ];
287 |
288 | fn compute_signature(point_averages: HashMap<(i8, i8), u8>, grid_size: usize) -> Vec {
289 | let mut raw_diffs = Vec::with_capacity(grid_size * grid_size);
290 | for grid_y in 1..(grid_size as i8) {
291 | for grid_x in 1..(grid_size as i8) {
292 | let gray = *point_averages.get(&(grid_x, grid_y)).unwrap();
293 | let raw_point_diffs: Vec = GRID_DELTAS.iter()
294 | .filter_map(|(delta_x, delta_y)| {
295 | point_averages.get(&(grid_x + delta_x, grid_y + delta_y))
296 | .map(|other| compute_diff(gray, *other))
297 | }).collect();
298 | raw_diffs.push(raw_point_diffs)
299 | }
300 | }
301 |
302 | let (dark_threshold, light_threshold) = get_thresholds(&raw_diffs);
303 | raw_diffs.into_iter().flat_map(|neighbors|
304 | neighbors.into_iter()
305 | .map(|v| {
306 | match v {
307 | v if v > 0 => collapse(v, light_threshold),
308 | v if v < 0 => collapse(v, dark_threshold),
309 | _ => 0
310 | }
311 | })).collect()
312 | }
313 |
314 |
315 | fn get_thresholds(raw_diffs: &[Vec]) -> (i16, i16) {
316 | let (dark, light): (Vec, Vec) = raw_diffs.iter().flatten()
317 | .filter(|d| **d != 0)
318 | .partition(|d| **d < 0);
319 |
320 | let dark_threshold = get_median(dark);
321 | let light_threshold = get_median(light);
322 |
323 | (dark_threshold, light_threshold)
324 | }
325 |
326 | fn collapse(val: i16, threshold: i16) -> i8 {
327 | if val.abs() >= threshold.abs() {
328 | 2 * val.signum() as i8
329 | } else {
330 | val.signum() as i8
331 | }
332 | }
333 |
334 | fn get_median(mut vec: Vec) -> i16 {
335 | vec.sort();
336 | if vec.len() % 2 == 0 {
337 | if vec.is_empty() {
338 | 0
339 | } else {
340 | (vec[(vec.len() / 2) - 1] + vec[vec.len() / 2]) / 2
341 | }
342 | } else {
343 | vec[vec.len() / 2]
344 | }
345 | }
346 |
347 | fn compute_diff(me: u8, other: u8) -> i16 {
348 | let raw_result = me as i16 - other as i16;
349 | if raw_result.abs() <= 2 {
350 | 0
351 | } else {
352 | raw_result
353 | }
354 | }
355 |
356 | const PIXEL_DELTAS: [(i32, i32); 9] = [
357 | (-1, -1), (0, -1), (1, -1),
358 | (-1, 0), (0, 0), (1, 0),
359 | (-1, 1), (0, 1), (1, 1)
360 | ];
361 |
362 | fn pixel_average(pixels: &[Vec], x: usize, y: usize) -> f32 {
363 | let max_y = pixels.len() as i32 - 1;
364 | let max_x = pixels[0].len() as i32 - 1;
365 |
366 | let sum: f32 = PIXEL_DELTAS.iter().map(|(delta_x, delta_y)| {
367 | pixels[(y as i32 + *delta_y).clamp(0, max_y) as usize][(x as i32 + *delta_x).clamp(0, max_x) as usize] as f32
368 | }).sum();
369 |
370 | sum / 9.0
371 | }
372 |
373 | #[cfg(test)]
374 | mod tests {
375 | use super::*;
376 | use pretty_assertions::{assert_eq};
377 | use std::collections::BTreeMap;
378 |
379 | macro_rules! assert_map_eq {
380 | ( $actual:expr, $expected:expr ) => {
381 | {
382 | let actual: BTreeMap<_, _> = ($actual).into_iter().collect();
383 | let expected: BTreeMap<_, _> = ($expected).into_iter().collect();
384 | assert_eq!(actual, expected)
385 | }
386 | }
387 | }
388 |
389 | fn from_dotgrid(grid: &str) -> Vec> {
390 | grid.split("\n")
391 | .map(|row| row.replace(" ",""))
392 | .filter(|row| row.len() > 0)
393 | .map(|row| row.chars().map(|c| match c {
394 | '.' => 0,
395 | 'o' => 64,
396 | 'O' => 128,
397 | 'x' => 192,
398 | 'X' => 255,
399 | c => panic!("Unexpected dotgrid character '{}'", c)
400 | }).collect()).collect()
401 | }
402 |
403 | #[test]
404 | fn test_pixel_gray() {
405 | assert_eq!(pixel_gray(255,255,255,255), 255);
406 | assert_eq!(pixel_gray(0,0,0,0), 0);
407 | assert_eq!(pixel_gray(255,255,255,0), 0);
408 | assert_eq!(pixel_gray(32, 64, 96, 255), 64);
409 | }
410 |
411 | #[test]
412 | fn test_grayscale_buffer() {
413 | assert_eq!(grayscale_buffer(&[
414 | 255, 255, 255, 255,
415 | 128, 128, 128, 128,
416 | 0, 0, 0, 0,
417 | 0, 128, 255, 128
418 | ], 2), [
419 | [255, 64],
420 | [0, 63]
421 | ]);
422 | }
423 |
424 | #[test]
425 | fn test_get_bounds() {
426 | assert_eq!([
427 | (vec![0,0,50,50,0,0], 0.05),
428 | (vec![0,0,0,50,50,0,0,0], 0.05),
429 | ].map(|(v, c)| get_bounds(v, c)),
430 | [(2, 3), (3, 4)]);
431 | }
432 |
433 | #[test]
434 | fn test_crop_boundaries() {
435 | let pic = from_dotgrid("
436 | .......
437 | .oooo..
438 | .oXxo..
439 | .oXxo..
440 | .......
441 | .......
442 | ");
443 |
444 | assert_eq!(crop_boundaries(&pic, 0.05), Bounds {
445 | lower_x: 1,
446 | upper_x: 4,
447 | lower_y: 1,
448 | upper_y: 3,
449 | });
450 | assert_eq!(crop_boundaries(&pic, 0.25), Bounds {
451 | lower_x: 2,
452 | upper_x: 3,
453 | lower_y: 2,
454 | upper_y: 3,
455 | });
456 | assert_eq!(crop_boundaries(&pic, 0.5), Bounds {
457 | lower_x: 2,
458 | upper_x: 2,
459 | lower_y: 2,
460 | upper_y: 2,
461 | });
462 | }
463 |
464 | #[test]
465 | fn test_grid_points() {
466 | assert_map_eq!(grid_points(&Bounds {
467 | lower_x: 5,
468 | upper_x: 15,
469 | lower_y: 10,
470 | upper_y: 30,
471 | }, 2), [
472 | ((1, 1), (10, 20))
473 | ]);
474 |
475 | assert_map_eq!(grid_points(&Bounds {
476 | lower_x: 5,
477 | upper_x: 15,
478 | lower_y: 10,
479 | upper_y: 30,
480 | }, 3), [
481 | ((1, 1), (8, 17)),
482 | ((2, 1), (12, 17)),
483 | ((1, 2), (8, 24)),
484 | ((2, 2), (12, 24)),
485 | ]);
486 | }
487 |
488 | #[test]
489 | fn test_grid_points_extreme() {
490 | assert_map_eq!(grid_points(&Bounds {
491 | lower_x: 0,
492 | upper_x: 100,
493 | lower_y: 1,
494 | upper_y: 1,
495 | }, 6), [
496 | ((1, 1), (16, 1)),
497 | ((2, 1), (33, 1)),
498 | ((3, 1), (50, 1)),
499 | ((4, 1), (67, 1)),
500 | ((5, 1), (84, 1)),
501 |
502 | ((1, 2), (16, 1)),
503 | ((2, 2), (33, 1)),
504 | ((3, 2), (50, 1)),
505 | ((4, 2), (67, 1)),
506 | ((5, 2), (84, 1)),
507 |
508 | ((1, 3), (16, 1)),
509 | ((2, 3), (33, 1)),
510 | ((3, 3), (50, 1)),
511 | ((4, 3), (67, 1)),
512 | ((5, 3), (84, 1)),
513 |
514 | ((1, 4), (16, 1)),
515 | ((2, 4), (33, 1)),
516 | ((3, 4), (50, 1)),
517 | ((4, 4), (67, 1)),
518 | ((5, 4), (84, 1)),
519 |
520 | ((1, 5), (16, 1)),
521 | ((2, 5), (33, 1)),
522 | ((3, 5), (50, 1)),
523 | ((4, 5), (67, 1)),
524 | ((5, 5), (84, 1)),
525 | ]);
526 | }
527 |
528 | #[test]
529 | fn test_grid_points_tiny() {
530 | assert_map_eq!(grid_points(&Bounds {
531 | lower_x: 0,
532 | upper_x: 1,
533 | lower_y: 0,
534 | upper_y: 1,
535 | }, 3), [
536 | ((1,1), (0,0)),
537 | ((2,1), (1,0)),
538 | ((1,2), (0,1)),
539 | ((2,2), (1,1)),
540 | ]);
541 | }
542 | }
543 |
--------------------------------------------------------------------------------
/tests/stats.rs:
--------------------------------------------------------------------------------
1 | #![cfg(feature = "img")]
2 |
3 | use std::collections::HashMap;
4 | use std::ffi::OsString;
5 | use std::fs;
6 | use std::path::Path;
7 |
8 | use image_match::cosine_similarity;
9 | use image_match::image::get_file_signature;
10 |
11 | #[test]
12 | fn check_match_percentages() {
13 | let orig = calc_sigs_for_pic_dir_files("original");
14 | let cropped = calc_sigs_for_pic_dir_files("cropped");
15 | let grown = calc_sigs_for_pic_dir_files("grown");
16 | let shrunk = calc_sigs_for_pic_dir_files("shrunk");
17 |
18 | evaluate_altered("Cropped", &orig, &cropped);
19 | evaluate_altered("Grown", &orig, &grown);
20 | evaluate_altered("Shrunk", &orig, &shrunk);
21 | evaluate_non_matching(&orig);
22 | }
23 |
24 | fn calc_sigs_for_pic_dir_files(dir: &str) -> HashMap> {
25 | println!("Calculating signatures for {}", dir);
26 | let pics_root = Path::new("./tests/pics").join(Path::new(dir));
27 | let names: Vec = fs::read_dir(pics_root.clone()).unwrap()
28 | .map(|f| f.unwrap().file_name())
29 | .collect();
30 | let mut files = HashMap::with_capacity(names.len());
31 | for name in names {
32 | let path = pics_root.join(Path::new(&name));
33 | let signature = get_file_signature(path).unwrap();
34 | files.insert(name.into_string().unwrap(), signature);
35 | }
36 |
37 | files
38 | }
39 |
40 | fn evaluate_altered(name: &str, orig: &HashMap>, altered: &HashMap>) {
41 | let mut cosines = Vec::with_capacity(orig.len());
42 | for (file, signature) in orig {
43 | let altered_sig = altered.get(file).unwrap();
44 | cosines.push(cosine_similarity(signature, altered_sig));
45 | }
46 |
47 | print_stats(name, cosines);
48 | }
49 |
50 | fn evaluate_non_matching(orig: &HashMap>) {
51 | let mut non_matching = Vec::with_capacity(orig.len() * orig.len());
52 | for (name, signature) in orig {
53 | orig.iter().filter(|(n, _)| n != &name)
54 | .map(|(_, other_sig)| cosine_similarity(signature, other_sig))
55 | .for_each(|similarity| non_matching.push(similarity));
56 | }
57 |
58 | print_stats("Non-Matching", non_matching);
59 | }
60 |
61 | fn print_stats(name: &str, mut cosines: Vec) {
62 | cosines.sort_by(|a, b| a.partial_cmp(b).unwrap());
63 |
64 | let avg = cosines.iter().sum::() / cosines.len() as f64;
65 |
66 | println!("{}:", name);
67 | println!("Min\tMean\tMax\t30th\t50th\t75th\t90th\t95th\t99th");
68 | println!("{:.3}\t{:.3}\t{:.3}\t{:.3}\t{:.3}\t{:.3}\t{:.3}\t{:.3}\t{:.3}\n",
69 | cosines.first().unwrap(),
70 | avg,
71 | cosines.last().unwrap(),
72 | prcnt(&cosines, 0.30),
73 | prcnt(&cosines, 0.50),
74 | prcnt(&cosines, 0.75),
75 | prcnt(&cosines, 0.90),
76 | prcnt(&cosines, 0.95),
77 | prcnt(&cosines, 0.99),
78 | );
79 | }
80 |
81 | fn prcnt(cosines: &Vec, percentile: f64) -> f64 {
82 | let idx = (percentile * cosines.len() as f64).floor() as usize;
83 | *cosines.get(idx).unwrap()
84 | }
85 |
--------------------------------------------------------------------------------