Programová manipulace s STL soubory

Instalace knihovny

Pro použití knihovny ADMesh je třeba nejprve knihovnu nainstalovat.

Pokud používáte Linux, můžete prozkoumat balíčky vaší distribuce, zajímají vás balíček devel nebo dev, abyste dostali hlavičkové soubory a jiné věci potřebné pro kompilaci programů využívajících ADMesh. V distribuci Fedora tedy chcete balíček admesh-devel, v distribuci Debian pak libadmesh-dev. V každém případě potřebujete verzi 0.98.x, starší verze obsahují pouze program pro příkazovou řádku.

Pro macOS můžete využít homebrew.

Pro operační systém Windows pak existují předkompilované archivy dostupné na GitHubu.

Na všech podporovaných systémech můžete knihovnu zkompilovat sami ze zdrojových kódů.

Vlastní sestavení na Linuxu

Po stažení admesh-0.98.5.tar.gz a rozbalení:

$ ./configure
$ make
$ export ADMESHDIR=~/admesh
$ make install DESTDIR=$ADMESHDIR

Pro kompilaci zdrojového kódu do programu je třeba linkeru říct, že chceme použít knihovnu ADMesh, a předat kompilátoru cestu k hlavičkovému souboru a knihovně:

$ export ADMESHDIR=~/admesh
$ gcc -L$ADMESHDIR/usr/local/lib/ -I$ADMESHDIR/usr/local/include/ source.c -o myapp -ladmesh

$ LD_LIBRARY_PATH=$ADMESHDIR/usr/local/lib/ ./myapp

Instalace a kompilace ADMesh na macOS

Pro instalaci využijeme Homebrew. Pokud nemáte nainstalovaný, nainstalujte ho podle návodu na https://brew.sh/

$ brew install admesh

Pro kompilaci zdrojového kódu do programu je třeba linkeru říct, že chceme použít knihovnu ADMesh, a předat kompilátoru cestu k hlavičkovému souboru a knihovně:

$ gcc -L/opt/homebrew/lib/ -I/opt/homebrew/include/ source.c -o myapp -ladmesh

$ ./myapp

Základní použití

Pro použití knihovny stačí naincludovat hlavičkový soubor admesh/stl.h:

#include <admesh/stl.h>

V knihovně existuje sada struktur a funkcí, které můžete využít pro základní manipulaci s STL modely.

Načtení modelu ze souboru

Nejprve je třeba soubor načíst z disku do struktury stl_file.

#include <stdlib.h>
#include <admesh/stl.h>

int main(void) {
  stl_file stl; 1
  char *filename = "directory/model.stl"; 2
  stl_open(&stl, filename); 3
  stl_exit_on_error(&stl); 4

  /* ... TODO ... */

  stl_close(&stl); 5
  return EXIT_SUCCESS;
}

Kompilace programu

Pro kompilaci zdrojového kódu do programu je třeba linkeru říct, že chceme použít knihovnu ADMesh:

$ gcc source.c -o myapp -ladmesh

Případně, pokud nemáte ADMesh nainstalovaný ve standardních cestách, je třeba nastavit absolutní cesty ke knihovně i hlavičkovému souboru:

$ export ADMESHDIR=~/admesh
$ gcc -L$ADMESHDIR/usr/local/lib/ -I$ADMESHDIR/usr/local/include/ source.c -o myapp -ladmesh

$ ./myapp

$ LD_LIBRARY_PATH=$ADMESHDIR/usr/local/lib/ ./myapp

$ DYLD_LIBRARY_PATH=$ADMESHDIR/usr/local/lib/ ./myapp

Práce se strukturou stl_file

Po načtení souboru do paměti je možné se strukturou stl_file nadále jakkoliv pracovat. Například prohlížet nebo měnit data. Struktura již není datově svázána se souborem na disku a všechna data jsou v paměti programu.

Pro prohlížení jednotlivých facetů je možné použít ukazatel (pole) facet_start. V poli jsou uloženy facety ve formě struktur stl_facet, které obsahují normálu – atribut normal (struktura typu stl_normal obsahující 3 floaty (x, y, z)), tři vertexy – atribut vertex (pole tří struktur typu stl_vertex každá obsahující 3 floaty (x, y, z)) a atribut extra, který můžete ignorovat.

float x = stl.facet_start[0].vertex[0].x; 1
float z = stl.facet_start[1000].vertex[1].z; 2

Abyste mohli procházet všechny facety, potřebujte nejprve vědět, kolik jich je. Tyto informace najdete v atributu stats, který obsahuje strukturu se spoustou užitečných dat, většinou čísel. Jedním z nich je number_of_facets, tedy počet facetů.

stl.facet_start[stl.stats.number_of_facets-1] 1

Ve statistikách (stats) najdete další informace, jejichž přehled je v definici struktury stl_stats v souboru stl.h nebo v nepříliš dobré dokumentaci.

Zde je na ukázku krátký program, který načte STL soubor model.stl (binární nebo ASCII) a zapíše jej jako ASCII nebo binární STL do stejného souboru – z binárních dělá ASCII a z ASCII dělá binární.

Data můžete libovolně prohlížet a měnit. Pokud chcete například model zvětšit, teoreticky stačí provést patřičnou matematickou operaci se všemi souřadnicemi všech vertexů všech facetů.

Většinu základních operací ale již autoři programu pokryli.

Funkce pro manipulaci s modelem

Pro „typické“ operace s 3D modelem existují předpřipravené funkce. V knihovně tak naleznete funkce na otáčení, škálování, přesouvání…​

Většinou se stačí podívat na jejich seznam v hlavičkovém souboru.

Mezi ty zajímavé patří:

Funkce pro zapsaní modelu do souboru

Po skončení práce s modelem je často třeba model opět zapsat na disk (vyexportovat).

K zapsání modelu ve formátu STL slouží funkce stl_write_ascii() a stl_write_binary(), které se liší ve výsledném formátu: zapisují ASCII STL, respektive binární STL.

Obě funkce berou tři argumenty:

Jméno meshe nesouvisí z názvem souboru, ale jde pouze o textovou informaci uloženou v STL souboru. Tato informace není v praxi využívána a často se nahrazuje názvem programu, který mesh vytvořil. Například modely z programu OpenSCAD se jmenují vždy OpenSCAD_Model.

/* ... */
stl_write_ascii(&stl, filename, "whatever"); 1
stl_exit_on_error(&stl); 2
/* ... */
stl_close(&stl); 3

Ukázka programu pro převod ASCII/binárního STL

Pro ukázku kompletní program pro převod ASCII STL souboru do binární formy (nebo obráceně).

#include <stdlib.h>
#include <admesh/stl.h>

int main(void) {
  stl_file stl;
  char *filename = "model.stl";

  printf("Opening %s\n", filename);
  stl_open(&stl, filename); 1
  stl_exit_on_error(&stl); 2

  if (stl.stats.type == binary) { 3
    printf("Writing ASCII file %s\n", filename);
    stl_write_ascii(&stl, filename, "converted"); 4
    stl_exit_on_error(&stl); 5
  } else {
    printf("Writing binary file %s\n", filename);
    stl_write_binary(&stl, filename, "converted"); 6
    stl_exit_on_error(&stl); 7
  }

  stl_close(&stl); 8
  return EXIT_SUCCESS;
}

Další informace

Jednotlivé funkce a struktury knihovny najdete v souboru admesh/stl.h. Velkou dokumentací knihovna bohužel neoplývá, i když něco vzniká na admesh.readthedocs.io.