Opcje osadzania

Ostatnia aktualizacja: 2026-06-05

Dodanie ?embed=true do dowolnego adresu /view/:shareId przełącza przeglądarkę w czysty tryb osadzania: bez nagłówka, stopki i panelu informacji, z samym płótnem 3D oraz opcjonalnym paskiem narzędzi. Dodatkowe parametry w adresie URL pozwalają sterować najważniejszymi ustawieniami renderowania bez pisania JavaScriptu.

Format adresu URL

https://stlviewer.online/view/{shareId}?embed=true&param=value&...

Zasady używania adresu URL

  • Nieznane parametry są po cichu pomijane, więc przyszłe opcje nie popsują istniejących osadzeń.
  • Nieprawidłowe wartości wracają do ustawień domyślnych bez wyświetlania błędu.
  • Parametry logiczne przyjmują 1, 0, true albo false.
  • Parametry zostają zachowane podczas nawigacji w przeglądarce oraz przy użyciu przycisków wstecz/dalej.

Osadzanie modelu hostowanego zewnętrznie (?url=)

Jeśli plik STL, 3MF lub PLY jest już dostępny na GitHubie, CDN-ie albo Twoim serwerze, możesz pokazać go bez wcześniejszego przesyłania do STLViewer. Użyj formy /view?url= z zakodowanym adresem pliku i dodaj &embed=true, aby włączyć czysty tryb osadzania. Wszystkie parametry osadzania działają także z ?url=, na przykład &background=transparent&autoRotate=0.

https://stlviewer.online/view?url={encodedFileUrl}&embed=true&param=value&...
  • Adres pliku musi używać HTTPS i kończyć się na .stl, .3mf albo .ply; inne protokoły i rozszerzenia są odrzucane i przekierowują na stronę główną.
  • Model jest pobierany po stronie klienta, bezpośrednio z przeglądarki odwiedzającego; bajty modelu nie przechodzą przez serwery STLViewer.
  • Ponieważ pobieranie odbywa się między różnymi originami, serwer z plikiem musi zwracać liberalne nagłówki CORS, np. Access-Control-Allow-Origin: *. Bez nich osadzenie pokaże komunikat 'Cannot load this model' zamiast modelu.
  • Zakoduj adres pliku przed wstawieniem go do parametru url, aby jego własny query string, np. podpisany URL z S3, pozostał nienaruszony.
  • Cały plik trafia do pamięci przeglądarki, więc dla stabilnego działania na typowych urządzeniach trzymaj zewnętrzne modele poniżej około 100 MB.

Lista parametrów

Wszystkie parametry są opcjonalne. Wartości domyślne różnią się między zwykłym widokiem a trybem osadzania.

ParametrWartościDomyślnie poza osadzeniemDomyślnie w osadzeniuOpis
axisz | yzzOkreśla, która z własnych osi pliku jest skierowana w górę (z dla większości plików STL/CAD, y dla wielu eksportów z gier i programów DCC). Wpływa na płaszczyznę automatycznego obrotu i orientację kamery.
autoRotateboolean11Decyduje, czy model ma obracać się automatycznie po załadowaniu.
rendersolid | wireframe | xray | normalssolidsolidTryb renderowania modelu. normals koloruje każdą powierzchnię według kierunku, w którym jest zwrócona, dzięki czemu odwrócone ściany są dobrze widoczne.
normalSpaceview | worldviewviewTylko z render=normals. view koloruje powierzchnie względem kamery; world utrzymuje kolory przypisane do osi sceny.
normalShadingface | smoothfacefaceTylko z render=normals. face używa normalnej każdego trójkąta; smooth używa normalnych zapisanych w pliku.
gridboolean10Siatka podłogi pod modelem.
axesboolean00Gizmo orientacji XYZ w rogu płótna. Obraca się razem z kamerą.
lightstudio | neutral | flat | dramaticstudiostudioPreset oświetlenia sceny.
lightAzimuth0–360 (deg)——Nadpisuje azymut (kierunek poziomy) aktywnego presetu oświetlenia, w stopniach. Zawija się w zakresie 0–360. Gdy pominięty, używana jest wartość presetu.
lightElevation-90–90 (deg)——Nadpisuje elewację (kąt nad horyzontem) aktywnego presetu oświetlenia, w stopniach. Ograniczone do -90–90. Gdy pominięty, używana jest wartość presetu.
lightIntensity0–2——Nadpisuje intensywność światła kluczowego aktywnego presetu. Ograniczone do 0–2. Gdy pominięty, używana jest wartość presetu.
lightAmbient0–1——Nadpisuje światło otoczenia aktywnego presetu. Ograniczone do 0–1. Gdy pominięty, używana jest wartość presetu.
backgroundauto | light | dark | transparent | hex | env:<id>autoautoTło płótna. auto podąża za motywem strony; light/dark wymusza stały kolor; transparent przepuszcza tło strony pod osadzeniem; 6-znakowy hex (np. 1a2b3c) ustawia własny kolor; env:<id> używa obrazu otoczenia (studio, sunset, dawn, forest, city, warehouse).
materialpreset ID——Nazwany preset materiału. Listę identyfikatorów znajdziesz niżej.
uinone | minimal | fullfullnoneWidoczność interfejsu. none = samo płótno. minimal = widoczny pasek narzędzi. full = pasek narzędzi i panele boczne.
attributionboolean11Pokazuje plakietkę 'Powered by STLViewer'. false ukrywa plakietkę, ale zostawia faviconę i podpowiedź.

Identyfikatory presetów materiału

Jako wartość parametru material podaj identyfikator wybranego presetu.

color

  • color-blue — Blue
  • color-pastel-green — Green
  • color-pastel-red — Red
  • color-pastel-yellow — Yellow

metal

  • metal-steel — Steel
  • metal-copper — Copper
  • metal-gold — Gold
  • metal-aluminium — Aluminium
  • metal-chrome — Chrome

wood

  • wood-oak — Oak
  • wood-walnut — Walnut
  • wood-pine — Pine

stone

  • stone-marble — Marble
  • stone-granite — Granite
  • stone-concrete — Concrete

plastic

  • plastic-white — White
  • plastic-black — Black

ceramic

  • ceramic-white-glossy — Porcelain

Przykłady

Najprostsze osadzenie (ustawienia domyślne):

<iframe src="https://stlviewer.online/view/{shareId}?embed=true"
  title="My part" style="width:100%;height:600px;border:0;"
  loading="lazy" allowfullscreen></iframe>

Model ze stali z automatycznym obrotem:

<iframe src="https://stlviewer.online/view/{shareId}?embed=true&material=metal-steel&autoRotate=1"
  title="My part" style="width:100%;height:600px;border:0;"
  loading="lazy" allowfullscreen></iframe>

Statyczne osadzenie bez interfejsu (bez paska narzędzi i plakietki):

<iframe src="https://stlviewer.online/view/{shareId}?embed=true&autoRotate=0&attribution=0"
  title="My part" style="width:100%;height:600px;border:0;"
  loading="lazy" allowfullscreen></iframe>

Przezroczyste tło (za modelem widać stronę, na której jest osadzony):

<iframe src="https://stlviewer.online/view/{shareId}?embed=true&background=transparent"
  title="My part" width="800" height="600"
  frameborder="0" loading="lazy" allowfullscreen></iframe>

Plik hostowany zewnętrznie (bez przesyłania — wymagany host z CORS):

<iframe src="https://stlviewer.online/view?url=https%3A%2F%2Fcdn.example.com%2Fmodel.stl&embed=true&autoRotate=0"
  title="My part" style="width:100%;height:600px;border:0;"
  loading="lazy" allowfullscreen></iframe>