more interfaces & more documents

Author: guoyongzhi

.gitignore

@@ -1,5 +1,8 @@
 .ipynb_checkpoints
 .vscode
+*.cov
 res/*/*
 address_compare
-guxiang_animation
+guxiang_animation
+/*.png
+test/*.jpg

README.md

@@ -5,10 +5,12 @@ wordcloud in Julia
 * **Exact**  Words with the same weight have the exact same size. The algorithm will never scale the word to fit the blank.
 
 ---
-
+# Installation
+```julia
+import Pkg; Pkg.add("WordCloud")
+```
 # Basic Usage 
 ```julia
-]add WordCloud
 using WordCloud
 words = "天地玄黄宇宙洪荒日月盈昃辰宿列张寒来暑往秋收冬藏闰余成岁律吕调阳云腾致雨露结为霜金生丽水玉出昆冈剑号巨阙珠称夜光果珍李柰菜重芥姜海咸河淡鳞潜羽翔龙师火帝鸟官人皇始制文字乃服衣裳推位让国有虞陶唐吊民伐罪周发殷汤坐朝问道垂拱平章"
 words = [string(c) for c in words]
@@ -17,27 +19,34 @@ wc = wordcloud(words, weights)
 generate!(wc)
 paint(wc, "qianziwen.png")
 ```
-*Run the command `runexample(:qianziwen)` to get the result.*  
+*Run the command `runexample(:qianziwen)` or `showexample(:qianziwen)` to get the result.*  
 # More Complex Usage
 ```julia
+using WordCloud
 wc = wordcloud(
     process(open(pkgdir(WordCloud)*"/res/alice.txt"), stopwords=WordCloud.stopwords_en ∪ ["said"]), 
     mask = loadmask(pkgdir(WordCloud)*"/res/alice_mask.png", color="#faeef8"),
-    colors = (WordCloud.colorschemes[:Set1_5].colors..., ),
+    colors = :Set1_5,
     angles = (0, 90),
     fillingrate = 0.7) |> generate!
-paint(wc, "alice.png", ratio=0.5)
+paint(wc, "alice.png", ratio=0.5, background=outline(wc.mask, color="purple", linewidth=1))
 ```
-*Run the command `runexample(:alice)` to get the result.*  
+*Run the command `runexample(:alice)` or `showexample(:alice)` to get the result.*  
 ![alice](res/alice.png)
 
-# More
+# More Examples
+## Training animation
 ![animation](res/animation.gif)  
-[Training Animation](./examples/animation.jl)  
-*Run the command `runexample(:animation)` to get the result.*  
+[Training animation](./examples/animation.jl)  
+*Run the command `runexample(:animation)` or `showexample(:animation)` to get the result.* 
+## Specifies the style of a particular word
+![specifystyle](res/specifystyle.png)  
+[Specifies the style of a particular word](./examples/specifystyle.jl)  
+*Run the command `runexample(:specifystyle)` or `showexample(:specifystyle)` to get the result.* 
+## Comparison
 ![compare](res/compare.png)  
 [Comparison of Obama's and Trump's inaugural address](./examples/compare.jl)  
-*Run the command `runexample(:compare)` to get the result.*  
+*Run the command `runexample(:compare)` or `showexample(:compare)` to get the result.*  
 
 ***
 * [x] 排序 & 预放置

examples/alice.jl

@@ -2,8 +2,9 @@ using WordCloud
 wc = wordcloud(
     process(open(pkgdir(WordCloud)*"/res/alice.txt"), stopwords=WordCloud.stopwords_en ∪ ["said"]), 
     mask = loadmask(pkgdir(WordCloud)*"/res/alice_mask.png", color="#faeef8"),
-    colors = (WordCloud.colorschemes[:Set1_5].colors..., ),
+    colors = :Set1_5,
     angles = (0, 90),
     fillingrate = 0.7) |> generate!
+println("save results to alice.png")
 paint(wc, "alice.png", background=outline(wc.mask, color="purple", linewidth=1))
 wc

examples/animation.jl

@@ -7,7 +7,7 @@ texts = df[!, "Column2"]
 weights = df[!, "Column3"]
 
 wc = wordcloud(texts, weights, fillingrate=0.8)
-
-gifdirectory = "gg/guxiang_animation"
+println("save results to guxiang_animation")
+gifdirectory = "guxiang_animation"
 generate_animation!(wc, 100, outputdir=gifdirectory)
 wc

examples/compare.jl

@@ -1,6 +1,7 @@
 using WordCloud
 
 stwords = ["us", "will"];
+
 println("==Obama's==")
 cs = WordCloud.randomscheme()
 as = WordCloud.randomangles()
@@ -10,42 +11,42 @@ wca = wordcloud(
     colors = cs,
     angles = as,
     fillingrate = fr) |> generate!
+
 println("==Trump's==")
-tb, wb = process(open(pkgdir(WordCloud)*"/res/Donald Trump's Inaugural Address.txt"), stopwords=WordCloud.stopwords_en ∪ stwords)
-samemask = tb .∈ Ref(wca.words)
-println(sum(samemask), " same words")
-csb = Iterators.take(WordCloud.iter_expand(cs), length(tb)) |> collect
-asb = Iterators.take(WordCloud.iter_expand(as), length(tb)) |> collect
-wainds = Dict(zip(wca.words, Iterators.countfrom(1)))
-for i in 1:length(tb)
-    if samemask[i]
-        ii = wainds[tb[i]]
-        csb[i] = wca.params[:colors][ii]
-        asb[i] = wca.params[:angles][ii]
-    end
-end
 wcb = wordcloud(
-    (tb,wb), 
-    mask = wca.mask,
-    colors = csb,
-    angles = asb,
-    fillingrate = fr)
-for i in 1:length(tb)
-    if samemask[i]
-        ii = wainds[tb[i]]
-        cxy = WordCloud.QTree.center(wca.qtrees[ii])
-        WordCloud.QTree.setcenter!(wcb.qtrees[i], cxy)
-    end
+    process(open(pkgdir(WordCloud)*"/res/Donald Trump's Inaugural Address.txt"), stopwords=WordCloud.stopwords_en ∪ stwords),
+    mask = getmask(wca),
+    colors = cs,
+    angles = as,
+    fillingrate = fr,
+    run = x->nothing, #turn off the useless initword! and placement! in advance
+)
+
+samewords = getword(wca) ∩ getword(wcb)
+println(length(samewords), " same words")
+
+for w in samewords
+    setcolor!(wcb, w, getcolor(wca, w))
+    setangle!(wcb, w, getangle(wca, w))
 end
+#Follow these steps to generate result: initword! -> placement! -> generate!
+initword!(wcb)
+
 println("=ignore defferent words=")
-ignore(wcb, .!samemask) do
+ignore(wcb, getword(wcb) .∉ Ref(samewords)) do
+    @assert Set(wcb.words) == Set(samewords)
+    centers = getposition.(wca, samewords, type=getcenter)
+    setposition!.(wcb, samewords, centers, type=setcenter!) #manually initialize the position,
+    setstate!(wcb, :placement!) #and set the state flag
     generate!(wcb, 1000, patient=-1, retry=1) #patient=-1 means no teleport; retry=1 means no rescale
 end
+
 println("=pin same words=")
-pin(wcb, samemask) do
+pin(wcb, samewords) do
     placement!(wcb)
     generate!(wcb, 1000, retry=1) #allow teleport but don‘t allow rescale
 end
+
 if getstate(wcb) != :generate!
     println("=overall tuning=")
     generate!(wcb, 1000, patient=-1, retry=2) #allow rescale but don‘t allow teleport
@@ -54,10 +55,9 @@ end
 ma = paint(wca)
 mb = paint(wcb)
 h,w = size(ma)
-space = loadmask(shape(box, w÷20, h))
-space .= WordCloud.ARGB(0,0,0,0)
+space = fill(mb[1], (h, w÷20))
 try mkdir("address_compare") catch end
-
+println("save results to address_compare")
 WordCloud.ImageMagick.save("address_compare/compare.png", [ma space mb])
 
 gif = WordCloud.GIF("address_compare")

examples/specifystyle.jl

@@ -1,20 +1,23 @@
 using WordCloud
 wc = wordcloud(
-    process(open(pkgdir(WordCloud)*"/res/alice.txt"), stopwords=WordCloud.stopwords_en ∪ ["said"], maxweight=1, maxnum=200), 
+    process(open("res/alice.txt"), stopwords=WordCloud.stopwords_en ∪ ["said"], maxweight=1, maxnum=300), 
     mask = padding(shape(ellipse, 600, 500, color=(0.98, 0.97, 0.99), bgcolor=0.97), 0.1),
-    colors = (WordCloud.colorschemes[:seaborn_dark].colors..., ),
+    colors = :seaborn_dark,
     angles = -90:90,
     run=x->x, #turn off the useless initword! and placement! in advance
 )
 
-setangle!(wc, "Alice", 0)
-setcolor!(wc, "Alice", "purple");
-initword!(wc, "Alice", 2size(wc.mask, 2)/length("Alice"))
-setposition!(wc, "Alice", reverse((size(wc.mask) .- size(getimage(wc, "Alice"))) .÷ 2))
+setword!(wc, "Alice", "Alice in Wonderland") # replace the word 'Alice' with 'Alice in Wonderland'
+setangle!(wc, "Alice in Wonderland", 0) # make it horizontal
+setcolor!(wc, "Alice in Wonderland", "purple");
+initword!(wc, "Alice in Wonderland", 2size(wc.mask, 2)/length("Alice in Wonderland")) # set a big font size
+setposition!(wc, 1, reverse(size(wc.mask)) .÷ 2, type=setcenter!) # center it
 
-pin(wc, "Alice") do
-    initword!(wc)
+pin(wc, "Alice in Wonderland") do
+    initword!(wc) #init inside `pin` to reset the size of other words
     generate!(wc)
 end
+
+println("save results to specifystyle.png")
 paint(wc, "specifystyle.png")
 wc

src/WordCloud.jl

@@ -1,9 +1,10 @@
 module WordCloud
 export wordcloud, shape, ellipse, box, paint, loadmask, process, outline, padding,
     train!, Momentum, generate!, generate_animation!
-export record, parsecolor, placement!, imageof, bitor, take, ignore, pin, runexample, showexample
-export getstate, getcolor, getangle, getweight, setcolor!, setangle!, setweight!, 
-    getposition, setposition!, getimage, initword!
+export getshift, getcenter, setshift!, setcenter!
+export record, parsecolor, placement!, rescale!, imageof, bitor, take, ignore, pin, runexample, showexample
+export getstate, setstate!, getcolor, getangle, getword, getweight, setcolor!, setangle!, setweight!, setword!,
+    getposition, setposition!, getimage, getmask, initword!
 
 include("qtree.jl")
 include("rendering.jl")