資料整體的品質

首先可以對整個資料集做一個初步的檢查，包含

1. 瀏覽整份資料集
2. 確認沒有嚴重有誤的照片(例如全黑的照片)
3. 確認所有照片都能夠被電腦讀取(以免訓練到一半程式被中斷)

照片尺寸和深寬比

對於整份資料集，統計所有照片的深寬比和尺寸十分重要，這些將會影響anchor size 和 ratios。通常有三種情況

1. 照片大小和深寬比都一樣:
   只需要決定縮放比例
2. 照片大小和深寬比不同但差異不大，深寬比都介於0.7~1.5:
   可以non-destructive resize(也就是不改變深寬比的縮放) -> padding
3. 照片大小和深寬比差異很大

參考:
https://neptune.ai/blog/data-exploration-for-image-segmentation-and-object-detection

Makefiles用途

用來決定大型程式需要被重新編譯的部分。

第一個範例

首先安裝make，並且將下面程式放到名稱為Makefile的檔案裡面。注意Makefile必須要用TAB來縮排而不是用空白鍵。

1
2

hello:
	echo "Hello, World"

接下來在Makefile所在的資料夾位置下make指令

1
2
3

$ make
echo "Hello, World"
Hello, World

Makefile語法

Makefile是由許多的規則組合而成，每一條則看起來如下

1
2
3
4

targets: prerequisites
	command
	command
	command

• targets是檔案名稱，用空白建作為分隔。通常每個rule只有一個target
• command是產生targets的一系列的步驟。command以Tab作為開頭，而不是空白鍵。
• prerequisites也是檔案名稱，以空白鍵作為分隔，這些是指令開始製作target前必須存在的檔案，因此這些檔案也可以稱為dependencies

Make基礎元素

1
2
3

hello:
	echo "Hello, World"
	echo "This line will always print, because the file hello does not exist."

以這個範例來說，

• 有一個名為hello的target
• 這個target有兩個command
• 這個target沒有prerequisites
  接下來我們執行make hello，由於hello檔不存在，所以下面的指令會被執行。如果hello檔存在，make就不會做任何事。
  特別注意在這裡hello同時代表target以及檔案，因為通常來說下面的command執行的目的就是要生成target。
  下面舉一個編譯c語言的例子，首先我們製作一個blah.c檔。

  1 2	// blah.c int main() { return 0; }

  接下來製作另一個Makefile。

  1 2	blah: cc blah.c -o blah

  接下來執行make，因為我們每有在第一個參數指定目標target，所以第一個target會被執行。第一次執行的時blah檔會被生成，如果再執行一次就會出現make: 'blah' is up to date的訊息，因為blah檔已經存在了。但是這有一個問題，如果我們更動blah.c檔案，make並不會重新編譯!!
  要解決這個問題就必須要增加prerequisite。

  1 2	blah: blah.c cc blah.c -o blah

  我們增加了blah的prerequisite，這時候make就除了檢查blah有沒有存在以外，還會另外去檢查blah.c是不是比blah還新。這裡我們可以看到make是利用系統的時間戳來判定blah.c有沒有被修改過，因此如果修改blah.c之後又把blah.c時間戳改回修改前的時間，那make就會以為blah.c沒有被修改過。

Make clean

clean常用來清除make產生的檔案，但是他並不是make的關鍵字。可以用make clean清除make產生的檔案。我們可以在makefile中編寫clean要清除的檔案。注意clean這個target除非你用make clean指令，不然他不會被執行。

1
2
3
4
5

some_file: 
	touch some_file

clean:
	rm -f some_file

Makefile使用相對路徑

1

rootdir = $(realpath .)

https://stackoverflow.com/a/3342259

Variables

變數Variables只能夠是字串，並且用:=賦值。對make來說單引號跟雙引號並意義，make會把他當成字元來處理。因此賦值的時候不需要加引號。
下面範例使用Variables

1
2
3
4
5
6
7
8
9
10
11
12

files := file1 file2
some_file: $(files)
	echo "Look at this variable: " $(files)
	touch some_file

file1:
	touch file1
file2:
	touch file2

clean:
	rm -f file1 file2 some_file

要引用變數可以用${}或是$()

1
2
3
4
5
6
7
8

x := dude

all:
	echo $(x)
	echo ${x}

	# Bad practice, but works
	echo $x 

Targets

all target

可以用來依次產生所有需要的target，通常會放在第一個target的位置，如此一來只要下make指令就可以生成所有target。

1
2
3
4
5
6
7
8
9
10
11

all: one two three

one:
	touch one
two:
	touch two
three:
	touch three

clean:
	rm -f one two three

多個target

當一個rule有多個target的時候，底下的command就會針對每一個target都跑一次。
$@就是一個有target名稱的automatic variable，下面範例就可以用$@看看現在command正在執行的是哪一個target

1
2
3
4
5
6
7
8
9

all: f1.o f2.o

f1.o f2.o:
	echo $@
# Equivalent to:
# f1.o:
#	 echo f1.o
# f2.o:
#	 echo f2.o

Automatic Variables and Wildcards

* 萬用字元

在cmake中*和%在cmake中都是萬用字元，但是它們代表的意義不一樣。*最好要包裝在wildcard 萬用字符函式中。否則可能會常陷入下面常見的陷阱。

1. 陷阱: *不能直接在變量定義中使用
2. 陷阱: 當*未匹配任何文件時，它會保持不變（除非在萬用字符函數(wildcard)中運行）。

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

   thing_wrong := *.o # Don't do this! '*' will not get expanded thing_right := $(wildcard *.o) all: one two three four # Fails, because $(thing_wrong) is the string "*.o" one: $(thing_wrong) # Stays as *.o if there are no files that match this pattern :( two: *.o # Works as you would expect! In this case, it does nothing. three: $(thing_right) # Same as rule three four: $(wildcard *.o)

% 萬用字元

%非常有用，但由於它可以在各種情況下使用，因此有些令人困惑。

1. 在“匹配”模式下使用時，它會在字符串中匹配一個或多個字符。此匹配稱為stem。
2. 在“替換”模式下使用時，它會取出匹配的stem，並將其替換為一個字符串。
3. ％在規則定義和某些特定函數中最常用。

Automatic Variables

這裡有完整的Automatic Variables表，下面只介紹常用的

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

hey: one two
	# Outputs "hey", since this is the target name
    # 印出目前的target
	echo $@

	# Outputs all prerequisites newer than the target
    # 印出所有比target新的prerequisite
	echo $?

	# Outputs all prerequisites
    # 印出所有的prerequisite
	echo $^

	touch hey

one:
	touch one

two:
	touch two

clean:
	rm -f hey one two

Rules

Make的隱藏規則

CC CXX CFLAGS CXXFLAGS LDFLAGS LDLIBS這些變數是make的隱藏規則。

• CC : 編譯C語言的編譯器; 預設是 cc
• CXX : 編譯C++語言的編譯器; 預設是 g++
• CFLAGS : 給C語言編譯器的額外參數
• CXXFLAGS : 給C++語言編譯器的額外參數
• CPPFLAGS : 給C/C++編譯器的額外參數
• LDFLAGS : 給連結器的額外參數

下面範例使用隱藏規則

1
2
3
4
5
6
7
8
9
10
11
12

CC = gcc # 使用gcc來編譯C語言
CFLAGS = -g # 給gcc的額外參數，開啟debug模式

# 隱藏規則 #1: blah會由C連接器產生(即使我們的command沒有呼叫C連接器)
# 隱藏規則 #2: blah.o 會由c編譯器產生，因為blah.c存在(即使我們的command沒有呼叫c編譯器)
blah: blah.o

blah.c:
	echo "int main() { return 0; }" > blah.c

clean:
	rm -f blah*

Static Pattern Rules

他的語法如下

1
2

targets...: target-pattern: prereq-patterns ...
   commands

這個語法的意思是，如果有一個target符合target-pattern(利用% wildcard)，且它的所有prerequisite都符合prereq-patterns，那麼就會執行commands。
例如我們可以改寫下面makefile

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

objects = foo.o bar.o all.o
all: $(objects)

# These files compile via implicit rules
foo.o: foo.c
bar.o: bar.c
all.o: all.c

all.c:
	echo "int main() { return 0; }" > all.c

%.c:
	touch $@

clean:
	rm -f *.c *.o all

改寫後如下，可以看到，我們把foo.o bar.o all.o的規則都合併成一個規則$(objects): %.o: %.c。首先foo.o符合%.o，且它的所有prerequisite都符合%.c，因此會執行%.o: %.c的規則。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

objects = foo.o bar.o all.o
all: $(objects)

# These files compile via implicit rules
# Syntax - targets ...: target-pattern: prereq-patterns ...
# In the case of the first target, foo.o, the target-pattern matches foo.o and sets the "stem" to be "foo".
# It then replaces the '%' in prereq-patterns with that stem
$(objects): %.o: %.c

all.c:
	echo "int main() { return 0; }" > all.c

%.c:
	touch $@

clean:
	rm -f *.c *.o all

Static Pattern Rules and Filter

此外，我們可以使用filter函式來過濾掉不需要的檔案，後面會再講到函式這裡只是先展示如何跟函式搭配使用，在下面的範例我們使用了 .raw 和 .result 這兩個擴展名。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

obj_files = foo.result bar.o lose.o
src_files = foo.raw bar.c lose.c

all: $(obj_files)
# Note: PHONY is important here. Without it, implicit rules will try to build the executable "all", since the prereqs are ".o" files.
.PHONY: all 

# Ex 1: .o files depend on .c files. Though we don't actually make the .o file.
$(filter %.o,$(obj_files)): %.o: %.c
	@echo "target: $@ prereq: $<"

# Ex 2: .result files depend on .raw files. Though we don't actually make the .result file.
$(filter %.result,$(obj_files)): %.result: %.raw
	@echo "target: $@ prereq: $<" 

%.c %.raw:
	@echo "touch $@ prereq: $<" 
	touch $@

clean:
	rm -f $(src_files)

執行的結果如下，首先執行第一條規則all: $(obj_files)產生第一個target foo.result，並由$(filter %.result,$(obj_files)): %.result: %.raw產生foo.result。foo.result的prerequisitfoo.raw由%.c %.raw:產生。
可以看到，我們把foo.result bar.o lose.o的規則都合併成一個規則$(filter %.result,$(obj_files)): %.result: %.raw。首先foo.result符合%.result，且它的所有prerequisite都符合%.raw，因此會執行%.result: %.raw的規則。

1
2
3
4
5
6

touch foo.raw
target: foo.result prereq: foo.raw
touch bar.c
target: bar.o prereq: bar.c
touch lose.c
target: lose.o prereq: lose.c

Pattern Rules

我們可以將Pattern Rules視為兩種用法。

• 自定義的implicit rules

  1 2 3

  # 自訂一個 pattern rule 將每一個.c檔編譯成.o檔 %.o : %.c $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@

• 簡化版的static pattern rules

  1 2 3 4

  # 定義一個沒有 prerequisites 的 pattern rule # 他將會在需要的時候產出一個空白的.c檔 %.c: touch $@

  在這裡%代表任意非空白的字串。

Double-Colon Rules

Double-Colon Rules 很少被用到，他允許對同一個target定義多個規則，且這些規則可以是不同的commands。如以下範例

1
2
3
4
5
6
7

all: blah

blah::
	@echo "hello"

blah::
	@echo "hello again"

他的輸出是

1
2

hello
hello again

Commands and execution

指令回顯/禁用

在預設情況下，make會回顯每一個command，如果你不想要回顯，可以在command前面加上@，如下

1
2
3

all: 
	@echo "This make line will not be printed"
	echo "But this will"

命令執行

每一行命令都會在一個新的shell中執行，因此如果你想要在同一個shell中執行，可以使用分號;來連接命令，如下

1
2
3
4
5
6
7
8
9
10
11

all: 
	cd ..
	# The cd above does not affect this line, because each command is effectively run in a new shell
	echo `pwd`

	# This cd command affects the next because they are on the same line
	cd ..;echo `pwd`

	# Same as above
	cd ..; \
	echo `pwd`

預設shell

預設情況下，make會使用/bin/sh來執行命令，如果你想要使用其他的shell，可以使用.SHELL來指定，如下

1
2
3
4

SHELL=/bin/bash

cool:
	echo "Hello from bash"

$$符號

在Makefile中，$$代表一個$符號，如此一來，我們就可以在Makefile中使用bash或是sh的shell variable。在下面這個例子中特別注一一下 Makefile variables 和 Shell variables

1
2
3
4
5
6
7

make_var = I am a make variable
all:
	# Same as running "sh_var='I am a shell variable'; echo $sh_var" in the shell
	sh_var='I am a shell variable'; echo $$sh_var

	# Same as running "echo I am a make variable" in the shell
	echo $(make_var)

用-k、-i、-進行錯誤處理

執行make的時候使用-k參數可以讓make繼續執行，即使其中一個target失敗了。執行make的時候使用-i參數可以讓make忽略所有的錯誤。

在command前面加上-可以讓make忽略該command的錯誤，如下

1
2
3
4

one:
	# This error will be printed but ignored, and make will continue to run
	-false
	touch one

打斷或是結束make

ctrl + c可以打斷或是結束make，他將會刪掉剛生成的target

遞迴使用 make

為了遞迴調用 Makefile，使用特殊的 $(MAKE) 代替 make，因為它將為您傳遞 make 標誌，並且不會受到這些標誌的影響。

當使用 $(MAKE) 來遞迴調用 Makefile 時，它將傳遞先前用於調用 make 的所有標誌和選項，以及在 Makefile 中定義的任何其他變量。這有助於確保在整個項目中使用相同的編譯選項和變量。同時，$(MAKE) 不會受到當前 make 的影響，這可以避免不必要的錯誤和不一致性。

1
2
3
4
5
6
7
8

new_contents = "hello:\n\ttouch inside_file"
all:
	mkdir -p subdir
	printf $(new_contents) | sed -e 's/^ //' > subdir/makefile
	cd subdir && $(MAKE)

clean:
	rm -rf subdir

Export, environments, and recursive make

當make執行的時候，他會先把所有環境變數轉換成make的變數，例如下面範例假如我們先在shell設定環境變數shell_env_var。

1. 設定環境並且執行make

   1	export shell_env_var='I am an environment variable'; make

2. 執行下面的makefile

   1 2 3 4 5 6

   all: # Print out the Shell variable echo $$shell_env_var # Print out the Make variable echo $(shell_env_var)

• make的export指令可以把make的變數直接轉換成環境變數

  1 2 3 4 5

  shell_env_var=Shell env var, created inside of Make export shell_env_var all: echo $(shell_env_var) echo $$shell_env_var

如此一來當我們在make command呼叫make的時候，就可以利用export指令將變數傳遞給子make程式。下面範例中cooly變數會被傳遞到子資料夾內所執行的make的makefile裡面。這裡可以注意到，cooly變數在all target之前被定義，但是他還是可以被all target使用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

new_contents = "hello:\n\techo \$$(cooly)"

all:
	mkdir -p subdir
	printf $(new_contents) | sed -e 's/^ //' > subdir/makefile
	@echo "---MAKEFILE CONTENTS---"
	@cd subdir && cat makefile
	@echo "---END MAKEFILE CONTENTS---"
	cd subdir && $(MAKE)

# Note that variables and exports. They are set/affected globally.
cooly = "The subdirectory can see me!"
export cooly
# This would nullify the line above: unexport cooly

clean:
	rm -rf subdir

• .EXPORT_ALL_VARIABLES
.EXPORT_ALL_VARIABLES可以直接把所有的make變數都轉換成環境變數

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

  .EXPORT_ALL_VARIABLES: new_contents = "hello:\n\techo \$$(cooly)" cooly = "The subdirectory can see me!" # This would nullify the line above: unexport cooly all: mkdir -p subdir printf $(new_contents) | sed -e 's/^ //' > subdir/makefile @echo "---MAKEFILE CONTENTS---" @cd subdir && cat makefile @echo "---END MAKEFILE CONTENTS---" cd subdir && $(MAKE) clean: rm -rf subdir

make的命令列選項

這裡有make的命令列選項，可以注意--dry-run, --touch, --old-file這幾個。
另外make可以一次接受多個target，例如make clean run test就會先執行clean，接著run和test。

變數part2

兩種賦值方法

• 延遲賦值（lazy evaluation）=:

  1 2 3 4 5 6 7

  VAR = foo VAR2 = $(VAR) VAR = bar all: # 在此處 VAR2 的值將是 "bar"，因為VAR2直到被真正使用展開 echo $(VAR2)

  ?=這個符號可以為沒被設定過的店數設定值

  1 2 3 4 5 6 7

  one = hello one ?= will not be set #one被設定過了，所以沒作用 two ?= will be set #two還沒被設定做，將設定值 all: echo $(one) echo $(two)

  輸出如下

  1 2 3 4

  echo hello hello echo will be set will be set

• 立即賦值（immediate assignment）:=:

  1 2 3 4 5 6 7

  VAR := foo VAR2 := $(VAR) VAR := bar all: # 在此處 VAR2 的值將是 "foo"，因為VAR2在:=的時候就展開了 echo $(VAR2)

  因此:=可以append variable，如果是=就會齣戲無窮迴圈錯誤

  1 2 3 4 5 6 7

  one = hello # 這段程式可以運行 # one gets defined as a simply expanded variable (:=) and thus can handle appending one := ${one} there all: echo $(one)

  下面這段程式會出現無窮迴圈錯誤。

  1 2 3 4 5 6

  one = hello # 注意這裡用的是 = ,會造成無窮迴圈錯誤 one = ${one} there all: echo $(one)

空白

一行字起頭的空白會被make忽略掉，但是尾巴空白的不會，要在起頭加空白可以用$(nullstring)，更精確地說其實未定義的變數都是empty string

1
2
3
4
5
6
7
8
9

with_spaces =   hello   # with_spaces has many spaces after "hello"
after = $(with_spaces)there

start_space = $(nullstring) hello

all: 
	echo "$(after)"
	echo "$(start_space)"
    echo $(nowhere) #這也會輸出empty string

append

+=可以用來append variable

1
2
3
4
5

foo := start
foo += more

all: 
	echo $(foo)

覆寫make命列列參數

override可以用來覆寫make命令列參數，例如下面這個例子，分別用make option_one=hi和make option_two=hi去執行，可以發現只有option_one會被覆寫

1
2
3
4
5
6
7

# Overrides command line arguments
override option_one = did_override
# Does not override command line arguments
option_two = not_override
all: 
	echo $(option_one)
	echo $(option_two)

針對target設定變數

變數可以只設定給指定的target，例如下面例子，one只定義給all target

1
2
3
4
5
6
7

all: one = cool

all: 
	echo one is defined: $(one)

other:
	echo one is nothing: $(one)

Pattern-specific variables

變數也可以指定義給特定的target patterns，例如下面例子，只有符合%.cpattern的target會被定義one

1
2
3
4
5
6
7

%.c: one = cool

blah.c: 
	echo one is defined: $(one)

other:
	echo one is nothing: $(one)

Makefile判斷式

if/else

1
2
3
4
5
6
7
8

foo = ok

all:
ifeq ($(foo), ok)
	echo "foo equals ok"
else
	echo "nope"
endif

檢查變數是否為空

1
2
3
4
5
6
7
8
9
10

nullstring =
foo = $(nullstring) # end of line; there is a space here

all:
ifeq ($(strip $(foo)),)
	echo "foo is empty after being stripped"
endif
ifeq ($(nullstring),)
	echo "nullstring doesn't even have spaces"
endif

檢查變數是否被定義

1
2
3
4
5
6
7
8
9
10

bar =
foo = $(bar)

all:
ifdef foo
	echo "foo is defined"
endif
ifndef bar
	echo "but bar is not"
endif

$(MAKEFLAGS)

下面範例展示如何使用 findstring 和 MAKEFLAGS 測試 make flag。分別用make指令和make -i指令執行下面makefile

1
2
3
4
5

all:
# Search for the "-i" flag. MAKEFLAGS is just a list of single characters, one per flag. So look for "i" in this case.
ifneq (,$(findstring i, $(MAKEFLAGS)))
	echo "i was passed to MAKEFLAGS"
endif

Functions

First Functions

函式主要用來處理文字。呼叫函式的方法有$(fn, arguments)或${fn, arguments}，而make也內建許多函式。例如subst替換掉文字。

1
2
3

bar := ${subst not, totally, "I am not superman"}
all: 
	@echo $(bar)

而如果你相替換掉空白或是逗號，可以利用變數。

1
2
3
4
5
6
7
8

comma := ,
empty:=
space := $(empty) $(empty)
foo := a b c
bar := $(subst $(space),$(comma),$(foo))

all: 
	@echo $(bar)

特別注意到不要在逗號和下一個參數之間留空白，因為它會被視為文字。

1
2
3
4
5
6
7
8
9

comma := ,
empty:=
space := $(empty) $(empty)
foo := a b c
bar := $(subst $(space), $(comma) , $(foo))

all: 
	# Output is ", a , b , c". Notice the spaces introduced
	@echo $(bar)

字串替換

函式$(patsubst pattern,replacement,text)的功能如下。

1
2
3
4
5
6
7
8
9
10
11

foo := a.o b.o l.a c.o
one := $(patsubst %.o,%.c,$(foo))
# This is a shorthand for the above
two := $(foo:%.o=%.c)
# This is the suffix-only shorthand, and is also equivalent to the above.
three := $(foo:.o=.c)

all:
	echo $(one)
	echo $(two)
	echo $(three)

The foreach function

foreach函式的用法為$(foreach var,list,text)，foreach會把以空白間區隔文字的list一個一個賦值給var，而text會累加前面的結果，範例如下

1
2
3
4
5
6
7

foo := who are you
# For each "word" in foo, output that same word with an exclamation after
bar := $(foreach wrd,$(foo),$(wrd)!)

all:
	# Output is "who! are! you!"
	@echo $(bar)

if function

用法如下

1
2
3
4
5
6
7

foo := $(if this-is-not-empty,then!,else!)
empty :=
bar := $(if $(empty),then!,else!)

all:
	@echo $(foo)
	@echo $(bar)

The call function

make可以用call來呼叫自定義函式

1
2
3
4
5

sweet_new_fn = Variable Name: $(0) First: $(1) Second: $(2) Empty Variable: $(3)

all:
	# Outputs "Variable Name: sweet_new_fn First: go Second: tigers Empty Variable:"
	@echo $(call sweet_new_fn, go, tigers)

The shell function

make也可以呼叫shell函式，但是會把輸出的換行符號改成空白鍵

其他功能

Include Makefiles

使用Include可以讓makefile裡面呼叫其他makefile

vpath 指令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

vpath %.h ../headers ../other-directory

# Note: vpath allows blah.h to be found even though blah.h is never in the current directory
some_binary: ../headers blah.h
	touch some_binary

../headers:
	mkdir ../headers

# We call the target blah.h instead of ../headers/blah.h, because that's the prereq that some_binary is looking for
# Typically, blah.h would already exist and you wouldn't need this.
blah.h:
	touch ../headers/blah.h

clean:
	rm -rf ../headers
	rm -f some_binary

換行

指令太長可以利用\換行

1
2
3

some_file: 
	echo This line is too long, so \
		it is broken up into multiple lines

.phony

在目標中添加”.PHONY”將防止Make將虛擬目標與文件名混淆。在這個例子中，如果創建了名為”clean”的文件，”make clean”仍然會運行。從技術上講，我應該在每個帶有”all”或”clean”的例子中都使用它，但為了保持例子的清晰，我沒有這樣做。此外，”phony”目標通常具有很少用作文件名的名稱，在實踐中許多人都會跳過這一步。

1
2
3
4
5
6
7
8

some_file:
	touch some_file
	touch clean

.PHONY: clean
clean:
	rm -f some_file
	rm -f clean

.delete_on_error

如果命令返回非零的退出狀態，make工具將停止運行規則（並將向前傳播到前置要求）。
DELETE_ON_ERROR將在規則以這種方式失敗時刪除該規則的目標。這將對所有目標發生，不僅僅是像PHONY這樣的目標。儘管由於歷史原因，make工具沒有使用這個選項，但始終使用它是一個好主意。

1
2
3
4
5
6
7
8
9
10

.DELETE_ON_ERROR:
all: one two

one:
	touch one
	false

two:
	touch two
	false

VNC使用ubuntu桌面
https://bytexd.com/how-to-install-configure-vnc-server-on-ubuntu/#google_vignette

VNC操作指令
http://kito.wikidot.com/vnc

清乾淨apt package
https://askubuntu.com/questions/187888/what-is-the-correct-way-to-completely-remove-an-application

刪除並重啟vnc server

1
2

vncserver -kill :1
vncserver -localhost no :1

參考:
https://www.digitalocean.com/community/tutorials/how-to-install-and-configure-vnc-on-ubuntu-20-04

客製化模型實作nvinfer介面

nvinfer呼叫介面

任何客製化介面最終必須被編譯成一個獨立的shared library。nvinfer在執行期間利用dlopen()呼叫函式庫，並且利用dlsym()呼叫函式庫中的函式。進一步的資訊紀錄在nvdsinfer_custom_impl.h裡面https://docs.nvidia.com/metropolis/deepstream/sdk-api/nvdsinfer__custom__impl_8h.html

客製化Output Parsing

• 對於detectors使用者必須自行解析模型的輸出並且將之轉化成bounding box 座標和物件類別。對於classifiers則是必須自行解析出物件屬性。範例在/opt/nvidia/deepstream/deepstream/sources/libs/nvdsinfer_customparser，裡面的README有關於使用custom parser的說明。

• 客製化parsing function必須為NvDsInferParseCustomFunc型態。在nvdsinfer_custom_impl.h的221行可以看到下面的型態定義，代表每一個客製化的解析函式都必須符合這個格式

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

  /** * Type definition for the custom bounding box parsing function. * * @param[in] outputLayersInfo A vector containing information on the output * layers of the model. * @param[in] networkInfo Network information. * @param[in] detectionParams Detection parameters required for parsing * objects. * @param[out] objectList A reference to a vector in which the function * is to add parsed objects. */ typedef bool (* NvDsInferParseCustomFunc) ( std::vector<NvDsInferLayerInfo> const &outputLayersInfo, NvDsInferNetworkInfo const &networkInfo, NvDsInferParseDetectionParams const &detectionParams, std::vector<NvDsInferObjectDetectionInfo> &objectList);

• 客製化parsing function可以在Gst-nvinfer的參數檔parse-bbox-func-name和custom-lib-name屬性指定。例如我們定義了Yolov2-tiny的客製化bounding box解析函式NvDsInferParseCustomYoloV2Tiny，編譯出來的shared library位於nvdsinfer_custom_impl_Yolo/libnvdsinfer_custom_impl_Yolo.so，我們在設定檔就就必須要有以下設定

  1 2	parse-bbox-func-name=NvDsInferParseCustomYoloV2Tiny custom-lib-path=nvdsinfer_custom_impl_Yolo/libnvdsinfer_custom_impl_Yolo.so

可以藉由在定義函式後呼叫CHECK_CUSTOM_PARSE_FUNC_PROTOTYPE()marco來驗證函式的定義。
使用範例如下

1
2
3
4
5
6
7
8
9

extern "C" bool NvDsInferParseCustomYoloV2Tiny(
    std::vector<NvDsInferLayerInfo> const& outputLayersInfo,
    NvDsInferNetworkInfo const& networkInfo,
    NvDsInferParseDetectionParams const& detectionParams,
    std::vector<NvDsInferParseObjectInfo>& objectList)
{
    ...
}
CHECK_CUSTOM_PARSE_FUNC_PROTOTYPE(NvDsInferParseCustomYoloV2Tiny);

https://forums.developer.nvidia.com/t/deepstreamsdk-4-0-1-custom-yolov3-tiny-error/108391?u=jenhao

IPlugin Implementation

對於TensorRT不支援的network layer，Deepstream提供IPlugin interface來客製化處理。在/opt/nvidia/deepstream/deepstream/sources底下的objectDetector_SSD, objectDetector_FasterRCNN, 和 objectDetector_YoloV3資料夾展示了如何使用custom layers。

在objectDetector_YoloV3範例中我們可以看到如何製作Tensorrt不支援的Yolov3的yolo layer。可以在yolo.cpp中看到自定義的layer是如何被呼叫使用的，程式節錄如下。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

....
else if (m_ConfigBlocks.at(i).at("type") == "yolo") {
            nvinfer1::Dims prevTensorDims = previous->getDimensions();
            assert(prevTensorDims.d[1] == prevTensorDims.d[2]);
            TensorInfo& curYoloTensor = m_OutputTensors.at(outputTensorCount);
            curYoloTensor.gridSize = prevTensorDims.d[1];
            curYoloTensor.stride = m_InputW / curYoloTensor.gridSize;
            m_OutputTensors.at(outputTensorCount).volume = curYoloTensor.gridSize
                * curYoloTensor.gridSize
                * (curYoloTensor.numBBoxes * (5 + curYoloTensor.numClasses));
            std::string layerName = "yolo_" + std::to_string(i);
            curYoloTensor.blobName = layerName;
            nvinfer1::IPluginV2* yoloPlugin
                = new YoloLayerV3(m_OutputTensors.at(outputTensorCount).numBBoxes,
                                  m_OutputTensors.at(outputTensorCount).numClasses,
                                  m_OutputTensors.at(outputTensorCount).gridSize);
            assert(yoloPlugin != nullptr);
            nvinfer1::IPluginV2Layer* yolo =
                network.addPluginV2(&previous, 1, *yoloPlugin);
            assert(yolo != nullptr);
            yolo->setName(layerName.c_str());
            std::string inputVol = dimsToString(previous->getDimensions());
            previous = yolo->getOutput(0);
            assert(previous != nullptr);
            previous->setName(layerName.c_str());
            std::string outputVol = dimsToString(previous->getDimensions());
            network.markOutput(*previous);
            channels = getNumChannels(previous);
            tensorOutputs.push_back(yolo->getOutput(0));
            printLayerInfo(layerIndex, "yolo", inputVol, outputVol, std::to_string(weightPtr));
            ++outputTensorCount;
        }
...

而其他版本的YOLO，Nvidia也已經幫我們建立好許多Plugin，例如yolov2的region layer，Nvidia已經幫我們建立，其他已經建立好的layer可以在這裡找到。
https://github.com/NVIDIA/TensorRT/tree/1c0e3fdd039c92e584430a2ed91b4e2612e375b8/plugin

畫出範例的結構圖

首先在~/.bashrc加入下面這行設定pipeline圖儲存的位置，注意GStreamer不會幫你建立資料夾，你必須確認資料夾存在

1

export GST_DEBUG_DUMP_DOT_DIR=/tmp

接下來在pipeline 狀態設為PLAYING之前加入下面這行程式

1

GST_DEBUG_BIN_TO_DOT_FILE(pipeline, GST_DEBUG_GRAPH_SHOW_ALL, "dstest1-pipeline");

最後執行程式後就會產生.dot在前面設定的資料夾，你可以下載Graphviz，或是用VScode的插件來看圖

Deepstream 說明書

https://docs.nvidia.com/metropolis/deepstream/dev-guide/text/DS_plugin_gst-nvdsxfer.html

gst-launch-1.0建立rtsp輸入源的pipeline

首先先用gst-launch-1.0建立一個簡單的rtsp輸入、螢幕輸出的pipeline

1

gst-launch-1.0 rtspsrc location='rtsp://192.168.1.10:554/user=admin_password=xxxxxx_channel=1_stream=0.sdp' ! rtph264depay ! h264parse ! nvv4l2decoder ! nvvideoconvert ! video/x-raw,format=BGRx ! videoconvert ! video/x-raw,format=BGR ! autovideosink

將python的範例程式轉成c++

https://github.com/NVIDIA-AI-IOT/deepstream_python_apps/tree/master/apps/deepstream-rtsp-in-rtsp-out

建立mjpeg串流

1. 指令方式

   1 2 3 4

   gst-launch-1.0 -v rtspsrc location="rtsp://<rtsp url>/live1.sdp" \ ! rtph264depay ! avdec_h264 \ ! timeoverlay halignment=right valignment=bottom \ ! videorate ! video/x-raw,framerate=37000/1001 ! jpegenc ! multifilesink location="snapshot.jpeg"

   https://stackoverflow.com/questions/59885450/jpeg-live-stream-in-html-slow

查詢deepstream bin的說明

1

gst-inspect-1.0 nvurisrcbin

gst-launch-1.0輸出除錯訊息到檔案

參考:
https://www.cnblogs.com/xleng/p/12228720.html

1

GST_DEBUG_NO_COLOR=1 GST_DEBUG_FILE=pipeline.log GST_DEBUG=5 gst-launch-1.0 -v rtspsrc location="rtsp://192.168.8.19/live.sdp" user-id="root" user-pw="3edc\$RFV" ! rtph264depay ! avdec_h264 ! timeoverlay halignment=right valignment=bottom ! videorate ! video/x-raw,framerate=37000/1001 ! jpegenc ! multifilesink location="snapshot.jpeg"

參考:
https://gstreamer.freedesktop.org/documentation/tutorials/basic/debugging-tools.html?gi-language=c
https://embeddedartistry.com/blog/2018/02/22/generating-gstreamer-pipeline-graphs/

本地端觀看udp傳送影像

host設為本機ip或127.0.0.1

send:

1

gst-launch-1.0 -v videotestsrc ! x264enc tune=zerolatency bitrate=500 speed-preset=superfast ! rtph264pay ! udpsink port=5000 host=$HOST

receive:

1

gst-launch-1.0 -v udpsrc port=5000 ! "application/x-rtp, media=(string)video, clock-rate=(int)90000, encoding-name=(string)H264, payload=(int)96" ! rtph264depay ! h264parse ! avdec_h264 ! videoconvert ! autovideosink

Glibs說明書

http://irtfweb.ifa.hawaii.edu/SoftwareDocs/gtk20/glib/glib-hash-tables.html#g-int-hash

GDB文字圖形介面

https://blog.louie.lu/2016/09/12/gdb-%E9%8C%A6%E5%9B%8A%E5%A6%99%E8%A8%88/

範例

https://gist.github.com/liviaerxin/bb34725037fd04afa76ef9252c2ee875#tips-for-debug

rtsp 元件nvrtspoutsinkbin

nvrtspoutsinkbin沒有說明書，只能用gst-inspect-1.0看
https://forums.developer.nvidia.com/t/where-can-fine-nvrtspoutsinkbin-info/199124

範例
/opt/nvidia/deepstream/deepstream/sources/apps/sample_apps/deepstream_reference_apps/deepstream-bodypose-3d/sources/deepstream_pose_estimation_app.cpp

1
2
3
4
5
6
7
8
9
10
11
12
13
14

/* Create RTSP output bin */
rtsp_out_bin = gst_element_factory_make ("nvrtspoutsinkbin", "nvrtsp-renderer");

if (!rtsp_out_bin) {
  g_printerr ("Failed to create RTSP output elements. Exiting.\n");
  return -1;
}

g_object_set (G_OBJECT (rtsp_out_bin), "sync", TRUE, NULL);
g_object_set (G_OBJECT (rtsp_out_bin), "bitrate", 768000, NULL);
g_object_set (G_OBJECT (rtsp_out_bin), "rtsp-port", rtsp_port_num, NULL);
g_object_set (G_OBJECT (rtsp_out_bin), "enc-type", enc_type, NULL);

gst_bin_add_many (GST_BIN (pipeline), rtsp_out_bin, NULL);

取得source id

https://forums.developer.nvidia.com/t/how-to-get-sources-index-in-deepstream/244461

可以用prob取得meta data
deepstream_test3_app.c 有範例

probe使用範例

切換輸入源

https://forums.developer.nvidia.com/t/how-switch-camera-output-gst-nvmultistreamtiler/233062

1
2
3

tiler_sink_pad.add_probe(Gst.PadProbeType.BUFFER, tiler_sink_pad_buffer_probe, 0)

tiler.set_property("show-source", <stream_id>) `

/opt/nvidia/deepstream/deepstream/sources/apps/apps-common/src/deepstream-yaml/deepstream_source_yaml.cpp有範例

斷線重連

rust的插件(可能可以編譯成c函式庫)
https://coaxion.net/blog/2020/07/automatic-retry-on-error-and-fallback-stream-handling-for-gstreamer-sources/

https://gitlab.freedesktop.org/gstreamer/gst-plugins-rs/-/tree/master/utils/fallbackswitch

編譯rust插件
https://www.collabora.com/news-and-blog/blog/2020/06/23/cross-building-rust-gstreamer-plugins-for-the-raspberry-pi/

RUST說明書
https://rust-lang.tw/book-tw/ch01-03-hello-cargo.html

截出有物件的圖

https://forums.developer.nvidia.com/t/saving-frame-with-detected-object-jetson-nano-ds4-0-2/121797/3

關閉Ubuntu圖形介面

https://linuxconfig.org/how-to-disable-enable-gui-on-boot-in-ubuntu-20-04-focal-fossa-linux-desktop

關閉使用gpu的資源

https://heary.cn/posts/Linux环境下重装NVIDIA驱动报错kernel-module-nvidia-modeset-in-use问题分析/

發現nvidia smi persistence mode會占用GPU資源，必須釋放掉才能安裝新的driver
可以用nvidia-smi的指令關掉https://docs.nvidia.com/deploy/driver-persistence/index.html#usage

1

nvidia-smi -pm 0

移除舊的driver

1
2

apt-get remove --purge nvidia-driver-520
apt-get autoremove

queue的用途

https://docs.xilinx.com/r/en-US/ug1449-multimedia/Performance-Improvement-from-the-GStreamer-Perspective

probe

https://coaxion.net/blog/2014/01/gstreamer-dynamic-pipelines/

https://erit-lvx.medium.com/probes-handling-in-gstreamer-pipelines-3f96ea367f31

deepstream-test4 用prob取得metadata的範例

NvDsBatchMeta資料圖:
https://docs.nvidia.com/metropolis/deepstream/dev-guide/text/DS_plugin_metadata.html

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

static GstPadProbeReturn
osd_sink_pad_buffer_probe (GstPad * pad, GstPadProbeInfo * info,
    gpointer u_data)
{
  GstBuffer *buf = (GstBuffer *) info->data;
  NvDsFrameMeta *frame_meta = NULL;
  NvOSD_TextParams *txt_params = NULL;
  guint vehicle_count = 0;
  guint person_count = 0;
  gboolean is_first_object = TRUE;
  NvDsMetaList *l_frame, *l_obj;

  NvDsBatchMeta *batch_meta = gst_buffer_get_nvds_batch_meta (buf);
  if (!batch_meta) {
    // No batch meta attached.
    return GST_PAD_PROBE_OK;
  }

  //batch_meta : NvDsBatchMeta https://docs.nvidia.com/metropolis/deepstream/sdk-api/struct__NvDsBatchMeta.html
  //
  //l_frame : NvDsFrameMetaList, 本質是GList http://irtfweb.ifa.hawaii.edu/SoftwareDocs/gtk20/glib/glib-doubly-linked-lists.html#GList
  //   struct GList
  // {
  //   gpointer data;
  //   GList *next;
  //   GList *prev;
  // };

  for (l_frame = batch_meta->frame_meta_list; l_frame; l_frame = l_frame->next) {
    frame_meta = (NvDsFrameMeta *) l_frame->data;

    if (frame_meta == NULL) {
      // Ignore Null frame meta.
      continue;
    }

    is_first_object = TRUE;

    // frame_meta : NvDsFrameMeta https://docs.nvidia.com/metropolis/deepstream/sdk-api/struct__NvDsFrameMeta.html
    // l_obj : NvDsObjectMetaList * 本質是GList 
    // obj_meta : NvDsObjectMeta
    for (l_obj = frame_meta->obj_meta_list; l_obj; l_obj = l_obj->next) {
      NvDsObjectMeta *obj_meta = (NvDsObjectMeta *) l_obj->data;

      if (obj_meta == NULL) {
        // Ignore Null object.
        continue;
      }

      // obj_meta : NvDsObjectMeta
      // text_params : NvOSD_TextParams 描述物件的文字
      // line233 - 241應該是清掉原本的文字然後放入字定義的class名稱
      txt_params = &(obj_meta->text_params);
      if (txt_params->display_text)
        g_free (txt_params->display_text);

      txt_params->display_text = g_malloc0 (MAX_DISPLAY_LEN);

      g_snprintf (txt_params->display_text, MAX_DISPLAY_LEN, "%s ",
          pgie_classes_str[obj_meta->class_id]);

      if (obj_meta->class_id == PGIE_CLASS_ID_VEHICLE)
        vehicle_count++;
      if (obj_meta->class_id == PGIE_CLASS_ID_PERSON)
        person_count++;

      /* Now set the offsets where the string should appear */
      txt_params->x_offset = obj_meta->rect_params.left;
      txt_params->y_offset = obj_meta->rect_params.top - 25;

      /* Font , font-color and font-size */
      txt_params->font_params.font_name = "Serif";
      txt_params->font_params.font_size = 10;
      txt_params->font_params.font_color.red = 1.0;
      txt_params->font_params.font_color.green = 1.0;
      txt_params->font_params.font_color.blue = 1.0;
      txt_params->font_params.font_color.alpha = 1.0;

      /* Text background color */
      txt_params->set_bg_clr = 1;
      txt_params->text_bg_clr.red = 0.0;
      txt_params->text_bg_clr.green = 0.0;
      txt_params->text_bg_clr.blue = 0.0;
      txt_params->text_bg_clr.alpha = 1.0;

      /*
       * Ideally NVDS_EVENT_MSG_META should be attached to buffer by the
       * component implementing detection / recognition logic.
       * Here it demonstrates how to use / attach that meta data.
       */
      if (is_first_object && !(frame_number % frame_interval)) {
        /* Frequency of messages to be send will be based on use case.
         * Here message is being sent for first object every frame_interval(default=30).
         */

        NvDsEventMsgMeta *msg_meta =
            (NvDsEventMsgMeta *) g_malloc0 (sizeof (NvDsEventMsgMeta));
        msg_meta->bbox.top = obj_meta->rect_params.top;
        msg_meta->bbox.left = obj_meta->rect_params.left;
        msg_meta->bbox.width = obj_meta->rect_params.width;
        msg_meta->bbox.height = obj_meta->rect_params.height;
        msg_meta->frameId = frame_number;
        msg_meta->trackingId = obj_meta->object_id;
        msg_meta->confidence = obj_meta->confidence;
        generate_event_msg_meta (msg_meta, obj_meta->class_id, obj_meta);

        // 要增加自訂的meta data必須要先用            nvds_acquire_user_meta_from_pool (batch_meta);取得
        // https://docs.nvidia.com/metropolis/deepstream/dev-guide/text/DS_plugin_metadata.html#user-custom-metadata-addition-inside-nvdsbatchmeta

        NvDsUserMeta *user_event_meta =
            nvds_acquire_user_meta_from_pool (batch_meta);
        if (user_event_meta) {
          user_event_meta->user_meta_data = (void *) msg_meta;
          user_event_meta->base_meta.meta_type = NVDS_EVENT_MSG_META;
          user_event_meta->base_meta.copy_func =
              (NvDsMetaCopyFunc) meta_copy_func;
          user_event_meta->base_meta.release_func =
              (NvDsMetaReleaseFunc) meta_free_func;
          nvds_add_user_meta_to_frame (frame_meta, user_event_meta);
        } else {
          g_print ("Error in attaching event meta to buffer\n");
        }
        is_first_object = FALSE;
      }
    }
  }
  g_print ("Frame Number = %d "
      "Vehicle Count = %d Person Count = %d\n",
      frame_number, vehicle_count, person_count);
  frame_number++;

  return GST_PAD_PROBE_OK;
}

NvDsObjEncUsrArgs參數的功用

• bool isFrame : 告訴encoder要編碼整張照片還是編碼每一個偵測物件的截圖。
  • 1: Encodes the entire frame.
  • 0: Encodes object of specified resolution.
• bool saveImg : 會直接儲存一張照片到當前資料夾
• bool attachUsrMeta :
  • 決定是否加上NVDS_CROP_IMAGE_META metadata

Deepstream截圖，以deepstream_image_meta_test為例

注意:

根據文件nvds_obj_enc_process是一個非阻塞的函式，使用者必須呼叫nvds_obj_enc_finish()以確保所有的圖片都已經確實被處理完成。

第一步，設定要儲存照片的條件並且encode成jpg檔

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

/* pgie_src_pad_buffer_probe will extract metadata received on pgie src pad
 * and update params for drawing rectangle, object information etc. We also
 * iterate through the object list and encode the cropped objects as jpeg
 * images and attach it as user meta to the respective objects.*/
static GstPadProbeReturn
pgie_src_pad_buffer_probe (GstPad * pad, GstPadProbeInfo * info, gpointer ctx)
{
  GstBuffer *buf = (GstBuffer *) info->data;
  GstMapInfo inmap = GST_MAP_INFO_INIT;
  if (!gst_buffer_map (buf, &inmap, GST_MAP_READ)) {
    GST_ERROR ("input buffer mapinfo failed");
    return GST_PAD_PROBE_DROP;
  }
  NvBufSurface *ip_surf = (NvBufSurface *) inmap.data;
  gst_buffer_unmap (buf, &inmap);

  NvDsObjectMeta *obj_meta = NULL;
  guint vehicle_count = 0;
  guint person_count = 0;
  NvDsMetaList *l_frame = NULL;
  NvDsMetaList *l_obj = NULL;
  NvDsBatchMeta *batch_meta = gst_buffer_get_nvds_batch_meta (buf);
  for (l_frame = batch_meta->frame_meta_list; l_frame != NULL;
      l_frame = l_frame->next) {
    NvDsFrameMeta *frame_meta = (NvDsFrameMeta *) (l_frame->data);
    /* For demonstration purposes, we will encode the first 10 frames. */
    if(frame_count <= 10) {
      NvDsObjEncUsrArgs frameData = { 0 };
      /* Preset */
      frameData.isFrame = 1;
      /* To be set by user */
      frameData.saveImg = save_img;
      frameData.attachUsrMeta = attach_user_meta;
      /* Set if Image scaling Required */
      frameData.scaleImg = FALSE;
      frameData.scaledWidth = 0;
      frameData.scaledHeight = 0;
      /* Quality */
      frameData.quality = 80;
      /* Main Function Call */
      nvds_obj_enc_process (ctx, &frameData, ip_surf, NULL, frame_meta);
    }
    guint num_rects = 0;
    for (l_obj = frame_meta->obj_meta_list; l_obj != NULL; l_obj = l_obj->next) {
      obj_meta = (NvDsObjectMeta *) (l_obj->data);
      if (obj_meta->class_id == PGIE_CLASS_ID_VEHICLE) {
        vehicle_count++;
        num_rects++;
      }
      if (obj_meta->class_id == PGIE_CLASS_ID_PERSON) {
        person_count++;
        num_rects++;
      }
      /* Conditions that user needs to set to encode the detected objects of
       * interest. Here, by default all the detected objects are encoded.
       * For demonstration, we will encode the first object in the frame. */
      if ((obj_meta->class_id == PGIE_CLASS_ID_PERSON
              || obj_meta->class_id == PGIE_CLASS_ID_VEHICLE)
          && num_rects == 1) {
        NvDsObjEncUsrArgs objData = { 0 };
        /* To be set by user */
        objData.saveImg = save_img;
        objData.attachUsrMeta = attach_user_meta;
        /* Set if Image scaling Required */
        objData.scaleImg = FALSE;
        objData.scaledWidth = 0;
        objData.scaledHeight = 0;
        /* Preset */
        objData.objNum = num_rects;
        /* Quality */
        objData.quality = 80;
        /*Main Function Call */
        nvds_obj_enc_process (ctx, &objData, ip_surf, obj_meta, frame_meta);
      }
    }
  }
  nvds_obj_enc_finish (ctx);
  frame_count++;
  return GST_PAD_PROBE_OK;
}

第二步，檢查usrMetaData是否的meta_type是不是NVDS_CROP_IMAGE_META

如果發現是NVDS_CROP_IMAGE_META，就儲存照片

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

/* osd_sink_pad_buffer_probe will extract metadata received on OSD sink pad
 * and update params for drawing rectangle, object information. We also iterate
 * through the user meta of type "NVDS_CROP_IMAGE_META" to find image crop meta
 * and demonstrate how to access it.*/
static GstPadProbeReturn
osd_sink_pad_buffer_probe (GstPad * pad, GstPadProbeInfo * info,
    gpointer u_data)
{
  GstBuffer *buf = (GstBuffer *) info->data;

  guint num_rects = 0;
  NvDsObjectMeta *obj_meta = NULL;
  guint vehicle_count = 0;
  guint person_count = 0;
  NvDsMetaList *l_frame = NULL;
  NvDsMetaList *l_obj = NULL;
  NvDsDisplayMeta *display_meta = NULL;
  NvDsBatchMeta *batch_meta = gst_buffer_get_nvds_batch_meta (buf);
  g_print ("Running osd_sink_pad_buffer_probe...\n");
  for (l_frame = batch_meta->frame_meta_list; l_frame != NULL;
      l_frame = l_frame->next) {
    NvDsFrameMeta *frame_meta = (NvDsFrameMeta *) (l_frame->data);
    int offset = 0;
    /* To verify  encoded metadata of cropped frames, we iterate through the
    * user metadata of each frame and if a metadata of the type
    * 'NVDS_CROP_IMAGE_META' is found then we write that to a file as
    * implemented below.
    */
    char fileFrameNameString[FILE_NAME_SIZE];
    const char *osd_string = "OSD";

    /* For Demonstration Purposes we are writing metadata to jpeg images of
      * the first 10 frames only.
      * The files generated have an 'OSD' prefix. */
    if (frame_number < 11) {
      NvDsUserMetaList *usrMetaList = frame_meta->frame_user_meta_list;
      FILE *file;
      int stream_num = 0;
      while (usrMetaList != NULL) {
        NvDsUserMeta *usrMetaData = (NvDsUserMeta *) usrMetaList->data;
        if (usrMetaData->base_meta.meta_type == NVDS_CROP_IMAGE_META) {
          snprintf (fileFrameNameString, FILE_NAME_SIZE, "%s_frame_%d_%d.jpg",
              osd_string, frame_number, stream_num++);
          NvDsObjEncOutParams *enc_jpeg_image =
              (NvDsObjEncOutParams *) usrMetaData->user_meta_data;
          /* Write to File */
          file = fopen (fileFrameNameString, "wb");
          fwrite (enc_jpeg_image->outBuffer, sizeof (uint8_t),
              enc_jpeg_image->outLen, file);
          fclose (file);
        }
        usrMetaList = usrMetaList->next;
      }
    }
    for (l_obj = frame_meta->obj_meta_list; l_obj != NULL; l_obj = l_obj->next) {
      obj_meta = (NvDsObjectMeta *) (l_obj->data);
      if (obj_meta->class_id == PGIE_CLASS_ID_VEHICLE) {
        vehicle_count++;
        num_rects++;
      }
      if (obj_meta->class_id == PGIE_CLASS_ID_PERSON) {
        person_count++;
        num_rects++;
      }
      /* To verify  encoded metadata of cropped objects, we iterate through the
       * user metadata of each object and if a metadata of the type
       * 'NVDS_CROP_IMAGE_META' is found then we write that to a file as
       * implemented below.
       */
      char fileObjNameString[FILE_NAME_SIZE];

      /* For Demonstration Purposes we are writing metadata to jpeg images of
       * vehicles or persons for the first 100 frames only.
       * The files generated have a 'OSD' prefix. */
      if (frame_number < 100 && (obj_meta->class_id == PGIE_CLASS_ID_PERSON
              || obj_meta->class_id == PGIE_CLASS_ID_VEHICLE)) {
        NvDsUserMetaList *usrMetaList = obj_meta->obj_user_meta_list;
        FILE *file;
        while (usrMetaList != NULL) {
          NvDsUserMeta *usrMetaData = (NvDsUserMeta *) usrMetaList->data;
          if (usrMetaData->base_meta.meta_type == NVDS_CROP_IMAGE_META) {
            NvDsObjEncOutParams *enc_jpeg_image =
                (NvDsObjEncOutParams *) usrMetaData->user_meta_data;

            snprintf (fileObjNameString, FILE_NAME_SIZE, "%s_%d_%d_%d_%s.jpg",
                osd_string, frame_number, frame_meta->batch_id, num_rects,
                obj_meta->obj_label);
            /* Write to File */
            file = fopen (fileObjNameString, "wb");
            fwrite (enc_jpeg_image->outBuffer, sizeof (uint8_t),
                enc_jpeg_image->outLen, file);
            fclose (file);
            usrMetaList = NULL;
          } else {
            usrMetaList = usrMetaList->next;
          }
        }
      }
    }
    display_meta = nvds_acquire_display_meta_from_pool (batch_meta);
    NvOSD_TextParams *txt_params = &display_meta->text_params[0];
    txt_params->display_text = g_malloc0 (MAX_DISPLAY_LEN);
    offset =
        snprintf (txt_params->display_text, MAX_DISPLAY_LEN, "Person = %d ",
        person_count);
    offset =
        snprintf (txt_params->display_text + offset, MAX_DISPLAY_LEN,
        "Vehicle = %d ", vehicle_count);

    /* Now set the offsets where the string should appear */
    txt_params->x_offset = 10;
    txt_params->y_offset = 12;

    /* Font , font-color and font-size */
    txt_params->font_params.font_name = "Serif";
    txt_params->font_params.font_size = 10;
    txt_params->font_params.font_color.red = 1.0;
    txt_params->font_params.font_color.green = 1.0;
    txt_params->font_params.font_color.blue = 1.0;
    txt_params->font_params.font_color.alpha = 1.0;

    /* Text background color */
    txt_params->set_bg_clr = 1;
    txt_params->text_bg_clr.red = 0.0;
    txt_params->text_bg_clr.green = 0.0;
    txt_params->text_bg_clr.blue = 0.0;
    txt_params->text_bg_clr.alpha = 1.0;

    nvds_add_display_meta_to_frame (frame_meta, display_meta);
  }
  g_print ("Frame Number = %d Number of objects = %d "
      "Vehicle Count = %d Person Count = %d\n",
      frame_number, num_rects, vehicle_count, person_count);
  frame_number++;
  return GST_PAD_PROBE_OK;
}

加入自己客製的的metadata

參考deepstream-user-metadata-test範例的nvinfer_src_pad_buffer_probe

1. 有四個東西需要使用者自行提供

   1. user_meta_data : pointer to User specific meta data
   2. meta_type : Metadata type that user sets to identify its metadata
   3. copy_func : Metadata copy or transform function to be provided when there is buffer transformation
   4. release_func : Metadata release function to be provided when it is no longer required.

2. 這個範例添加一個亂數到metadata上面，以下是要達成這個目標要準備的函式

   1. user_meta_data

      1 2 3 4 5 6 7 8 9 10 11 12

      void *set_metadata_ptr() { int i = 0; gchar *user_metadata = (gchar*)g_malloc0(USER_ARRAY_SIZE); g_print("\n**************** Setting user metadata array of 16 on nvinfer src pad\n"); for(i = 0; i < USER_ARRAY_SIZE; i++) { user_metadata[i] = rand() % 255; g_print("user_meta_data [%d] = %d\n", i, user_metadata[i]); } return (void *)user_metadata; }

   2. meta_type

記得要在在probe function裡面定義變數

1
2
3

/** set the user metadata type */
#define NVDS_USER_FRAME_META_EXAMPLE (nvds_get_user_meta_type("NVIDIA.NVINFER.USER_META"))
NvDsMetaType user_meta_type = NVDS_USER_FRAME_META_EXAMPLE;

3. copy_func

1
2
3
4
5
6
7
8
9

/* copy function set by user. "data" holds a pointer to NvDsUserMeta*/
static gpointer copy_user_meta(gpointer data, gpointer user_data)
{
  NvDsUserMeta *user_meta = (NvDsUserMeta *)data;
  gchar *src_user_metadata = (gchar*)user_meta->user_meta_data;
  gchar *dst_user_metadata = (gchar*)g_malloc0(USER_ARRAY_SIZE);
  memcpy(dst_user_metadata, src_user_metadata, USER_ARRAY_SIZE);
  return (gpointer)dst_user_metadata;
}

4. release_func

1
2
3
4
5
6
7
8
9
10

/* release function set by user. "data" holds a pointer to NvDsUserMeta*/
static void release_user_meta(gpointer data, gpointer user_data)
{
  NvDsUserMeta *user_meta = (NvDsUserMeta *) data;
  if(user_meta->user_meta_data) {
    g_free(user_meta->user_meta_data);
    user_meta->user_meta_data = NULL;
  }
}

3. 新增一個probe把資料放入metadata

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43

   /* Set nvds user metadata at frame level. User need to set 4 parameters after * acquring user meta from pool using nvds_acquire_user_meta_from_pool(). * * Below parameters are required to be set. * 1. user_meta_data : pointer to User specific meta data * 2. meta_type: Metadata type that user sets to identify its metadata * 3. copy_func: Metadata copy or transform function to be provided when there * is buffer transformation * 4. release_func: Metadata release function to be provided when it is no * longer required. * * osd_sink_pad_buffer_probe will extract metadata received on OSD sink pad * and update params for drawing rectangle, object information etc. */ static GstPadProbeReturn nvinfer_src_pad_buffer_probe (GstPad * pad, GstPadProbeInfo * info, gpointer u_data) { GstBuffer *buf = (GstBuffer *) info->data; NvDsMetaList * l_frame = NULL; NvDsUserMeta *user_meta = NULL; NvDsMetaType user_meta_type = NVDS_USER_FRAME_META_EXAMPLE; NvDsBatchMeta *batch_meta = gst_buffer_get_nvds_batch_meta (buf); for (l_frame = batch_meta->frame_meta_list; l_frame != NULL; l_frame = l_frame->next) { NvDsFrameMeta *frame_meta = (NvDsFrameMeta *) (l_frame->data); /* Acquire NvDsUserMeta user meta from pool */ user_meta = nvds_acquire_user_meta_from_pool(batch_meta); /* Set NvDsUserMeta below */ user_meta->user_meta_data = (void *)set_metadata_ptr(); user_meta->base_meta.meta_type = user_meta_type; user_meta->base_meta.copy_func = (NvDsMetaCopyFunc)copy_user_meta; user_meta->base_meta.release_func = (NvDsMetaReleaseFunc)release_user_meta; /* We want to add NvDsUserMeta to frame level */ nvds_add_user_meta_to_frame(frame_meta, user_meta); } return GST_PAD_PROBE_OK; }

將客製化訊息傳換json以之後發送訊息

nvmsgconv的功能:
利用NVDS_EVENT_MSG_METAmetadata來產生JSON格式的”DeepStream Schema” payload。
所產生的payload會以NVDS_META_PAYLOAD的型態儲存到buffer。
除了NvDsEventMsgMeta定義的常用訊號結構，使用者還可以自訂客製化物件並加到NVDS_EVENT_MSG_METAmetadata。要加入自定義訊息NvDsEventMsgMeta提供”extMsg”和”extMsgSize”欄位。使用者可以把自定義的structure指針assign給”extMsg”，並且在”extMsgSize”指令資料大小。

以deepstream-test4為例，在這裡message放入了客製化訊息NvDsVehicleObject和NvDsPersonObject，如果想要客製化自己的訊息就必須要自己定義。

自製自己的客製化訊息
可以參考
/opt/nvidia/deepstream/deepstream-6.2/sources/libs/nvmsgconv/deepstream_schema/eventmsg_payload.cpp參考客製化訊息如何定義轉換成json

nvmsgconv的原始碼
/opt/nvidia/deepstream/deepstream-6.2/sources/gst-plugins/gst-nvmsgconv
/opt/nvidia/deepstream/deepstream-6.2/sources/libs/nvmsgconv

• nvmsgconv開啟除錯功能
  debug-payload-dir : Absolute path of the directory to dump payloads for debugging

1. 以deepstream-test4為例，首先將模型的偵測結果NvDsObjectMeta轉換成NvDsEventMsgMeta，在這步將訊息struct加到extMsg上
2. 將製作好的NvDsEventMsgMeta加進buffer裡面，metadata為NvDsUserMeta，在這一步也要指定meta_copy_func、meta_free_func

mvmsgbroker使用方法

以下將以rabbitmq為範例

1. 安裝rabbitmq client
   說明文件在/opt/nvidia/deepstream/deepstream/sources/libs/amqp_protocol_adaptor的readme.md

   1 2 3 4 5 6 7

   git clone -b v0.8.0 --recursive https://github.com/alanxz/rabbitmq-c.git cd rabbitmq-c mkdir build && cd build cmake .. cmake --build . sudo cp librabbitmq/librabbitmq.so.4 /opt/nvidia/deepstream/deepstream/lib/ sudo ldconfig

2. 安裝rabbitmq server

1
2
3
4
5
6
7
8
9
10

#Install rabbitmq on your ubuntu system: https://www.rabbitmq.com/install-debian.html
#The “Using rabbitmq.com APT Repository” procedure is known to work well

 sudo apt-get install rabbitmq-server

#Ensure rabbitmq service has started by running (should be the case):
 sudo service rabbitmq-server status

#Otherwise
 sudo service rabbitmq-server start

3. 設定連線詳細資訊
4. 建立cfg_amqp.txt連線資訊檔(/opt/nvidia/deepstream/deepstream/sources/libs/amqp_protocol_adaptor 有範例)，並且傳給nvmsgbroker。內容範例如下

1
2
3
4
5
6
7
8
9

[message-broker]
hostname = localhost
port = 5672
username = guest
password = guest
exchange = amq.topic
topic = topicname
amqp-framesize = 131072
#share-connection = 1

• exchange: 預設的exchange是amq.topic，可以更改成其他的
• Topic : 設定要發送的topic名稱
• share-connection : Uncommenting this field signifies that the connection created can be shared with other components within the same process.

1. 直接將連線資訊傳給msgapi_connect_ptr

1

conn_handle = msgapi_connect_ptr((char *)"url;port;username;password",(nvds_msgapi_connect_cb_t) sample_msgapi_connect_cb, (char *)CFG_FILE);

4. 測試用程式
   在/opt/nvidia/deepstream/deepstream/sources/libs/amqp_protocol_adaptor有測試用的程式test_amqp_proto_async.c和test_amqp_proto_sync.c，可以用來測試連線是否成功，編譯方式如下

   1 2 3

   make -f Makefile.test ./test_amqp_proto_async ./test_amqp_proto_sync

   注意:

• 你可能須要root權限才能在這個資料夾編譯程式
• libnvds_amqp_proto.so 位於 /opt/nvidia/deepstream/deepstream-/lib/

5. 測試和驗證發送出去的訊息
   • 建立exchange , queue，並且將他們綁定在一起

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# Rabbitmq management:
It comes with a command line tool which you can use to create/configure all of your queues/exchanges/etc
https://www.rabbitmq.com/management.html

# Install rabbitmq management plugin:
sudo rabbitmq-plugins enable rabbitmq_management

# Use the default exchange amq.topic
OR create an exchange as below, the same name as the one you specify within the cfg_amqp.txt
#sudo rabbitmqadmin -u guest -p guest -V / declare exchange name=myexchange type=topic

# Create a Queue
sudo rabbitmqadmin -u guest -p guest -V / declare queue name=myqueue durable=false auto_delete=true

#Bind Queue to exchange with routhing_key specification
rabbitmqadmin -u guest -p guest -V / declare binding source=amq.topic destination=myqueue routing_key=topicname

#To check if the queues were actually created, execute:
$ sudo rabbitmqctl list_queues
Listing queues
myqueue      0

* 接收訊息

1
2
3
4
5
6
7
8
9
10

#Install the amqp-tools
sudo apt-get install amqp-tools

cat <<EOF > test_amqp_recv.sh
while read -r line; do
    echo "\$line"
done
EOF

chmod +x test_amqp_recv.sh

* 執行consumer

1

amqp-consume  -q "myqueue" -r "topicname" -e "amq.topic" ./test_amqp_recv.sh

混用c 和 c++ 程式

https://hackmd.io/@rhythm/HyOxzDkmD
https://embeddedartistry.com/blog/2017/05/01/mixing-c-and-c-extern-c/

async property

某些狀況下async property 設為true會讓pipeline卡住，還需要進一步了解原因

nvmsgconv 詳細payload設定

在/opt/nvidia/deepstream/deepstream/sources/libs/nvmsgconv/nvmsgconv.cpp裡面可以看到nvds_msg2p_ctx_create這個函式，是用來產出payload的函式。在nvmsgconv讀取的yaml檔裡面可以設定的group和屬性如下

sensor

• enable : 是否啟用這個sensor
• id : 對應NvDsEventMsgMeta的sensorId
• type :
• description
• location
  • lat;lon;alt的格式
• coordinate
  • x;y;z的格式

place

analytics

NvDsEventMsgMeta 轉換成json的詳細實作

在/opt/nvidia/deepstream/deepstream-6.2/sources/libs/nvmsgconv/deepstream_schema/eventmsg_payload.cpp這個程式裡，分別有sensor, place, analytics的轉換實作

客製化nvmsgconv payload

如果要客製化payload的話，可以參考/opt/nvidia/deepstream/deepstream-6.2/sources/libs/nvmsgconv/deepstream_schema/eventmsg_payload.cpp裡面的實作，並且加入自己需要的客製化payload。首先將整個/opt/nvidia/deepstream/deepstream-6.2/sources/libs/nvmsgconv複製到其他資料夾並且準備編譯環境

編譯環境

這裡介紹在Ubuntu20.04的桌上型主機上環境的配置方法，Jetson的環境配置方法可能略有不同。

• 下載並且編譯protobuf
  在Ubuntu20.04下使用apt-get install protobuf 只會安裝到protobuf 3.6的版本，而許多標頭檔要到3.7以上才有，而且不能超過3.19，以免某些標頭檔又遺失。如果中間有步驟做錯，只要還沒make install，建議直接刪除protobuf的資料夾，重新下載並且編譯。

首先直接從github下載protobuf原始碼

1

git clone https://github.com/protocolbuffers/protobuf.git

切換版本到v3.19.6，並且更新submodule。

1
2
3

cd protobuf
git submodule update --init --recursive
./autogen.sh

編譯並且安裝，make check過程中如果有錯誤，編譯出來的程式可能會有部分功能遺失。

1
2
3
4
5

./configure
make
make check
sudo make install
sudo ldconfig # refresh shared library cache.

編譯客製化的nvmsgconv

接下來進到nvmsgconv的資料夾，修改一下最後產出的lib檔案名稱和install的位置，然後用make指令編譯

預訓練模型

/opt/nvidia/deepstream/deepstream-6.2/samples/models/tao_pretrained_mod
els/trafficcamnet

usb相機

https://docs.nvidia.com/jetson/archives/r35.4.1/DeveloperGuide/text/SD/CameraDevelopment/CameraSoftwareDevelopmentSolution.html#applications-using-gstreamer-with-the-nvarguscamerasrc-plugin

儲存影像

https://forums.developer.nvidia.com/t/drawn-rectangle-is-not-available-on-encoded-frame/178022/7?u=jenhao

元件速度測量

https://forums.developer.nvidia.com/t/deepstream-sdk-faq/80236/12?u=jenhao

參考:
https://www.gclue.jp/2022/06/gstreamer.html

在現在常見的SSD作業系統碟加上HDD資料碟的配置，下面接介紹如何手動將/home移動到HDD資料碟

格式化硬碟(完全新的硬碟才需要)，這裡假設整顆硬碟不再分割磁碟

1
2

lsblk #找出硬碟的名稱
sudo mkfs -t ext4 /dev/sdb #格式化整顆硬碟

將資料碟mount在一個暫時的資料夾下面

1
2

sudo mkdir /mnt/tmp
sudo mount /dev/sdb1 /mnt/tmp

複製原本/home裡面的資料

1

sudo rsync -avx /home/ /mnt/tmp

建立/home的永久mount點

• 先用以下指令查詢資料碟的UUID

  1	sudo blkid

• 用sudo nano /etc/fstab # or any other editor將下面一行寫入/etc/fstab文件最後面來設定mount點

1

UUID=<noted number from above>    /home    ext4    defaults   0  2

重開機檢查是否生效

(危險區)刪除舊的/home

以下指令會刪掉舊的/home。務必先unmount新的home以免刪錯

1
2

sudo umount /home    # unmount the new home first!
sudo rm -rf /home/*  # deletes the old home

掛載另一顆硬碟

將/home掛載到另一顆硬碟

參考:
https://askubuntu.com/a/50539

https://www.tecmint.com/convert-home-directory-partition-linux/

https://help.ubuntu.com/community/DiskSpace

GObject 和 GLib

GStreamer建立在GObject和GLib之上，熟悉GObject和GLib對於學習GStreamer會有幫助，要區分目前的函示是屬於GStreamer還是GLib的方法就是GStreamer的函式是gst_開頭，而GLib的函式是g_開頭

1.簡單範例

範例

下面程式碼是一個最基礎的GStreamer範例basic-tutorial-1.c

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

#include <gst/gst.h>

#ifdef __APPLE__
#include <TargetConditionals.h>
#endif

int
tutorial_main (int argc, char *argv[])
{
  GstElement *pipeline;
  GstBus *bus;
  GstMessage *msg;

  /* Initialize GStreamer */
  gst_init (&argc, &argv);

  /* Build the pipeline */
  pipeline =
      gst_parse_launch
      ("playbin uri=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm",
      NULL);

  /* Start playing */
  gst_element_set_state (pipeline, GST_STATE_PLAYING);

  /* Wait until error or EOS */
  bus = gst_element_get_bus (pipeline);
  msg =
      gst_bus_timed_pop_filtered (bus, GST_CLOCK_TIME_NONE,
      GST_MESSAGE_ERROR | GST_MESSAGE_EOS);

  /* See next tutorial for proper error message handling/parsing */
  if (GST_MESSAGE_TYPE (msg) == GST_MESSAGE_ERROR) {
    g_error ("An error occurred! Re-run with the GST_DEBUG=*:WARN environment "
        "variable set for more details.");
  }

  /* Free resources */
  gst_message_unref (msg);
  gst_object_unref (bus);
  gst_element_set_state (pipeline, GST_STATE_NULL);
  gst_object_unref (pipeline);
  return 0;
}

int
main (int argc, char *argv[])
{
#if defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE
  return gst_macos_main (tutorial_main, argc, argv, NULL);
#else
  return tutorial_main (argc, argv);
#endif
}

{:file=’basic-tutorial-1.c’}

在Linux下可以用以下指令編譯。

1

gcc basic-tutorial-1.c -o basic-tutorial-1 `pkg-config --cflags --libs gstreamer-1.0`

解說

上面這個範例最重要的只有五個需要注意的地方，其他的程式碼都是程式結束後清理的例行動作。

1. 首先所有的Gstreamer都必須呼叫gst_init()，他有三個功能

• 初始化GStreamer
• 確認plug-ins都可以使用
• 執行命令列的參數選項，可以直接將main函式的argc和argv直接傳入gst_init()

  1 2 3 4

  /* Initialize GStreamer */ gst_init (&argc, &argv); /* Build the pipeline */

2. gst_parse_launch
   GStreamer 元件像水管一樣接起來組成像水管的pipeline，影音資料像像水流一樣，source元件是pipeline的起頭，像水龍頭一樣流出影音資料。sink元件是pipeline的結尾，是影音資料最後到達的地方。過程中經過中間的處理原件可以對影音資料進行處理。

通常你會需要用程式定義每個元件和串接方式，但是如果你的pipeline很簡單，你可以直接用文字描述的方式作為參數傳給gst_parse_launch來建立pipeline

3. playbin
   在這個範例中我們用到playbin來建立pipeline，playbin是一個特殊的元件，他可以同時做為source和sink，而且他可以自己建立成一個pipeline。在這個範例我們給他一個影片串流的URL，如果URL有錯或是指定的影片檔不存在，playbin可以回傳錯誤，在這個範例我們遇到錯誤的時候是直接離開程式。

   1 2 3

   gst_parse_launch ("playbin uri=https://www.freedesktop.org/software/gstreamer-sdk/data/media/sintel_trailer-480p.webm", NULL);

4. state
   GStreamer 還有一個重要的觀念state。每一個GStreamer element都有state，很像影音撥放器的播放和暫停按鈕。在這個範例裡面，pipeline是我們唯一的element，因此要把他設為撥放才會開始撥放影片。

   1 2	/* Start playing */ gst_element_set_state (pipeline, GST_STATE_PLAYING);

5. message bus、gst_element_get_bus、gst_bus_timed_pop_filtered
   在下面這兩行，gst_element_get_bus會取得pipeline的bus，而gst_bus_timed_pop_filtered會把main thread停住直到我們感興趣的訊息，在這裡是GST_MESSAGE_ERROR和GST_MESSAGE_EOS，而GST_MESSAGE_EOS代表影片結束了，因此當影片結束的時候整個程式就會停止。

1
2
3
4
5

/* Wait until error or EOS */
bus = gst_element_get_bus (pipeline);
msg =
    gst_bus_timed_pop_filtered (bus, GST_CLOCK_TIME_NONE,
    GST_MESSAGE_ERROR | GST_MESSAGE_EOS);

2. GStreamer 觀念

這個教學將會示範用程式建立pipeline。在這裡將會學到

• 介紹GStreamer element並且學習如何建立
• 串接element
• 客製化element行為
• 利用message bus監看錯誤是件並且從中取出錯誤訊息

用程式寫出前一個教學的撥放器

完整程式碼basic-tutorial-2.c

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96

#include <gst/gst.h>

#ifdef __APPLE__
#include <TargetConditionals.h>
#endif

int
tutorial_main (int argc, char *argv[])
{
  GstElement *pipeline, *source, *sink;
  GstBus *bus;
  GstMessage *msg;
  GstStateChangeReturn ret;

  /* Initialize GStreamer */
  gst_init (&argc, &argv);

  /* Create the elements */
  source = gst_element_factory_make ("videotestsrc", "source");
  sink = gst_element_factory_make ("autovideosink", "sink");

  /* Create the empty pipeline */
  pipeline = gst_pipeline_new ("test-pipeline");

  if (!pipeline || !source || !sink) {
    g_printerr ("Not all elements could be created.\n");
    return -1;
  }

  /* Build the pipeline */
  gst_bin_add_many (GST_BIN (pipeline), source, sink, NULL);
  if (gst_element_link (source, sink) != TRUE) {
    g_printerr ("Elements could not be linked.\n");
    gst_object_unref (pipeline);
    return -1;
  }

  /* Modify the source's properties */
  g_object_set (source, "pattern", 0, NULL);

  /* Start playing */
  ret = gst_element_set_state (pipeline, GST_STATE_PLAYING);
  if (ret == GST_STATE_CHANGE_FAILURE) {
    g_printerr ("Unable to set the pipeline to the playing state.\n");
    gst_object_unref (pipeline);
    return -1;
  }

  /* Wait until error or EOS */
  bus = gst_element_get_bus (pipeline);
  msg =
      gst_bus_timed_pop_filtered (bus, GST_CLOCK_TIME_NONE,
      GST_MESSAGE_ERROR | GST_MESSAGE_EOS);

  /* Parse message */
  if (msg != NULL) {
    GError *err;
    gchar *debug_info;

    switch (GST_MESSAGE_TYPE (msg)) {
      case GST_MESSAGE_ERROR:
        gst_message_parse_error (msg, &err, &debug_info);
        g_printerr ("Error received from element %s: %s\n",
            GST_OBJECT_NAME (msg->src), err->message);
        g_printerr ("Debugging information: %s\n",
            debug_info ? debug_info : "none");
        g_clear_error (&err);
        g_free (debug_info);
        break;
      case GST_MESSAGE_EOS:
        g_print ("End-Of-Stream reached.\n");
        break;
      default:
        /* We should not reach here because we only asked for ERRORs and EOS */
        g_printerr ("Unexpected message received.\n");
        break;
    }
    gst_message_unref (msg);
  }

  /* Free resources */
  gst_object_unref (bus);
  gst_element_set_state (pipeline, GST_STATE_NULL);
  gst_object_unref (pipeline);
  return 0;
}

int
main (int argc, char *argv[])
{
#if defined(__APPLE__) && TARGET_OS_MAC && !TARGET_OS_IPHONE
  return gst_macos_main (tutorial_main, argc, argv, NULL);
#else
  return tutorial_main (argc, argv);
#endif
}

{:file=’basic-tutorial-2.c’}

GStreamer element

element是GStreamer最根本的元素，影音資料從source流向sink，過程中經過filter對影音資料進行處理，這三個元素組成為pipeline

建立element

1
2
3

/* Create the elements */
source = gst_element_factory_make ("videotestsrc", "source");
sink = gst_element_factory_make ("autovideosink", "sink");

建立element可以用gst_element_factory_make()來建立，第一個參數是要建立的element名稱，第二個參數是我們給element取的名字。幫element命名的好處是如果你沒有儲存pointer，你可以用名稱來找到這個element，而且除錯訊息也會變得比較有意義。

這個教學中建立兩個element，videotestsrc和autovideosink，然後沒有建立任何filter。所以pipeline長的像下圖。

videotestsrc是一個source element，他會產生除錯用的影像。

autovideosink是一個sink element，他會將影像顯示到螢幕上。

建立pipeline

1
2
3
4
5
6
7

/* Create the empty pipeline */
pipeline = gst_pipeline_new ("test-pipeline");

if (!pipeline || !source || !sink) {
  g_printerr ("Not all elements could be created.\n");
  return -1;
}

所有的element都必須在pipeline裡面才能運作，利用gst_pipeline_new()，可以建立新的pipeline。

bin

1
2
3
4
5
6
7

/* Build the pipeline */
 gst_bin_add_many (GST_BIN (pipeline), source, sink, NULL);
 if (gst_element_link (source, sink) != TRUE) {
   g_printerr ("Elements could not be linked.\n");
   gst_object_unref (pipeline);
   return -1;
 }

Gstreamer的bin是也是一個element，它可以拿來成裝其他 GstElement。GstBin的類別關係圖如下

1
2
3
4
5

GObject
    ╰──GInitiallyUnowned
        ╰──GstObject
            ╰──GstElement
                ╰──GstBin

pipeline也是bin，用來裝入element。

利用gst_bin_add_many()可以將element放入pipeline，他可以一次加入許多element。他的第一個參數是bin，第二個參數之後都是element，也就是要放入的element

連接element

到目前為止element並還沒有連接起來，利用gst_element_link()將element聯接起來。他的第一個參數是來源，第二個參數是目標，也就是第一個參數的element會把資料傳給第二個參數的element，所以是有順序性的。

注意，只有位於同一個bin的element可以互相聯接。

屬性

GStreamer 的element全部都是一種特殊的GObject，因此他們都有property，有些可以讀取有些可以寫入

property必須透過GLib的方法g_object_get()和g_object_set()來讀取和寫入，因此注意到這輛個函式是g_開頭。

g_object_set()支援一次修改多個properties。

回到我們的程式，我們改變videotestsrc的”pattern” properties，你可以將它改成其他類型來看看輸出的畫面有什麼改變。

1
2

/* Modify the source's properties */
g_object_set (source, "pattern", 0, NULL);

錯誤檢查

到目前為止pipeline都已經建立完成，接下來我們要增加一些程式來應付錯誤發生的情況。

1
2
3
4
5
6
7

/* Start playing */
ret = gst_element_set_state (pipeline, GST_STATE_PLAYING);
if (ret == GST_STATE_CHANGE_FAILURE) {
  g_printerr ("Unable to set the pipeline to the playing state.\n");
  gst_object_unref (pipeline);
  return -1;
}

這是我們一樣呼叫gst_element_set_state來開始撥放，但是我們另外檢查gst_element_set_state回傳的錯誤。

另外，我們還多了一些程式來處理gst_bus_timed_pop_filtered()拿到的錯誤訊息，錯誤訊息是一個GstMessage，如果遇到EOS以外的錯誤訊息，就把他印出來。

GstMessage十分方便，幾乎可以承載任何形式的訊息，而GSstreamer提供了許多解析訊息的函式。

首先我們先利用GST_MESSAGE_TYPE()來取得錯誤的類型，如果不是EOS錯誤，就再用gst_message_parse_error()把錯誤轉型成GLib的GError以及錯誤訊息的文字。注意使用完之後要記得釋放。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

/* Parse message */
if (msg != NULL) {
  GError *err;
  gchar *debug_info;

  switch (GST_MESSAGE_TYPE (msg)) {
    case GST_MESSAGE_ERROR:
      gst_message_parse_error (msg, &err, &debug_info);
      g_printerr ("Error received from element %s: %s\n",
          GST_OBJECT_NAME (msg->src), err->message);
      g_printerr ("Debugging information: %s\n",
          debug_info ? debug_info : "none");
      g_clear_error (&err);
      g_free (debug_info);
      break;
    case GST_MESSAGE_EOS:
      g_print ("End-Of-Stream reached.\n");
      break;
    default:
      /* We should not reach here because we only asked for ERRORs and EOS */
      g_printerr ("Unexpected message received.\n");
      break;
  }
  gst_message_unref (msg);
}

GStreamer bus

GStreamer bus是用來將元素所產生的GstMessage按順序傳送給應用程式的thread。這裡要強調的是，消息是從處理影像的thread傳遞給應用程式的thread。

訊息可以用gst_bus_timed_pop_filtered()這個函式來同步取得。或是用signals 來非同步取得，應用設必須隨時注意bus上有沒有出現錯誤。

動態pipeline

在這個範例所建立的pipeline並不是完整的，而這裡將示範如何在程式運行時才將完整的pipeline建立好。

程式將打開一個multiplexed (或是 muxed)的檔案，也就是聲音和影像都儲存在一個檔案(container file)。用來打開這種檔案的element稱為demuxers。常見的container file有mp4、MKV、WMV等等。

如果container file裡面包含多個串流(例如一個影片串流，兩個聲音串流)，demuxer就會把他們分別分配到不同的出口，而不同的pipeline就可以各自處理這些串流。

在GStreamer裡element用來傳遞資料的接口稱為pad(GstPad)，sink pad就是資料流進element的口，以及source pad就是element將資料流出的口。記憶的方式就是source elements只會擁有source pad，而sink element只會擁有sink pad。filter element則同時擁有source pad和sink pad。

在這個範例裡面，demuxer包含一個sink pad 和多個 source pad，而demuxer複雜的地方就在於在讀取檔案之前沒辦法確定demuxer到底有多少個source pad，因為demuxer要讀取到檔案之後才能決定有多少個source pad。