三流Mayavi操作-Mayav-2.1.1-圖形控制函數 Figure handling functions

秉着邊學邊寫邊折騰的原則，開始粗糙的工作。真正掌握還是得講解給別人聽。 先給出網課
https://www.icourse163.org/course/BIT-1001871001
Mayavi官方
http://docs.enthought.com/mayavi/mayavi/genindex.html
（有時候這網站會裝死，一般過幾個小時就會活過來）
我發現了，光是三流操作還不夠，還得加上四流翻譯。

http://docs.enthought.com/mayavi/mayavi/auto/mlab_figure.html
這個文章我採用全文翻譯，而且保留原文的排版風格。中間畫蛇添足的方法進行解釋吧。
文章分爲2節，第一節是翻譯，中間例子和講解。爲了解決詳略不得當的問題，（以前就是詳略不得當）把需要大幅度展開的放在第2節作爲補充，並在第1節裏面註明擴充的位置。

0.可能用的上的代碼

這裏給出一段代碼<2.1.1-code 0>供調試用：

import numpy as np
from mayavi.mlab import *

x, y, z = np.mgrid[-4:4:40j, -4:4:40j, 0:4:20j]
r = np.sqrt(x ** 2 + y ** 2 + z ** 2 + 0.1)

u = y * np.sin(r) / r
v = -x * np.sin(r) / r
w = np.ones_like(z)*0.05

figure1 = figure(size=(600,600),bgcolor=(1,0,1),figure='Simple 1')
quiver3d(u, v, w,mask_points=20)
xlabel('x')
outline()
flow(u, v, w,linetype='tube',seed_visible=False)
figu = gcf()
# clf(figure1)
clf()
show()

1 全文翻譯及講解

Figure handling functions

clf

mayavi.mlab.clf(figure=None)
Clear the current figure.
You can also supply the figure that you want to clear.
清空當前的figure。
你也可以提供想要清理的figure。

[畫蛇添足]這個是清空當前繪製的內容的一個函數，準確地說不只是清空圖像，連數據源也一起清空了。
裏面可以接受一個參數就是figure

flow(u, v, w,linetype='tube',seed_visible=False)
clf()
clf緊隨其後，導致圖像連數據源都沒了。爽是爽了。就是圖有點冷。

另外figure可以指定。
如果開始賦值了figure的handle：

figure1 = figure(size=(600,600),bgcolor=(1,0,1),figure='Simple 1')
那麼後面就可以直接用clf(figure1)
得到的效果是完全一樣的~
.

.
.

close

mayavi.mlab.close(scene=None, all=False)
Close a figure window
關閉figure窗口。

[畫蛇添足]

這個技巧用在集成環境裏面。我這裏效果體現不多。
如果在show()前面插入close()，這個時候可視化圖像就沒有了。但是，這一點也是有用的，因爲就不用去繪製圖形了，跑起來更快了，拿來做計算不知道效果如何。和clf()不一樣，這次的數據源還在，沒有被清空，可以用其他函數把它調出來。

.
.

draw

mayavi.mlab.draw(figure=None)
Forces a redraw of the current figure.
重新繪製當前figure
.
.

figure

mayavi.mlab.figure(figure=None, bgcolor=None, fgcolor=None, engine=None, size=(400, 350))
Creates a new scene or retrieves an existing scene. If the mayavi engine is not running this also starts it.
創建一個新的scene或者檢索存在的scene，如果Mayavi的engine終止了，也可以使用它來開啓。

參數:

figure

The name of the figure, or handle to it.
figure的名字，或者handle(有些翻譯成句柄，我不想這麼翻譯，保留專業名詞。)

bgcolor:

The color of the background (None is default).
背景色，None是缺省值.
注意缺省值是 (127,127,127)，bg是background的縮寫。

從GUI裏面可以知道

fgcolor:

The color of the foreground, that is the color of all text annotation labels (axes, orientation axes, scalar bar labels). It should be sufficiently far from bgcolor to see the annotation texts. (None is default).
前景色，所謂前景色指的是所有的文字註釋標籤(座標軸，顯示標量的標籤等)，它的顏色應該明顯區別於背景色。(默認值是None)

orientation axes我沒有翻譯，不知道怎麼翻譯。這個axes和scalar bar labels都是Module層級的內容,屬於圖形修飾函數，後面會講，用xlable()可以調出來使用，它能給整個圖帶上座標軸。包括scalar bar labels也是一樣可以調出來，使用scalarbar()，這裏點到爲止。這章的內容是圖形控制，不是圖形修飾。
默認值從上面的GUI裏面看的出來，是（225,225,225），也就是白色。

engine:

The mayavi engine that controls the figure.
Mayavi的engine控制所有的figure

這是Mayavi的最高層級，或者是說最底層，看你怎麼理解，大概就是老大的性質。GUI裏面是不可見的，它用來建立和銷燬scene。

爲了避免內容太冗長，我把engine的內容放在文末作爲補充節單獨說一下

補充見文末

size:

The size of the scene created, in pixels. May not apply for certain scene viewer.
指定scene創建的交互窗口大小，單位用像素表示。可能不適用於一些場景查看器。
前半句很好理解，後面的場景查看器我沒用過，不是很清楚。

場景查看器？？留一個坑。

<2.1.1-code 0>裏面制定過size的大小，這個size是有默認值的,(400, 350)。確實比較小，如果要做很多大小一樣的圖，這裏就要做點小調整。
figure(size=(600,600),bgcolor=(1,0,1),figure='Simple 1')

.
.

gcf

mayavi.mlab.gcf(engine=None)
Return a handle to the current figure.
You can supply the engine from which you want to retrieve the current figure, if you have several mayavi engines.
返回當前figure的handle
如果存在多個Mayavi engine，你也可以提供你想返回的figure的engine。

.
.

savefig

mayavi.mlab.savefig(filename, size=None, figure=None, magnification='auto', **kwargs)
Save the current scene. The output format are deduced by the extension to filename. Possibilities are png, jpg, bmp, tiff, ps, eps, pdf, rib (renderman), oogl (geomview), iv (OpenInventor), vrml, obj (wavefront)
存儲當前的scene.輸出格式將由filename自動判斷。可能的擴展名png, jpg, bmp, tiff, ps, eps, pdf, rib (renderman), oogl (geomview), iv (OpenInventor), vrml, obj (wavefront)

參數

這段代碼報錯！未解決

Size:

the size of the image created (unless magnification is set, in which case it is the size of the window used for rendering).
創建的圖像大小.(除非 magnification 已經設定，這種情況下它是渲染的窗口大小。)

Figure:

the figure instance to save to a file.
存儲爲文件的figure實例

這個可以用gcf捕捉返回handle傳進來

Magnification:

the magnification is the scaling between the pixels on the screen, and the pixels in the file saved. If you do not specify it, it will be calculated so that the file is saved with the specified size. If you specify a magnification, Mayavi will use the given size as a screen size, and the file size will be ‘magnification * size’.
Magnification是像素的放縮倍數。如果不指定Magnification參數，它將按照指定的size存儲爲文件，如果指定，Mayavi會使用給定的size，此時文件的size將會變成 magnification*size

注意

If the size specified is larger than the window size, and no magnification parameter is passed, the magnification of the scene is changed so that the image created has the requested size. Please note that if you are trying to save images with sizes larger than the window size, there will be additional computation cost.
Any extra keyword arguments are passed along to the respective image format’s save method.
.
如果size被指定但是比渲染的窗口大，卻沒有傳入magnification參數，magnification將會發生改變來適應圖像被要求的大小來存儲。請注意如果你嘗試存儲圖像的大小大於渲染的窗口的大小，將會產生額外的運算量。
所有參數的傳入方式應該遵循不同圖像格式的存儲方式。

.
.

screenshot

mayavi.mlab.screenshot(figure=None, mode='rgb', antialiased=False)
Return the current figure pixmap as an array.

參數

Figure:

a figure instance or None, optional If specified, the figure instance to capture the view of.
接受一個figure實例或者None，如果指定了參數，這figure實例的圖像將會被捕捉

Mode:

{‘rgb’, ‘rgba’} The color mode of the array captured.
接受{‘rgb’, ‘rgba’} ，捕獲的色彩模式。

Antialiased:

{True, False} Use anti-aliasing for rendering the screenshot. Uses the number of aa frames set by figure.scene.anti_aliasing_frames
接受{True, False}，對screenshot的渲染圖像使用反鋸齒 。

這裏沒說清楚

Notes

On most systems, this works similarly to taking a screenshot of the rendering window. Thus if it is hidden by another window, you will capture the other window. This limitation is due to the heavy use of the hardware graphics system.
在大多數系統裏，它的工作方式類似於一種對渲染窗口的screenshot截屏。如果它被其他窗口遮蓋了，則會捕捉到其他窗口。這就限制了在硬件圖像系統的大量使用。(hardware graphics system，我不知道怎麼翻譯)

翻譯可能有問題

This function can be useful for integrating 3D plotting with Mayavi in a 2D plot created by matplotlib.
這個函數對3D圖像轉化爲2D圖像將會很有用。

一個例子

from mayavi import mlab
mlab.test_plot3d()
arr = mlab.screenshot()
import pylab as pl
pl.imshow(arr)
pl.axis('off')
pl.show()

.
.

sync_camera

mayavi.mlab.sync_camera(reference_figure, target_figure)
Synchronise the camera of the target_figure on the camera of the reference_figure.
這個沒有多講，回頭再補充。
.
.

2 補充

1.關於engine的問題

先放兩篇文章
http://docs.enthought.com/mayavi/mayavi/advanced_scripting.html
http://docs.enthought.com/mayavi/mayavi/auto/example_multiple_engines.html

填坑區:
這一節有很多地方都沒說清楚，回頭來補充例子。

更新(2018.12.12）
2018.12.11.——更新到screenshot
2018.12.12.——更完（都不好意思說更完，這週末來把中間坑坑窪窪的洞填一下。）