VisPy 中文文檔：APP模塊

01-28

英文原文

APP 模塊定義了三個類：應用程序 Application，畫布 Canvas，以及計時器 Timer。VisPy 在載入的時候，會創建一個默認的應用程序實例，該實例可以在模塊的命名空間內通過函數調用來使用。

vispy.app.use_app(backend_name=None, call_reuse=True)The app module - VisPy

獲取/創建一個默認的應用程序對象。

多次調用這個函數也是安全的，只要後端名字 backend_name 設置為 None 或者匹配已選定的後端 backend 就行。

參數: backend_name : str 字元串類型或者 None

該參數是設置要使用的後端應用的名字。如果沒有指定，VisPy 會常識自動選擇一個後端。更多內容參考vispy.use()。

call_reuse : 布爾值

該參數是設置是否調用後端的 reuse() 函數，默認設為 True。默認情況下是不執行的，不過某些後端需要用到這個函數。例如在 notebook 後端裡面，調用了 user_app() 之後就需要立即注入某些 JavaScript 文件。

vispy.app.create()The app module - VisPy

創建本地應用程序。

vispy.app.run()The app module - VisPy

進入本地 GUI 事件循環。

vispy.app.quit()The app module - VisPy

退出本地 GUI 事件循環。

vispy.app.process_envets()The app module - VisPy

處理等候中的事件。如果主循環沒有雲行，就要經常運行這個函數，來保持可視化界面的交互，並保證事件系統的運行。

class vispy.app.A.Application(backend_name=None)

代表了 VisPy 應用程序。

這個類打包了一個本地 GUI 應用程序的實例。 VisPy 有一個默認的該類的實例，可以通過 vispy.app.use_app()來創建或者獲取。

參數: backend_name : str 字元串類型或者 None

該參數是設置要使用的後端應用的名字。如果沒有指定，VisPy 會常識自動選擇一個後端。更多內容參考vispy.use()。

特別注意

創建一個應用程序對象的時候，會選擇一個後端，但本地後端應用對象只在 create() 函數被調用或者 native 被使用的時候才會創建。Canvas 畫布和 Timer 計時器會自動進行創建。

方法：

create() 創建本地應用 is_interactive() 探知用戶是否要求類交互模式process_events() 處理所有等待中的 GUI 事件 quit() 退出本地 GUI 事件循環 reuse()在交互對話中重新使用應用程序時再次對應用進行調用 run([allow_interactive]) 進入本地 GUI 事件循環 sleep(duration_sec) 沉睡指定的秒數

backend_module

定義後端的模塊對象。

backend_name

應用打包的 GUI 後端名。

方法：

backend_module

定義後端的模塊對象。

backend_name

應用打包的 GUI 後端名。

creat()

創建本地應

creat()

創建本地應用程序。

is_interactive()

探知用戶是否要求使用交互模式。

native

本地 GUI 應用程序實例。

process_events()

處理等候中的 GUI 事件。如果主循環沒有雲行，就要經常運行這個函數，來保持可視化界面的交互，並保證事件系統的運行。

quit()

退出本地 GUI 事件循環。

reuse()

在交互對話中重新使用應用程序時再次對應用進行調用。當用戶多次調用use_app()的時候，這允許後端可以在客戶端內進行一些任務。例如在 notebook 後端裡面，調用了 user_app() 之後就需要立即注入某些 JavaScript 文件。

run(allow_interactive=True)

進入本地 GUI 事件循環。參數： allow_interactive : 布爾值

這個參數用來表示是否允許在控制台終端下使用交互模式。默認輸入 python -i main.py 就可以進入一個互動式的 shell，也會調用 VisPy 事件循環。在這種情況下，run() 函數會立即終結，然後在腳本執行之後，根據解釋器內的輸入循環來判定是否繼續運行。

sleep(duration_sec)

休眠指定的事件（秒數）。這是為了在 VisPy 以交互模式運行的時候降低 CPU 的負荷。更多內容可以參考 inputhook.py。

參數： duration_sec: float 浮點數

這個變數就是休眠的秒數。

class vispy.app.A.Canvas(title=Vispy canvas, size=(800, 600), position=None, show=False, autoswap=True, app=None, create_native=True, vsync=False, resizable=True, decorate=True, fullscreen=False, config=None, shared=None, keys=None, parent=None, dpi=None, always_on_top=False, px_scale=1)

這個類表示一個含有 OpenGL 環境的 GUI 元素。

參數: title : str 字元串

控制項的標題。

size : (width, height)

窗口的尺寸。（寬度，高度）

position : (x, y)

窗口在屏幕坐標系中的位置。

show : bool 布爾值

是否立即顯示控制項，默認為 False。

autoswap : bool

在一次繪製事件之後是否自動交換緩衝區。默認為 True。如果為 True，則在 canvas.draw 事件處理器之後，將會緊接著就調用 swap_buffers 這一 Canvas 方法。 app : Application 應用程序或者 str 字元串
提供一個 VisPy 的應用程序實例，來用作後端。（默認使用 vispy.app。）如果用字元串，則根據這個字元串選擇某一個應用程序作為後端，例如可用pyglet。可以注意一下這裡的 Canvas 應用可以通過 canvas.app 來讀取。

create_native : bool 布爾值

判斷是否立即創建控制項。默認為 True。

vsync : bool 布爾值

是否開啟垂直同步。

resizable : bool 布爾值

是否允許窗口重新調整大小。

decorate : bool 布爾值

是否裝飾你窗口。默認為 True。

fullscreen : bool 布爾值或者 int 整形

如果是 False，則默認使用窗口模式。如果為 True，會在默認顯示器上全屏。如果給出 int 值，則用此值編號的顯示器來全屏顯示。

config : dict 詞典

含有 OpenGL 配置選項的一個詞典，包含在默認配置選項中，用於環境初始化。參考 canvas.context.config 來看可選的選項。

shared : Canvas 或者 GLContext 或者 None

一個已經存在的 Canvas 對象，或者可分享 OpenGL 對象的環境。

keys : str 字元串或 dict 詞典或 None

要使用的默認鍵映射。如果是 interactive，則 ESC 和 F11 這兩個鍵分別對應了關閉畫布和切換全屏這兩個功能。如果是 dict，就把鍵映射到函數。如果 dict 中都是字元串，就當做是 Canvas 的方法，要麼就得是可調用的。

parent : widget-object 控制項對象

父控制項，如果對選用的後端來說這個對象存在的話。

dpi : float 浮點數或 None

Canvas 畫布使用的解析度，單位英寸的像素數。如果設置為 None，那就優先根據全局設定來探測，其次就是採用操作系統的設定。

always_on_top : bool 布爾值

是否讓圖像總在最頂層，如果設為 True，創建的窗口就會始終在頂層。

px_scale : int > 0 正整數

對應邏輯和物理像素之間關係的縮放參數，對後端確定的實際縮放參數的一補充。此選項允許調整縮放參數進行測試。

特別注意

Canvas 接收下列事件：

initialize 初始化

resize 重新調整大小

draw 繪製

mouse_press 滑鼠按下

mouse_release 滑鼠釋放

mouse_double_click 滑鼠雙擊

mouse_move 滑鼠移動

mouse_wheel 滑鼠滾輪

key_press 按鍵按下

key_release 按鍵釋放

stylus 手寫筆？

touch 觸碰

close 關閉？接近？

mouse_double_click 滑鼠雙擊，mouse_press 滑鼠按下和 mouse_release 滑鼠釋放事件的順序在後端之間無法保證一致。目前只有某些後端（ Qt 和 WX ）原生支持雙擊; 在其他後端，要對這些滑鼠事件以某一個固定的時間延遲來進行手動檢測。這可能會導致易用性問題，因為會增加操作系統在檢測上話費的時間，或者又不能使用一種專門的雙擊按鈕。

方法：

close() 關閉當前畫布 Canvas。

connect(fun) 把某個函數連接到一個事件上。

create_native() 如果沒有創建原生控制項則進行創建。

measure_fps([window, callback]) 顯示當前每秒鐘幀數 FPS。

set_current([event]) 設置當前 Canvas 為活動 GL Canvas。

show([visible, run]) 顯示或者隱藏 Canvas。

swap_buffers([event]) 交換GL緩衝區，使屏幕外緩衝區可見。

update([event]) 通知後端對當前 Canavas 進行重繪。

app 當前 Canvas 基於的 VisPy 應用程序實例。

close() 關閉當前 Canvas。

特別注意

close 這個函數一旦調用了，通常會清除 GL 環境。以 QT 為例，如果當前控制項是頂層控制項，這就會清除 GL 環境和控制項。想要和 QT 的標準行為一致，避免摧毀控制項，建議把控制項設置成子控制項。

connect(fun)

把某個函數連接到一個事件上。這裡的函數名字應該是 on_X 模式的，X 在這裡表示的是事件名字，例如繪製事件就是 on_draw。

此方法通常是裝飾器，在事件處理程序的函數定義中。

參數: fun : callable 可調用的函數

就是要連接的那個函數啦。

context

原生控制項的 OpenGL 環境。

在 Canvas 對象中通過調用這個屬性來使用 OpenGL 函數，以及分享環境的命名空間。

create_native()

若未創建原生控制項則進行創建。如果已經創建了，則該函數不進行任何操作。

dpi

Canvas 畫布中每英寸上的像素數，物理解析度。

fps

Canvas 畫布或者窗口的幀率，每秒鐘的幀數，events.draw 執行的頻率。

measure_fps(window=1, callback=%1.1f FPS)

測試當前 FPS。設置更新的窗口，連接到 draw 繪製事件到 update_fps 函數並設置回調函數。

參數: window : float 浮點數

窗口計算 FPS 的時間，單位是秒，默認是1.0。

callback : function 函數或 str 字元串

伴隨浮點數 FPS 值而要調用的函數，如果是字元串的話，就是 fps 值的格式化字元串。默認的是%1.1f FPS。如果回調為 False 了，則停止 FPS 檢測。

native

當前 Canvas 畫布所處的原生控制項對象。

physical_size

當前 Canvas 畫布或者 Window 窗口的物理尺寸，各種不同後端提供的 HiDPI 不同所以有不同的尺寸屬性。

pixel_scale

像素比例，邏輯像素（點數）與顯示設備上的物理像素的比值。通常都是1.0，不過有的後端可能會比 1 大。當用戶自己用 Gloo 來編寫自己的可視化方案時，可以設置成一個縮放參數，（複製並乘以所有邏輯像素值），但盡量少這樣做，除非你要構建自己的視覺（Visuals）或場景可視化（SceneGraph）; 而應該在SceneGraph畫布中應用canvas_fb_transform。

position

當前 Canvas 畫布或在 Window 窗口相對屏幕的位置。

set_current(event=None)

設置當前 Canvas 為活動 GL Canvas。

參數: event : None

不使用。

show(visible=True, run=False)

顯示或隱藏 Canvas 畫布。

參數: visible : bool 布爾值

使 Canvas 畫布可見。

run : bool 布爾值

運行後端事件循環。

size

Canvas 畫布或 Window 窗口的尺寸。

swap_buffers(event=None)

交換GL緩衝區，使屏幕外緩衝區可見。

參數: event : None

不使用。

title

Canvas 畫布或 Window 窗口的標題

update(event=None)

通知後端對 Canvas 畫布進行重繪。

參數: event : None

不使用。

class ### vispy.app.Timer(interval=auto, connect=None, iterations=-1, start=False, app=None)

計時器 Timer 用來規劃未來事件或重複事件。

參數: interval : float 浮點數或者 auto

事件之間的時間間隔。默認是 auto，就是讓程序去查找當前屏幕的刷新率所匹配的時間間隔。目前一般就是 1/60。（譯者註：因為通常的顯示器刷新率是 60Hz。）

connect : function 函數或者 None

調用的函數

iterations : int 整形

迭代次數。如果設為 -1 則無限進行下去。

start : bool 布爾值

判斷是否啟動計時器。

app : instance of vispy.app.Application

vispy.app.Appllicantion 的實例，要附加計時器 Timer 的對象。

方法：

connect(callback) self.events.timeout.connect() 的別名 disconnect([callback]) self.events.timeout.disconnect() 的別名 start([interval, iterations]) 啟動計時器。 stop() 停止計時器。

app

Timer 計時器所處的 VisPy 應用程序實例。

connect(callback)

self.events.timeout.connect() 的別名。

disconnect(callback=None)

self.events.timeout.disconnect() 的別名。

native

Timer 所基於的原生計時器。

start(interval=None, iterations=None)

啟動計時器。每間隔指定的秒數 interval，計時器事件就會被生成。如果間隔的秒數 interval設為 None，就會使用 self.interval 來替代 interval。

如果指定了 迭代次數 iterations，那麼計時器 Timer 在完成了這些次數後就會停止。如果沒有指定這個次數，就會使用 self.iterations 裡面存儲的上一次的值。如果給 iterations 設一個負值，計時器就會一直運行下去，知道 stop() 函數被調用了才停止。

如果這個函數調用的時候計時器早已經在運行了，就不會有任何效果。（計時器還會跟之前一樣繼續運行，對迭代的間隔和次數都不影響，也不會開始一個新的計時器啟動事件。）

stop()

停止計時器。