feat(WordCloud): add paintcloud and paintsvgcloud functions

Author: guo-yong-zhi

README.md

@@ -39,8 +39,10 @@ wc = wordcloud(open(pkgdir(WordCloud)*"/res/alice.txt")) |> generate! # from a f
 wc = wordcloud(["中文", "需要", "提前", "分词"]) |> generate! # from a list
 ```
 ```julia
-wc = wordcloud(["the"=>1.0, "to"=>0.51, "and"=>0.50,
-                  "of"=>0.47, "a"=>0.44, "in"=>0.33]) |> generate! # from pairs or a dict
+wc = wordcloud(["the"=>1.0, "to"=>0.51, "and"=>0.50]) |> generate! # from pairs or a dict
+```
+```julia
+paintcloud("It's easy to generate word clouds") # obtain the final picture directly
 ```
 # Advanced Usage
 ```julia

src/WordCloud.jl

@@ -12,7 +12,7 @@ Please visit the repository at: <https://github.com/guo-yong-zhi/WordCloud.jl>
 module WordCloud
 export wordcloud, processtext, html2text, countwords, casemerge!, rescaleweights
 export parsecolor, rendertext, shape, ellipse, box, squircle, star, ngon, bezistar, bezingon,
-    loadmask, outline, padding, paint, paintsvg, svgstring
+    loadmask, outline, padding, paint, paintsvg, paintcloud, paintsvgcloud, svgstring
 export imageof, showmask, showmask!
 export record, @record, layout!, rescale!, recolor!, keep, ignore, pin, runexample, showexample, generate!, fit!
 export getparameter, setparameter!, hasparameter, getstate, setstate!,

src/wc-class.jl

@@ -72,6 +72,7 @@ For more sophisticated text processing, please utilize the function [`processtex
 * Notes
   * After obtaining the wordcloud object, the following steps are required to obtain the resulting picture: initialize! -> layout! -> generate! -> paint
   * You can skip `initialize!` and/or `layout!`, and these operations will be automatically performed with default parameters
+  * You can use [`paintcloud`](@ref) and [`paintsvgcloud`](@ref) to obtain the final picture directly.
 """
 wordcloud(wordsweights::Tuple; kargs...) = wordcloud(wordsweights...; kargs...)
 wordcloud(counter::AbstractDict; kargs...) = wordcloud(keys(counter) |> collect, values(counter) |> collect; kargs...)

src/wc-helper.jl

@@ -88,7 +88,7 @@ function loadmask(file, args...; kargs...)
     loadmask(mask, args...; kargs...)
 end
 
-"Similar to `paint`, but exports SVG"
+"Similar to [`paint`](@ref), but exports SVG"
 function paintsvg(wc::WC; background=true)
     imgs = getsvgimages(wc)
     poss = getpositions(wc)
@@ -123,6 +123,8 @@ function paintsvg(wc::WC, file, args...; kargs...)
 end
 
 """
+Paint the [`wordcloud`](@ref) generated object into an image or an SVG file.
+See also: [`paintsvg`](@ref)
 # Examples
 * paint(wc::WC)
 * paint(wc::WC, background=false) # without background
@@ -159,7 +161,37 @@ function paint(wc::WC, file, args...; kargs...)
     Render.save(file, img)
     img
 end
-        
+
+"""
+Generate a word cloud image from text. This function serves as a shortcut for `paint(generate!(wordcloud(...))...)`.
+For details on supported arguments, see:
+- [`wordcloud`](@ref)
+- [`paint`](@ref)
+See also: [`paintsvgcloud`](@ref)
+# Examples
+* paintcloud("holly bible")
+* paintcloud("holly bible", "result.svg")
+* paintcloud(["holly", "bible"], [0.7, 0.3], "result.png", background=false)
+* paintcloud("holly bible", angles=(0, 90), ratio=0.5)
+"""
+function paintcloud(args...; paintfunc=paint, kargs...)
+    if length(args) > 1 && last(args) isa AbstractString
+        args_w, args_p = args[1:end-1], args[end:end]
+    else
+    	args_w, args_p = args, ()
+    end
+    pkw = (:background, :ratio)
+    kargs_w = filter(kw -> first(kw) ∉ pkw, kargs)
+    kargs_p = filter(kw -> first(kw) ∈ pkw, kargs)
+    redirect_stdio(stdout=devnull, stderr=devnull) do
+        paintfunc(generate!(wordcloud(args_w...; kargs_w...)), args_p...; kargs_p...)
+    end
+end
+"Similar to [`paintcloud`](@ref), but exports SVG"
+function paintsvgcloud(args...; paintfunc=paintsvg, kargs...)
+    paintcloud(args...; paintfunc=paintfunc, kargs...)
+end
+
 function frame(wc::WC, label::AbstractString, args...; kargs...)
     overlay!(paint(wc, args...; kargs...), rendertextoutlines(label, 32, color="black", linecolor="white", linewidth=1), 20, 20)
 end

test/runtests.jl

@@ -16,6 +16,8 @@ include("test_textprocessing.jl")
     paint(wc, "test.jpg", background=outline(wc.mask, color=(1, 0, 0.2, 0.7), linewidth=2), ratio=0.5)
     paint(wc, "test.svg", background=WordCloud.tobitmap(wc.mask))
     paint(wc, "test.svg")
+    paintsvgcloud("holly bible", "test.svg")
+    paintcloud("holly bible", angles=(0, 90), ratio=0.5)
     show(wc)
     @test getparameter(wc, :volume) == WordCloud.occupancy(WordCloud.QTrees.kernel(wc.maskqtree[1]), WordCloud.QTrees.FULL)
     # animation