Stl Viewer Javascript Plugin

Intro

Download

Installation

Usage

Parameters

Methods

Events / Callbacks

Save/Load Methods

License

Example

Javascript STL/OBJ/3MF 3D files Viewer

Download

Click to download Stl Viewer v1.13

OR

Installation

Upload those files into your web server:
stl_viewer.min.js
parser.min.js
load_stl.min.js
webgl_detector.js
CanvasRenderer.js
OrbitControls.js
TrackballControls.js
Projector.js
three.min.js

Usage

At the html page header / page body:
<script src="stl_viewer.min.js"></script>
At the page body, create an element to contain the Stl Viewer, and give it an ID:
<div id="stl_cont"></div>
Create a new instance of Stl Viewer (simplest initiation - read and view STL file called 'mystl.stl'):
var stl_viewer=new StlViewer(document.getElementById("stl_cont"), { models: [ {id:0, filename:"mystl.stl"} ] });
Working Example

copy

Optional parameters at initialization

var object_name = new StlViewer(html element container, [{[optional] init parameters}]);
object_nameoptional, holds instance of the created Stl Viewer
html element containerrequired, a reference to html element that will containt the Stl Viewer
[optional] init parameters all_loaded_callbackJavascript function to call after all 3D files were loaded (Default: null), See Events allow_drag_and_dropAllowing/not allowing user to drag and drop 3D files into viewer container (true/false; Default:true) auto_resizeSet camera to fit all 3D object in container (after all were loaded) (true/false; Default: true) auto_rotateAuto rotates camera if true (true/false; Default: false) mouse_zoomEnable mouse wheel zoom (true/false; Default: true) bgcolorBackground color for html container (String; Default: "transparent") cameraxCamera X axis position (Number; Default: 0) camerayCamera Y axis position (Number; Default: 0) canvas_widthWidth of the stl viewer (String represents css attribute; Default: "100%") canvas_heightHeight of the stl viewer (String represents css attribute; Default: "100%") load_three_filesLoad THREE.js lib files in the background (String represents relative path to files / or false to not load THREE js files ; Default: "" - assumes THREE js files are at the same folder as the page) loading_progress_callbackJavascript function to call during loading process (of one or more 3D files) (Default: null), See Events modelsArray of models to load (see here; Default:null) model_loaded_callbackJavascript function to call after (any) 3D file was loaded (Default: null), See Events load_error_callbackJavascript function to call after a loading error (Default: null), See Events on_model_dropJavascript function to call after 3D file was dropped into container (Default: null), See Events on_model_mouseclickJavscript function to call after mouse button was clicked on a model (Default: null), See Events send_no_model_click_eventWhether to trigger model click event when user clicked on nothing (no model) (Default: false) ready_callbackJavascript function to call after THREE.js files were loaded (Default: null), See Events zoomWhich zoom to use (relevant when auto_resize is set to false) (Number, -1 means auto zoom; Default: -1) center_modelsCenter model at the middle of parent element after loaded(true/false; Default: true) controlsCamera control type (0=OrbitControls, 1=TrackballControls; Default: 0) jszip_pathRelative path to jszip.min.js file, only needed when dealing with vsb or 3mf files (Default: null) jszip_utils_pathRelative path to jszip-utils.min.js file, only needed when dealing with vsb or 3mf files (Default: null)
Working Example

copy

'Models' parameter

Array of models to load: [{models to load parameters}, {...}, ...]
[optional] models to load parameters idA uniqe id to indentify the model (Positive number (-1 for auto id), Default: -1) filenameURL of file to load (String) local_fileUser chosen local file to load (HTML file input element) meshExisting mesh to add (THREE.js mesh object) xModel X-axis position (Number, Default: 0) yModel Y-axis position (Number, Default: 0) zModel Z-axis position (Number, Default: 0) displayModel shading to display (String: "flat" / "smooth"/ "wireframe", Default: "flat") colorModel color (String "#RRGGBB" represents RGB set, Default: "#909090") scaleScale factor for all axises (Positive number, Default: 1) scalexScale factor for X-axis (Positive number, Default: 1) scaleyScale factor for Y-axis (Positive number, Default: 1) scalezScale factor for Z-axis (Positive number, Default: 1) rotationxRotation on world X-axis (Number represents radians, Default: 0) rotationyRotation on world Y-axis (Number represents radians, Default: 0) rotationzRotation on world Z-axis (Number represents radians, Default: 0) opacityModel opacity (Number between 0 and 1, Default: 1) view_edgesAdd edges on model (true/false, Default: false) unitsModel units ('mm'/'inch', Default: 'mm') animationApply animation on model (see here; Default:null)
Working Example

copy

'Animation' parameter

Apply animation on model: {delta/exact:{animation parameters}}
[rqeuired] delta/exact deltaAdd (animation parameter's) values to current model position exactSet (animation parameter's) values of current model position
[optional] animation parameters msecAnimation time duration (how much time to animate?) (Number represents milliseconds, Default: 300) loopAnimation loop (relevant to 'delta' animation only) (true/false, Default: false) xX-axis end position (Number, Default: 0) yY-axis end position (Number, Default: 0) zZ-axis end position (Number, Default: 0) rotationxX-axis end rotation angle (Number represents radians, Default: 0) rotationyY-axis end rotation angle (Number represents radians, Default: 0) rotationzZ-axis end rotation angle (Number represents radians, Default: 0) scalexX-axis end scale factor (Positive number, Default: null) scaleyY-axis end scale factor (Positive number, Default: null) scalezZ-axis end scale factor (Positive number, Default: null) scaleEnd scale factor for all axises (Positive number, Default: null)
Working Example

copy

Methods

add_model (new_model)
Add a new model to scene (new_model: model data)
Example (load STL and give it id 1):
stl_viewer.add_model({id:1, filename:"knot.stl"});
add_models ([new_model, new_modelm ...])
Add multiple models to scene (new_model: array of model data)
Example (load two STLs and give them ids 1 and 2):
stl_viewer.add_models([{id:1, filename:"knot.stl"}, {id:2, filename:"bar.stl"}]);
remove_model (model_id)
Remove model from scene (model_id: Number)
Example (remove model with id 5):
stl_viewer.remove_model(5);
set_display (model_id, display)
Set model display/shading (model_id: Number; display:"flat"/"smooth"/"wireframe")
Example:
stl_viewer.set_display(2, "smooth");
set_color (model_id, color)
Set model color (model_id: Number; color:string "#RRGGBB" represents RGB set, or "transparent")
Example (set color of model id #2 to blue):
stl_viewer.set_color(2, "#0000FF");
set_opacity (model_id, opacity)
Set model opacity/transparency (model_id: Number; opacity:Number between 0 and 1)
Example:
stl_viewer.set_opacity(5, 0.5);
set_position (model_id, x,y,z)
Set model position (model_id: Number; x:x-axis position; y:y-axis position; z:z-axis position )
Example (set model #2 at position 100/100/100):
stl_viewer.set_position(2, 100, 100, 100);
set_scale (model_id, scalex, scaley, scalez)
Set model scaling/resizing factor (model_id: Number; scalex:x-axis scale factor; scaley:y-axis scale factor; scalez:z-axis scale factor)
Example (set model #7 twice as big):
stl_viewer.set_scale(7, 2);
set_edges (model_id, b)
Set edges around model? (model_id: Number; b:true/false)
Example (draw edges around model #5):
stl_viewer.set_edges(5, true);
set_grid (b), size, divisions
Draw grid around scene? (b:true/false; size:grid size (Number, default: covers all models); divisions:number of divisions (default: 10))
Example:
stl_viewer.set_grid(true);
rotate (model_id, axis_x_angel, axis_y_angel, axis_z_angel)
Rotation of model (model_id: Number; axis_x_angel:Number represents radians around x-axis; axis_y_angel:radians around y-axis; axis_z_angel:Number represents radians around z-axis)
Example (rotate model #2 0.5 radias around x axis):
stl_viewer.rotate(2, 0.5, 0, 0);
animate_model (model_id, animation)
Set animation on model (model_id: Number; animation:animation data, null to remove animation)
Example (make model #1 move 100 pixels on y axis, in one second):
stl_viewer.animate_model(1, {delta:{y:100, msec:1000}} );
get_model_info (model_id)
Returns model info as object: model name, position, dimensions, rotation, display type, color, scale, volume, area and triangles count (model_id: Number)
Example (display model info as JSON string):
alert( JSON.stringify(stl_viewer.get_model_info(5)) );
get_model_mesh (model_id)
Returns THREE JS Mesh object (model_id: Number)
Example (get mesh of model 2):
var my_mesh = get_model_mesh (2);
set_bg_color (bg_color)
Set scene background color (bg_color: String "#RRGGBB" represents RGB set / 'transparent')
Example (set scene background yellow):
stl_viewer.set_bg_color("#FFFF00");
set_center_models (b)
Center models at the middle of parent element after loaded (b: true/false)
set_zoom (zoom_value)
Set screen zoom (zoom_value: Number / -1 for auto zoom)
set_auto_zoom()
Set screen auto zoom
set_auto_rotate (b)
Set screen auto rotation (b: true/false)
set_mouse_zoom (b)
Enable mouse wheel zoom (b: true/false)
Example (remove the ability to zoom with a mouse):
stl_viewer.set_mouse_zoom(false);
set_auto_resize (b)
Resize html container element with screen resize? (b: true/false)
clean ()
Removes all 3D models, clean scene
set_on_model_mouseclick (callback)
Set 'onmouseclick' listener (callback: Javascript function), See Events
Example (call function 'yeh_mouse_down' when any model was clicked):
stl_viewer.set_on_model_mouseclick(yeh_mouse_down);
set_drag_and_drop (b)
Load 3D model by user's 'drag and drop' action (b: true/false)
Example (allow user to drag&drop model files into scene):
stl_viewer.set_drag_and_drop(true);
get_camera_state ()
Returns camera state as Javscript object {position, up, target}
Example:
var camera_state = stl_viewer.get_camera_state();
set_camera_state ()
Set camera state by Javscript object ({position, up, target}) - potision/up/taraget are x/y/z vectors
Example:
stl_viewer.set_camera_state(camera_state);
set_model_units (units, scale)
Set model unit (units: 'mm'/'inch', scale: whether to scale model size true/false)
Example:
stl_viewer.set_model_units('inch', true);
dispose ()
Free objects and remove all internal references, use this when you want to remove plugin's instance from memory
Example:
stl_viewer.dispose(); stl_viewer=null;
Working Example

copy

Events / Callbacks

ready_callback()
Called after THREE JS files were loaded
all_loaded_callback()
Called after all 3D files were loaded
loading_progress_callback(load_status, load_session)
Called multiple times during loading of 3D file(s) (load_status: array of loading models with two fileds: loaded, total; load_session: Number, represents current loading session) See example
model_loaded_callback(model_id)
Called after a model was loaded (model_id: Number, represents the model that was loaded)
load_error_callback(error_str)
Called after loading error (error_str: String, the error description)
on_model_drop(filename)
Called after 3D model was dragged and dropped to scene (and starts being loaded) (filename: String, 3D file name)
on_model_mouseclick(model_id, e, distance, click_type)
Called after mouse button was down on a 3D model (model_id: Number, represents the model that was clicked; e:DOM event object; distance:distance form camera (z axis); click_type: Number, 1=left click, 3=right click, 11=double click, 20=touch screen)

Save/Load Methods

* Using those methods in IE11/Edge requires ie_polyfills.js (file included)
get_stl_bin (model_id)
Returns STL formatted model as arraybuffer (model_id: Number)
Example:
var model_binary_data = stl_viewer.get_stl_bin(0);
download_model (model_id[, filename])
download model as STL file (model_id: Number; filename: name of the file (optional), default: model's original filename)
Example:
stl_viewer.download_model(0, 'my_model.stl');
get_vsj (as_js_obj)
Returns current scene status as Javscript object or JSON string, contains models info, container properties; doesn't contain events and model's binary data (as_js_obj: true/false; Default:false; if true: returns Javscript Object, if false - returns JSON string)
Example:
var scene_status = stl_viewer.get_vsj();
Result (assuming one model named bar.stl in scene):
{"canvas_height":"100%","bg_color":"transparent","camera_state":{"position":{"x":0,"y":0,"z":74.39999999999999},"up":{"x":0,"y":1,"z":0},"target":{"x":0,"y":0,"z":0}},"auto_rotate":false,"mouse_zoom":true,"auto_resize":true,"center_models":true,"models":[{"id":0,"filename":"some_model.stl","display":"flat","color":"#F0F0F0"}]}
download_vsj (filename)
Download a json/text file with current scene status (filename: name of the file (optional), default: 1.vsj)
Example:
stl_viewer.download_vsj('my_scene.vsj');
load_vsj (filename)
Load scene from vsj - ViewStl JSON file (filename: URL of vsj file | HTML file object)
Example:
stl_viewer.load_vsj('my_scene.vsj');
get_vsb ()
Returns current scene status as Javscript object, INCLUDING model's binary data (means: you don't need to keep the original STL files or anything else besides this vsb file)
Example:
var vsb = stl_viewer.get_vsb();
Result:
Object {vsj: Object (see get_vsj), files: array of models {id: number, bin: ArrayBuffer}}
get_vsb_blob ()
Returns current scene's vsb as blob, method acts as Promise (see example code)
(then you can send this blob to server in order to save it as file)
Dependency: JSZip (library not included in Viewstl plugin, you must load it within your page OR supply jszip_path and jszip_utils_path parameters)
Example:
stl_viewer.get_vsb_blob('1.vsb').then(function (content) {console.log("my vsb as blob: ", content);});
Result: my_scene.vsb: a ZIP compressed file, contains json.data.vsj (see get_vsj), and models as STL files
download_vsb (filename)
Download current scene as vsb file - ViewStl Binary (filename: name of the file (optional), default: 1.vsb)
(you don't need to keep the original STL files or anything else besides this vsb file)
Dependency: JSZip (library not included in Viewstl plugin, you must load it within your page OR supply jszip_path and jszip_utils_path parameters)
Example:
stl_viewer.download_vsb('my_scene.vsb');
Result: my_scene.vsb: a ZIP compressed file, contains json.data.vsj (see get_vsj), and models as STL files
load_vsb (filename)
Load scene from vsb - ViewStl Binary file (filename: URL of vsb file | HTML file object)
Dependency: JSZip (library not included in Viewstl plugin, you must load it within your page OR supply jszip_path and jszip_utils_path parameters)
Example:
stl_viewer.load_vsb('my_scene.vsb');
Working Example

copy

License

Viewstl Javscript plugin is licensed under the MIT License - Copyright (c) 2019 Viewstl.com

Terms of use / Terms of service

See Viewstl.com terms of service

Live Preview

Click here for live preview