└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Verold Studio Uploader API 2 | 3 | The Uploader API allows for developers to create integrations between modelling tools, ​3D scanning software, or other sources of 3D content. You can easily upload models and textures to Verold Studio through the API. 4 | 5 | ## POST projects.json: 6 | 7 | The method POST on http://studio.verold.com/projects.json allows you to create a new project ​with one or more assets (models, textures, materials, etc.). An example of using the API is given here, with detailed descriptions of the parameters below. 8 | 9 | # easy_install poster 10 | from poster.encode import multipart_encode 11 | from poster.streaminghttp import register_openers 12 | import urllib2 13 | 14 | # Register the streaming http handlers with urllib2 15 | register_openers() 16 | 17 | import json 18 | import base64 19 | import urllib2 20 | 21 | url="http://studio.verold.com/projects.json" 22 | 23 | data = { 24 | 'api_key': "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", 25 | 'title': "My First Project", 26 | 'description': "Hello World! This is my first project!", 27 | 'model': open("./model.zip"), 28 | 'tags': "test,first", 29 | 'private': "public" 30 | } 31 | 32 | datamulti, headers = multipart_encode(data) 33 | 34 | request = urllib2.Request(url, datamulti, headers) 35 | print urllib2.urlopen(request).read() 36 | 37 | 38 | ### api_key 39 | The user’s API key, used for authentication. You can get your personal API key from here. 40 | 41 | ### model 42 | The model file. For best results, we recommend uploading a ZIP file containing the model (in OBJ, Collada, or FBX format) and all textures. 43 | 44 | ### title (optional) 45 | The project title. 46 | 47 | ### description (optional) 48 | The project description. 49 | 50 | ### tags (optional) 51 | A comma-separated list of project tags. 52 | 53 | ### private (optional) 54 | Set to “public” or “private” (Pro accounts only). If private is set to “private” for a non-Pro account, the value is silently changed to “public” without generating an error. Defaults to private for Pro accounts. 55 | 56 | ### scale_to_size (optional) 57 | Scales the model(s) to fit in a cube of this size, placed on the ground plane. Default: don’t scale model(s). 58 | 59 | ### merge_models (optional) 60 | If “1”, treat multiple models as a single model. When uploading multiple models in a ZIP archive, it is often best to set merge_models to “1” so that the relative sizing of each model is preserved; otherwise, models are scaled independently according to scale_to_size. Default: Don’t merge models. 61 | 62 | ## Response 63 | 64 | If the project is created successfully, the response code is 201 and the response takes the form: 65 | 66 | { "id":"511399f3fc77b30200000469", … } 67 | 68 | The project can be viewed at: 69 | 70 | > http://studio.verold.com/projects/511399f3fc77b30200000469 71 | 72 | If an error occurs, check the response code. For example, an invalid API key results in a 401 (unauthorized) response. 73 | 74 | # Determining Processing Success/Failure 75 | 76 | When a model is uploaded to Verold Studio, it is passed off asynchrnously to a cluster of processing servers where the models are optimized, compressed, and added to your project scene. This means, that if you redirect the user directly to Verold Studio immediately after the model files have been uploaded, that the user will likely get there before the modelrs are ready in the scene. Verold Studio will detect that there are jobs processing, and inform the user that a model is on the way. When it's ready, it will be automatically loaded into the scene. 77 | 78 | We deliberately do not hold the request open while the uploaded models are processing. However, if you would like to hold the user in your tools until the models have been fully processed, you can easily achieve this by polling on the jobs queue of the project. Then you can only redirect the user to Verold Studio after the model has been fully processed. For this, use the Jobs API: 79 | 80 | GET /projects/{project_id}/jobs.json 81 | 82 | an example url is: 83 | 84 | http://studio.verold.com/projects/51504881c1f95e02000002da/jobs.json 85 | 86 | The JSON output from that link is: 87 | 88 | [ 89 | { 90 | id: "51504899c1f95e02000002e2", 91 | userId: "xxxxxxxxxxxxxxxxxxxxxxx", 92 | projectId: "123123123123123123123", 93 | filePath: "uploads/asahashashgashahg/hashjahjashsahjashjashjashjahjashjsa/fighter.fbx", 94 | state: "COMPLETE", 95 | autoInstance: false, 96 | dateCreated: "2013-03-25T12:52:41.682Z", 97 | dateModified: "2013-03-25T12:49:36.931Z" 98 | }, 99 | ... 100 | ] 101 | 102 | 103 | There will be one entry for each uploaded file, and the state of each entry will be one of: 104 | 105 | 'CREATED', 'STARTED', 'COMPLETE', 'ERROR' 106 | 107 | In normal circumstances the job should go to either complete or error fairly quickly, depending on the complexity of the model. 108 | 109 | # Optimization 110 | 111 | The Verold Uploader supports decimation and optimization during the upload process. This is especially useful for high-res 3D scans; using the optimization parameters you can very easily generate a version of your model that can be displayed in realtime. Be aware that using these optimization parameters will slow the upload process. 112 | 113 | For an example of how to use the optimization parameters, see the Python upload script: 114 | 115 | Python/VeroldUploader.py 116 | 117 | You can run this as follows: 118 | 119 | python VeroldUploader.py -k api_key -d 0.1 -t 50000 file.obj 120 | 121 | The first step of optimization is to decimate the model. You can speficy either -d for the decimation percentage, or -t for the maximum number of polygons. Models less than 20K polys load extremely fast, then up to 200K polys load pretty well. Beyond 200K polys, model loading gets slower, sometimes unbearably slow on lower powered client machines. 122 | --------------------------------------------------------------------------------