diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 87fc4fb..710af4c 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.0","generation_timestamp":"2023-12-29T15:42:41","documenter_version":"1.2.1"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-09-14T15:06:15","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/dev/api/index.html b/dev/api/index.html index 9824fb3..79d1870 100644 --- a/dev/api/index.html +++ b/dev/api/index.html @@ -1,27 +1,27 @@ -API Reference · DitherPunk.jl
GitHub

API Reference

DitherPunk.dither — Function
dither([T::Type,] img, alg::AbstractDither, args...; kwargs...)

Dither image img using algorithm alg.

Output

If no return type is specified, dither will default to the type of the input image.

source
DitherPunk.dither! — Function
dither!([out,] img, alg::AbstractDither, args...; kwargs...)

Dither image img using algorithm alg.

Output

If out is specified, it will be changed in place. Otherwise img will be changed in place.

source
DitherPunk.braille — Function
braille(img; kwargs...)
-braille(img, alg; kwargs...)

Binary dither with algorithm alg, then print image in braille.

Keyword arguments

  • invert: invert Unicode output, defaults to false
  • to_string: return a string instead of printing to terminal. Defaults to false.
  • method: method used to print in unicode. Either :braille or :block. Defaults to :braille.

All keyword arguments for binary dithering methods can be used.

source

Algorithm types

Error diffusion

DitherPunk.ErrorDiffusion — Type
ErrorDiffusion(filter, offset)

Generalized error diffusion algorithm. When calling dither using a color palette cs, this will iterate over pixels and round them to the closest color in cs. The rounding error is then "diffused" over the neighborhood defined by the matrix filter centered around an integer offset.

When using dither or dither! with an ErrorDiffusion method, the keyword argument clamp_error can be passed, which defaults to true. When true, the accumulated error on each pixel is clamped within limits of the image's colorant type before looking up the closest color. Setting clamp_error=false might be desired to achieve a glitchy effect.

Example

julia> alg = FloydSteinberg() # returns ErrorDiffusion instance
+API Reference · DitherPunk.jl
GitHub
API Reference
DitherPunk.dither — Function
dither([T::Type,] img, alg::AbstractDither, args...; kwargs...)
Dither image img using algorithm alg.
Output
If no return type is specified, dither will default to the type of the input image.
source
DitherPunk.dither! — Function
dither!([out,] img, alg::AbstractDither, args...; kwargs...)
Dither image img using algorithm alg.
Output
If out is specified, it will be changed in place. Otherwise img will be changed in place.
source
DitherPunk.braille — Function
braille(img; kwargs...)
+braille(img, alg; kwargs...)
Binary dither with algorithm alg, then print image in braille.
Keyword arguments
  • invert: invert Unicode output, defaults to false
  • to_string: return a string instead of printing to terminal. Defaults to false.
  • method: method used to print in unicode. Either :braille or :block. Defaults to :braille.
All keyword arguments for binary dithering methods can be used.
source
Algorithm types
Error diffusion
DitherPunk.ErrorDiffusion — Type
ErrorDiffusion(filter, offset)
Generalized error diffusion algorithm. When calling dither using a color palette cs, this will iterate over pixels and round them to the closest color in cs. The rounding error is then "diffused" over the neighborhood defined by the matrix filter centered around an integer offset.
When using dither or dither! with an ErrorDiffusion method, the keyword argument clamp_error can be passed, which defaults to true. When true, the accumulated error on each pixel is clamped within limits of the image's colorant type before looking up the closest color. Setting clamp_error=false might be desired to achieve a glitchy effect.
Example
julia> alg = FloydSteinberg() # returns ErrorDiffusion instance
 ErrorDiffusion{Rational{Int64}, UnitRange{Int64}}(CartesianIndex{2}[CartesianIndex(1, 0), CartesianIndex(-1, 1), CartesianIndex(0, 1), CartesianIndex(1, 1)], Rational{Int64}[7//16, 3//16, 5//16, 1//16], (-1:1, 0:1))
 
 julia> cs = ColorSchemes.PuOr_7  # using ColorSchemes.jl for color palette presets
 
 julia> dither(img, alg, cs)
 
-julia> dither(img, alg, cs; clamp_error=false)
source
DitherPunk.FloydSteinberg — Function
FloydSteinberg()
Error diffusion algorithm using the filter
    *   7
-3   5   1     (1//16)
References
[1]  Floyd, R.W. and L. Steinberg, "An Adaptive Algorithm for Spatial Gray      Scale."  SID 1975, International Symposium Digest of Technical Papers,      vol 1975m, pp. 36-37.
source
DitherPunk.JarvisJudice — Function
JarvisJudice()
Error diffusion algorithm using the filter
        *   7   5
+julia> dither(img, alg, cs; clamp_error=false)
source
DitherPunk.FloydSteinberg — Function
FloydSteinberg()
Error diffusion algorithm using the filter
    *   7
+3   5   1     (1//16)
References
[1]  Floyd, R.W. and L. Steinberg, "An Adaptive Algorithm for Spatial Gray      Scale."  SID 1975, International Symposium Digest of Technical Papers,      vol 1975m, pp. 36-37.
source
DitherPunk.JarvisJudice — Function
JarvisJudice()
Error diffusion algorithm using the filter
        *   7   5
 3   5   7   5   3
-1   3   5   3   1   (1//48)
Also known as the Jarvis, Judice, and Ninke filter.
References
[1]  Jarvis, J.F., C.N. Judice, and W.H. Ninke, "A Survey of Techniques for      the Display of Continuous Tone Pictures on Bi-Level Displays," Computer      Graphics and Image Processing, vol. 5, pp. 13-40, 1976.
source
DitherPunk.Atkinson — Function
Atkinson()
Error diffusion algorithm using the filter
    *   1   1
+1   3   5   3   1   (1//48)
Also known as the Jarvis, Judice, and Ninke filter.
References
[1]  Jarvis, J.F., C.N. Judice, and W.H. Ninke, "A Survey of Techniques for      the Display of Continuous Tone Pictures on Bi-Level Displays," Computer      Graphics and Image Processing, vol. 5, pp. 13-40, 1976.
source
DitherPunk.Sierra — Function
Sierra()
Error diffusion algorithm using the filter
        *   5   3
 2   4   5   4   2
-    2   3   2       (1//32)
Also known as Sierra3 or three-row Sierra due to the filter shape.
source
DitherPunk.TwoRowSierra — Function
TwoRowSierra()
Error diffusion algorithm using the filter
        *   4   3
-1   2   3   2   1   (1//16)
Also known as Sierra2.
source
DitherPunk.SierraLite — Function
SierraLite()
Error diffusion algorithm using the filter
    *   2
-1   1               (1//4)
Also known as Sierra-2-4A filter.
source
DitherPunk.Stucki — Function
Stucki()
Error diffusion algorithm using the filter
        *   8   4
+    2   3   2       (1//32)
Also known as Sierra3 or three-row Sierra due to the filter shape.
source
DitherPunk.TwoRowSierra — Function
TwoRowSierra()
Error diffusion algorithm using the filter
        *   4   3
+1   2   3   2   1   (1//16)
Also known as Sierra2.
source
DitherPunk.SierraLite — Function
SierraLite()
Error diffusion algorithm using the filter
    *   2
+1   1               (1//4)
Also known as Sierra-2-4A filter.
source
DitherPunk.Stucki — Function
Stucki()
Error diffusion algorithm using the filter
        *   8   4
 2   4   8   4   2
-1   2   4   2   1   (1//42)
References
[1]  Stucki, P., "MECCA - a multiple-error correcting computation algorithm      for bilevel image hardcopy reproduction."  Research Report RZ1060, IBM      Research Laboratory, Zurich, Switzerland, 1981.
source
DitherPunk.Burkes — Function
Burkes()
Error diffusion algorithm using the filter
        *   8   4
+1   2   4   2   1   (1//42)
References
[1]  Stucki, P., "MECCA - a multiple-error correcting computation algorithm      for bilevel image hardcopy reproduction."  Research Report RZ1060, IBM      Research Laboratory, Zurich, Switzerland, 1981.
source
DitherPunk.Burkes — Function
Burkes()
Error diffusion algorithm using the filter
        *   8   4
 2   4   8   4   2
-1   2   4   2   1   (1//42)
References
[1] Burkes, D., "Presentation of the Burkes error filter for use in preparing     continuous-tone images for presentation on bi-level devices." Unpublished, 1988.
source
DitherPunk.Fan93 — Function
Fan93()
Error diffusion algorithm using the filter
      *  7
-1  3  5            (1//16)
A modification of the weights used in the Floyd-Steinberg algorithm.
References
[1] Z. Fan, "A Simple Modification of Error Diffusion Weights",     IS&T's 46th Annual Conference, May 9-14, 1993, Final Program and Advanced Printing of     Paper Summaries, pp 113-115 (1993).
source
DitherPunk.ShiauFan — Function
ShiauFan()
Error diffusion algorithm using the filter
        *   4
-1   1   2           (1//8)
References
[1]  J. N. Shiau and Z. Fan. "Method for quantization gray level pixel data with extended      distribution set", US 5353127A, United States Patent and Trademark Office, Oct. 4, 1993
source
DitherPunk.ShiauFan2 — Function
ShiauFan2()
Error diffusion algorithm using the filter
            *   8
-1   1   2   4       (1//16)
References
[1]  J. N. Shiau and Z. Fan. "Method for quantization gray level pixel data with extended      distribution set", US 5353127A, United States Patent and Trademark Office, Oct. 4, 1993 [2]  J. N. Shiau and Z. Fan. "A set of easily implementable coefficients in error-diffusion      with reduced worm artifacts" Color Imaging: Device-Independent Color, Color Hard Copy,      and Graphics Arts, volume 2658, pages 222–225. SPIE, March 1996.
source
DitherPunk.SimpleErrorDiffusion — Function
SimpleErrorDiffusion()
Error diffusion algorithm using the filter
*   1
-1   0         (1//2)
References
[1]  Floyd, R.W. and L. Steinberg, "An Adaptive Algorithm for Spatial Gray      Scale."  SID 1975, International Symposium Digest of Technical Papers,      vol 1975m, pp. 36-37.
source
Ordered dithering
DitherPunk.OrderedDither — Type
OrderedDither(mat::AbstractMatrix)
Generalized ordered dithering algorithm using a threshold map. Takes a normalized threshold matrix mat.
When applying the algorithm to an image, the threshold matrix is repeatedly tiled to match the size of the image. It is then applied as a per-pixel threshold map. Optionally, this final threshold map can be inverted by selecting invert_map=true.
source
Bayer
DitherPunk.Bayer — Function
Bayer([level=1]; kwargs...)
Ordered dithering using the Bayer matrix as a threshold matrix. The Bayer matrix is of dimension $2^{n+1} \times 2^{n+1}$, where $n$ is the level, which defaults to 1.
[1]  Bayer, B.E., "An Optimum Method for Two-Level Rendition of Continuous      Tone Pictures," IEEE International Conference on Communications,      Conference Records, 1973, pp. 26-11 to 26-15.
source
Halftoning
DitherPunk.Rhombus — Function
Rhombus()
Diagonal ordered matrix with balanced centered points. Uses $8 \times 8$ threshold matrix RHOMBUS_MAT.
source
Threshold methods
DitherPunk.ClosestColor — Type
Simplest form of image quantization by turning each pixel to the closest one in the provided color palette cs. Technically this not a dithering algorithm as the quatization error is not "randomized".
source
Other
Utilities
Index

+1   2   4   2   1   (1//42)

References

[1] Burkes, D., "Presentation of the Burkes error filter for use in preparing continuous-tone images for presentation on bi-level devices." Unpublished, 1988.

source
DitherPunk.Fan93 — Function
Fan93()

Error diffusion algorithm using the filter

      *  7
+1  3  5            (1//16)

A modification of the weights used in the Floyd-Steinberg algorithm.

References

[1] Z. Fan, "A Simple Modification of Error Diffusion Weights", IS&T's 46th Annual Conference, May 9-14, 1993, Final Program and Advanced Printing of Paper Summaries, pp 113-115 (1993).

source
DitherPunk.ShiauFan — Function
ShiauFan()

Error diffusion algorithm using the filter

        *   4
+1   1   2           (1//8)

References

[1] J. N. Shiau and Z. Fan. "Method for quantization gray level pixel data with extended distribution set", US 5353127A, United States Patent and Trademark Office, Oct. 4, 1993

source
DitherPunk.ShiauFan2 — Function
ShiauFan2()

Error diffusion algorithm using the filter

            *   8
+1   1   2   4       (1//16)

References

[1] J. N. Shiau and Z. Fan. "Method for quantization gray level pixel data with extended distribution set", US 5353127A, United States Patent and Trademark Office, Oct. 4, 1993 [2] J. N. Shiau and Z. Fan. "A set of easily implementable coefficients in error-diffusion with reduced worm artifacts" Color Imaging: Device-Independent Color, Color Hard Copy, and Graphics Arts, volume 2658, pages 222–225. SPIE, March 1996.

source
DitherPunk.SimpleErrorDiffusion — Function
SimpleErrorDiffusion()

Error diffusion algorithm using the filter

*   1
+1   0         (1//2)

References

[1] Floyd, R.W. and L. Steinberg, "An Adaptive Algorithm for Spatial Gray Scale." SID 1975, International Symposium Digest of Technical Papers, vol 1975m, pp. 36-37.

source

Ordered dithering

DitherPunk.OrderedDither — Type
OrderedDither(mat::AbstractMatrix, [max::Integer])

Generalized ordered dithering algorithm using a threshold map. Takes an unnormalized threshold matrix mat and optionally a normalization quotient max (defaults to length(mat)+1).

When applying the algorithm to an image, the threshold matrix is repeatedly tiled to match the size of the image. It is then applied as a per-pixel threshold map. Optionally, this final threshold map can be inverted by selecting invert_map=true.

source

Bayer

DitherPunk.Bayer — Function
Bayer([level=1]; kwargs...)

Ordered dithering using the Bayer matrix as a threshold matrix. The Bayer matrix is of dimension $2^{n+1} \times 2^{n+1}$, where $n$ is the level, which defaults to 1.

[1] Bayer, B.E., "An Optimum Method for Two-Level Rendition of Continuous Tone Pictures," IEEE International Conference on Communications, Conference Records, 1973, pp. 26-11 to 26-15.

source

Halftoning

DitherPunk.Rhombus — Function
Rhombus()

Diagonal ordered matrix with balanced centered points. Uses $8 \times 8$ threshold matrix RHOMBUS_MAT.

source

Threshold methods

DitherPunk.ClosestColor — Type

Simplest form of image quantization by turning each pixel to the closest one in the provided color palette cs. Technically this not a dithering algorithm as the quatization error is not "randomized".

source

Other

Utilities

Index

diff --git a/dev/assets/documenter.js b/dev/assets/documenter.js index f531160..82252a1 100644 --- a/dev/assets/documenter.js +++ b/dev/assets/documenter.js @@ -4,7 +4,6 @@ requirejs.config({ 'highlight-julia': 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/languages/julia.min', 'headroom': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/headroom.min', 'jqueryui': 'https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.13.2/jquery-ui.min', - 'minisearch': 'https://cdn.jsdelivr.net/npm/minisearch@6.1.0/dist/umd/index.min', 'katex-auto-render': 'https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.16.8/contrib/auto-render.min', 'jquery': 'https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.0/jquery.min', 'headroom-jquery': 'https://cdnjs.cloudflare.com/ajax/libs/headroom/0.12.0/jQuery.headroom.min', @@ -78,48 +77,54 @@ require(['jquery'], function($) { let timer = 0; var isExpanded = true; -$(document).on("click", ".docstring header", function () { - let articleToggleTitle = "Expand docstring"; - - debounce(() => { - if ($(this).siblings("section").is(":visible")) { - $(this) - .find(".docstring-article-toggle-button") - .removeClass("fa-chevron-down") - .addClass("fa-chevron-right"); - } else { - $(this) - .find(".docstring-article-toggle-button") - .removeClass("fa-chevron-right") - .addClass("fa-chevron-down"); +$(document).on( + "click", + ".docstring .docstring-article-toggle-button", + function () { + let articleToggleTitle = "Expand docstring"; + const parent = $(this).parent(); + + debounce(() => { + if (parent.siblings("section").is(":visible")) { + parent + .find("a.docstring-article-toggle-button") + .removeClass("fa-chevron-down") + .addClass("fa-chevron-right"); + } else { + parent + .find("a.docstring-article-toggle-button") + .removeClass("fa-chevron-right") + .addClass("fa-chevron-down"); - articleToggleTitle = "Collapse docstring"; - } + articleToggleTitle = "Collapse docstring"; + } - $(this) - .find(".docstring-article-toggle-button") - .prop("title", articleToggleTitle); - $(this).siblings("section").slideToggle(); - }); -}); + parent + .children(".docstring-article-toggle-button") + .prop("title", articleToggleTitle); + parent.siblings("section").slideToggle(); + }); + } +); -$(document).on("click", ".docs-article-toggle-button", function () { +$(document).on("click", ".docs-article-toggle-button", function (event) { let articleToggleTitle = "Expand docstring"; let navArticleToggleTitle = "Expand all docstrings"; + let animationSpeed = event.noToggleAnimation ? 0 : 400; debounce(() => { if (isExpanded) { $(this).removeClass("fa-chevron-up").addClass("fa-chevron-down"); - $(".docstring-article-toggle-button") + $("a.docstring-article-toggle-button") .removeClass("fa-chevron-down") .addClass("fa-chevron-right"); isExpanded = false; - $(".docstring section").slideUp(); + $(".docstring section").slideUp(animationSpeed); } else { $(this).removeClass("fa-chevron-down").addClass("fa-chevron-up"); - $(".docstring-article-toggle-button") + $("a.docstring-article-toggle-button") .removeClass("fa-chevron-right") .addClass("fa-chevron-down"); @@ -127,7 +132,7 @@ $(document).on("click", ".docs-article-toggle-button", function () { articleToggleTitle = "Collapse docstring"; navArticleToggleTitle = "Collapse all docstrings"; - $(".docstring section").slideDown(); + $(".docstring section").slideDown(animationSpeed); } $(this).prop("title", navArticleToggleTitle); @@ -224,224 +229,474 @@ $(document).ready(function () { }) //////////////////////////////////////////////////////////////////////////////// -require(['jquery', 'minisearch'], function($, minisearch) { - -// In general, most search related things will have "search" as a prefix. -// To get an in-depth about the thought process you can refer: https://hetarth02.hashnode.dev/series/gsoc +require(['jquery'], function($) { -let results = []; -let timer = undefined; +$(document).ready(function () { + let meta = $("div[data-docstringscollapsed]").data(); -let data = documenterSearchIndex["docs"].map((x, key) => { - x["id"] = key; // minisearch requires a unique for each object - return x; + if (meta?.docstringscollapsed) { + $("#documenter-article-toggle-button").trigger({ + type: "click", + noToggleAnimation: true, + }); + } }); -// list below is the lunr 2.1.3 list minus the intersect with names(Base) -// (all, any, get, in, is, only, which) and (do, else, for, let, where, while, with) -// ideally we'd just filter the original list but it's not available as a variable -const stopWords = new Set([ - "a", - "able", - "about", - "across", - "after", - "almost", - "also", - "am", - "among", - "an", - "and", - "are", - "as", - "at", - "be", - "because", - "been", - "but", - "by", - "can", - "cannot", - "could", - "dear", - "did", - "does", - "either", - "ever", - "every", - "from", - "got", - "had", - "has", - "have", - "he", - "her", - "hers", - "him", - "his", - "how", - "however", - "i", - "if", - "into", - "it", - "its", - "just", - "least", - "like", - "likely", - "may", - "me", - "might", - "most", - "must", - "my", - "neither", - "no", - "nor", - "not", - "of", - "off", - "often", - "on", - "or", - "other", - "our", - "own", - "rather", - "said", - "say", - "says", - "she", - "should", - "since", - "so", - "some", - "than", - "that", - "the", - "their", - "them", - "then", - "there", - "these", - "they", - "this", - "tis", - "to", - "too", - "twas", - "us", - "wants", - "was", - "we", - "were", - "what", - "when", - "who", - "whom", - "why", - "will", - "would", - "yet", - "you", - "your", -]); - -let index = new minisearch({ - fields: ["title", "text"], // fields to index for full-text search - storeFields: ["location", "title", "text", "category", "page"], // fields to return with search results - processTerm: (term) => { - let word = stopWords.has(term) ? null : term; - if (word) { - // custom trimmer that doesn't strip @ and !, which are used in julia macro and function names - word = word - .replace(/^[^a-zA-Z0-9@!]+/, "") - .replace(/[^a-zA-Z0-9@!]+$/, ""); - } +}) +//////////////////////////////////////////////////////////////////////////////// +require(['jquery'], function($) { - return word ?? null; - }, - // add . as a separator, because otherwise "title": "Documenter.Anchors.add!", would not find anything if searching for "add!", only for the entire qualification - tokenize: (string) => string.split(/[\s\-\.]+/), - // options which will be applied during the search - searchOptions: { - boost: { title: 100 }, - fuzzy: 2, +/* +To get an in-depth about the thought process you can refer: https://hetarth02.hashnode.dev/series/gsoc + +PSEUDOCODE: + +Searching happens automatically as the user types or adjusts the selected filters. +To preserve responsiveness, as much as possible of the slow parts of the search are done +in a web worker. Searching and result generation are done in the worker, and filtering and +DOM updates are done in the main thread. The filters are in the main thread as they should +be very quick to apply. This lets filters be changed without re-searching with minisearch +(which is possible even if filtering is on the worker thread) and also lets filters be +changed _while_ the worker is searching and without message passing (neither of which are +possible if filtering is on the worker thread) + +SEARCH WORKER: + +Import minisearch + +Build index + +On message from main thread + run search + find the first 200 unique results from each category, and compute their divs for display + note that this is necessary and sufficient information for the main thread to find the + first 200 unique results from any given filter set + post results to main thread + +MAIN: + +Launch worker + +Declare nonconstant globals (worker_is_running, last_search_text, unfiltered_results) + +On text update + if worker is not running, launch_search() + +launch_search + set worker_is_running to true, set last_search_text to the search text + post the search query to worker + +on message from worker + if last_search_text is not the same as the text in the search field, + the latest search result is not reflective of the latest search query, so update again + launch_search() + otherwise + set worker_is_running to false + + regardless, display the new search results to the user + save the unfiltered_results as a global + update_search() + +on filter click + adjust the filter selection + update_search() + +update_search + apply search filters by looping through the unfiltered_results and finding the first 200 + unique results that match the filters + + Update the DOM +*/ + +/////// SEARCH WORKER /////// + +function worker_function(documenterSearchIndex, documenterBaseURL, filters) { + importScripts( + "https://cdn.jsdelivr.net/npm/minisearch@6.1.0/dist/umd/index.min.js" + ); + + let data = documenterSearchIndex.map((x, key) => { + x["id"] = key; // minisearch requires a unique for each object + return x; + }); + + // list below is the lunr 2.1.3 list minus the intersect with names(Base) + // (all, any, get, in, is, only, which) and (do, else, for, let, where, while, with) + // ideally we'd just filter the original list but it's not available as a variable + const stopWords = new Set([ + "a", + "able", + "about", + "across", + "after", + "almost", + "also", + "am", + "among", + "an", + "and", + "are", + "as", + "at", + "be", + "because", + "been", + "but", + "by", + "can", + "cannot", + "could", + "dear", + "did", + "does", + "either", + "ever", + "every", + "from", + "got", + "had", + "has", + "have", + "he", + "her", + "hers", + "him", + "his", + "how", + "however", + "i", + "if", + "into", + "it", + "its", + "just", + "least", + "like", + "likely", + "may", + "me", + "might", + "most", + "must", + "my", + "neither", + "no", + "nor", + "not", + "of", + "off", + "often", + "on", + "or", + "other", + "our", + "own", + "rather", + "said", + "say", + "says", + "she", + "should", + "since", + "so", + "some", + "than", + "that", + "the", + "their", + "them", + "then", + "there", + "these", + "they", + "this", + "tis", + "to", + "too", + "twas", + "us", + "wants", + "was", + "we", + "were", + "what", + "when", + "who", + "whom", + "why", + "will", + "would", + "yet", + "you", + "your", + ]); + + let index = new MiniSearch({ + fields: ["title", "text"], // fields to index for full-text search + storeFields: ["location", "title", "text", "category", "page"], // fields to return with results processTerm: (term) => { let word = stopWords.has(term) ? null : term; if (word) { + // custom trimmer that doesn't strip @ and !, which are used in julia macro and function names word = word .replace(/^[^a-zA-Z0-9@!]+/, "") .replace(/[^a-zA-Z0-9@!]+$/, ""); + + word = word.toLowerCase(); } return word ?? null; }, + // add . as a separator, because otherwise "title": "Documenter.Anchors.add!", would not + // find anything if searching for "add!", only for the entire qualification tokenize: (string) => string.split(/[\s\-\.]+/), - }, -}); + // options which will be applied during the search + searchOptions: { + prefix: true, + boost: { title: 100 }, + fuzzy: 2, + }, + }); + + index.addAll(data); + + /** + * Used to map characters to HTML entities. + * Refer: https://github.com/lodash/lodash/blob/main/src/escape.ts + */ + const htmlEscapes = { + "&": "&", + "<": "<", + ">": ">", + '"': """, + "'": "'", + }; + + /** + * Used to match HTML entities and HTML characters. + * Refer: https://github.com/lodash/lodash/blob/main/src/escape.ts + */ + const reUnescapedHtml = /[&<>"']/g; + const reHasUnescapedHtml = RegExp(reUnescapedHtml.source); + + /** + * Escape function from lodash + * Refer: https://github.com/lodash/lodash/blob/main/src/escape.ts + */ + function escape(string) { + return string && reHasUnescapedHtml.test(string) + ? string.replace(reUnescapedHtml, (chr) => htmlEscapes[chr]) + : string || ""; + } -index.addAll(data); + /** + * RegX escape function from MDN + * Refer: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping + */ + function escapeRegExp(string) { + return string.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string + } -let filters = [...new Set(data.map((x) => x.category))]; -var modal_filters = make_modal_body_filters(filters); -var filter_results = []; + /** + * Make the result component given a minisearch result data object and the value + * of the search input as queryString. To view the result object structure, refer: + * https://lucaong.github.io/minisearch/modules/_minisearch_.html#searchresult + * + * @param {object} result + * @param {string} querystring + * @returns string + */ + function make_search_result(result, querystring) { + let search_divider = `
`; + let display_link = + result.location.slice(Math.max(0), Math.min(50, result.location.length)) + + (result.location.length > 30 ? "..." : ""); // To cut-off the link because it messes with the overflow of the whole div -$(document).on("keyup", ".documenter-search-input", function (event) { - // Adding a debounce to prevent disruptions from super-speed typing! - debounce(() => update_search(filter_results), 300); + if (result.page !== "") { + display_link += ` (${result.page})`; + } + searchstring = escapeRegExp(querystring); + let textindex = new RegExp(`${searchstring}`, "i").exec(result.text); + let text = + textindex !== null + ? result.text.slice( + Math.max(textindex.index - 100, 0), + Math.min( + textindex.index + querystring.length + 100, + result.text.length + ) + ) + : ""; // cut-off text before and after from the match + + text = text.length ? escape(text) : ""; + + let display_result = text.length + ? "..." + + text.replace( + new RegExp(`${escape(searchstring)}`, "i"), // For first occurrence + '$&' + ) + + "..." + : ""; // highlights the match + + let in_code = false; + if (!["page", "section"].includes(result.category.toLowerCase())) { + in_code = true; + } + + // We encode the full url to escape some special characters which can lead to broken links + let result_div = ` + +
+
${escape(result.title)}
+
${result.category}
+
+

+ ${display_result} +

+
+ ${display_link} +
+ + ${search_divider} + `; + + return result_div; + } + + self.onmessage = function (e) { + let query = e.data; + let results = index.search(query, { + filter: (result) => { + // Only return relevant results + return result.score >= 1; + }, + combineWith: "AND", + }); + + // Pre-filter to deduplicate and limit to 200 per category to the extent + // possible without knowing what the filters are. + let filtered_results = []; + let counts = {}; + for (let filter of filters) { + counts[filter] = 0; + } + let present = {}; + + for (let result of results) { + cat = result.category; + cnt = counts[cat]; + if (cnt < 200) { + id = cat + "---" + result.location; + if (present[id]) { + continue; + } + present[id] = true; + filtered_results.push({ + location: result.location, + category: cat, + div: make_search_result(result, query), + }); + } + } + + postMessage(filtered_results); + }; +} + +// `worker = Threads.@spawn worker_function(documenterSearchIndex)`, but in JavaScript! +const filters = [ + ...new Set(documenterSearchIndex["docs"].map((x) => x.category)), +]; +const worker_str = + "(" + + worker_function.toString() + + ")(" + + JSON.stringify(documenterSearchIndex["docs"]) + + "," + + JSON.stringify(documenterBaseURL) + + "," + + JSON.stringify(filters) + + ")"; +const worker_blob = new Blob([worker_str], { type: "text/javascript" }); +const worker = new Worker(URL.createObjectURL(worker_blob)); + +/////// SEARCH MAIN /////// + +// Whether the worker is currently handling a search. This is a boolean +// as the worker only ever handles 1 or 0 searches at a time. +var worker_is_running = false; + +// The last search text that was sent to the worker. This is used to determine +// if the worker should be launched again when it reports back results. +var last_search_text = ""; + +// The results of the last search. This, in combination with the state of the filters +// in the DOM, is used compute the results to display on calls to update_search. +var unfiltered_results = []; + +// Which filter is currently selected +var selected_filter = ""; + +$(document).on("input", ".documenter-search-input", function (event) { + if (!worker_is_running) { + launch_search(); + } }); +function launch_search() { + worker_is_running = true; + last_search_text = $(".documenter-search-input").val(); + worker.postMessage(last_search_text); +} + +worker.onmessage = function (e) { + if (last_search_text !== $(".documenter-search-input").val()) { + launch_search(); + } else { + worker_is_running = false; + } + + unfiltered_results = e.data; + update_search(); +}; + $(document).on("click", ".search-filter", function () { if ($(this).hasClass("search-filter-selected")) { - $(this).removeClass("search-filter-selected"); + selected_filter = ""; } else { - $(this).addClass("search-filter-selected"); + selected_filter = $(this).text().toLowerCase(); } - // Adding a debounce to prevent disruptions from crazy clicking! - debounce(() => get_filters(), 300); + // This updates search results and toggles classes for UI: + update_search(); }); -/** - * A debounce function, takes a function and an optional timeout in milliseconds - * - * @function callback - * @param {number} timeout - */ -function debounce(callback, timeout = 300) { - clearTimeout(timer); - timer = setTimeout(callback, timeout); -} - /** * Make/Update the search component - * - * @param {string[]} selected_filters */ -function update_search(selected_filters = []) { - let initial_search_body = ` -
Type something to get started!
- `; - +function update_search() { let querystring = $(".documenter-search-input").val(); if (querystring.trim()) { - results = index.search(querystring, { - filter: (result) => { - // Filtering results - if (selected_filters.length === 0) { - return result.score >= 1; - } else { - return ( - result.score >= 1 && selected_filters.includes(result.category) - ); - } - }, - }); + if (selected_filter == "") { + results = unfiltered_results; + } else { + results = unfiltered_results.filter((result) => { + return selected_filter == result.category.toLowerCase(); + }); + } let search_result_container = ``; + let modal_filters = make_modal_body_filters(); let search_divider = `
`; if (results.length) { @@ -449,19 +704,23 @@ function update_search(selected_filters = []) { let count = 0; let search_results = ""; - results.forEach(function (result) { - if (result.location) { - // Checking for duplication of results for the same page - if (!links.includes(result.location)) { - search_results += make_search_result(result, querystring); - count++; - } - + for (var i = 0, n = results.length; i < n && count < 200; ++i) { + let result = results[i]; + if (result.location && !links.includes(result.location)) { + search_results += result.div; + count++; links.push(result.location); } - }); + } - let result_count = `
${count} result(s)
`; + if (count == 1) { + count_str = "1 result"; + } else if (count == 200) { + count_str = "200+ results"; + } else { + count_str = count + " results"; + } + let result_count = `
${count_str}
`; search_result_container = `
@@ -490,125 +749,37 @@ function update_search(selected_filters = []) { $(".search-modal-card-body").html(search_result_container); } else { - filter_results = []; - modal_filters = make_modal_body_filters(filters, filter_results); - if (!$(".search-modal-card-body").hasClass("is-justify-content-center")) { $(".search-modal-card-body").addClass("is-justify-content-center"); } - $(".search-modal-card-body").html(initial_search_body); + $(".search-modal-card-body").html(` +
Type something to get started!
+ `); } } /** * Make the modal filter html * - * @param {string[]} filters - * @param {string[]} selected_filters * @returns string */ -function make_modal_body_filters(filters, selected_filters = []) { - let str = ``; - - filters.forEach((val) => { - if (selected_filters.includes(val)) { - str += `${val}`; - } else { - str += `${val}`; - } - }); +function make_modal_body_filters() { + let str = filters + .map((val) => { + if (selected_filter == val.toLowerCase()) { + return `${val}`; + } else { + return `${val}`; + } + }) + .join(""); - let filter_html = ` + return `
Filters: ${str} -
- `; - - return filter_html; -} - -/** - * Make the result component given a minisearch result data object and the value of the search input as queryString. - * To view the result object structure, refer: https://lucaong.github.io/minisearch/modules/_minisearch_.html#searchresult - * - * @param {object} result - * @param {string} querystring - * @returns string - */ -function make_search_result(result, querystring) { - let search_divider = `
`; - let display_link = - result.location.slice(Math.max(0), Math.min(50, result.location.length)) + - (result.location.length > 30 ? "..." : ""); // To cut-off the link because it messes with the overflow of the whole div - - if (result.page !== "") { - display_link += ` (${result.page})`; - } - - let textindex = new RegExp(`\\b${querystring}\\b`, "i").exec(result.text); - let text = - textindex !== null - ? result.text.slice( - Math.max(textindex.index - 100, 0), - Math.min( - textindex.index + querystring.length + 100, - result.text.length - ) - ) - : ""; // cut-off text before and after from the match - - let display_result = text.length - ? "..." + - text.replace( - new RegExp(`\\b${querystring}\\b`, "i"), // For first occurrence - '$&' - ) + - "..." - : ""; // highlights the match - - let in_code = false; - if (!["page", "section"].includes(result.category.toLowerCase())) { - in_code = true; - } - - // We encode the full url to escape some special characters which can lead to broken links - let result_div = ` - -
-
${result.title}
-
${result.category}
-
-

- ${display_result} -

-
- ${display_link} -
- - ${search_divider} - `; - - return result_div; -} - -/** - * Get selected filters, remake the filter html and lastly update the search modal - */ -function get_filters() { - let ele = $(".search-filters .search-filter-selected").get(); - filter_results = ele.map((x) => $(x).text().toLowerCase()); - modal_filters = make_modal_body_filters(filters, filter_results); - update_search(filter_results); +
`; } }) @@ -635,103 +806,107 @@ $(document).ready(function () { //////////////////////////////////////////////////////////////////////////////// require(['jquery'], function($) { -let search_modal_header = ` -
-
-

- - - - -

-
-
- -
-
-`; - -let initial_search_body = ` -
Type something to get started!
-`; - -let search_modal_footer = ` - -`; - -$(document.body).append( - ` -