forked from Jibo-Revival-Group/JiboOs
198 lines
7.8 KiB
JavaScript
198 lines
7.8 KiB
JavaScript
/**
|
|
* @typedef jibo.media#ThumbnailType
|
|
* @description Enum of thumbnail types
|
|
* @property thumb {any} Mobile
|
|
* @property thumb_robot {any} Robot
|
|
*/
|
|
|
|
/** Callback for {@link jibo.media#takePhoto}.
|
|
*
|
|
* ```
|
|
* jibo.media.takePhoto((err, data) => {
|
|
* if(!err) {
|
|
* let img = new Image();
|
|
* img.src = data.url;
|
|
* }
|
|
* else {
|
|
* console.error(err);
|
|
* }
|
|
* });
|
|
* ```
|
|
*
|
|
* @callback jibo.media~TakePhotoCallback
|
|
* @param [error] {Error|null} An error object if there was an error, or `null`.
|
|
* @param data {object} Data about the photo.
|
|
* @param data.id {string} Content ID of temporary in-memory preview photo.
|
|
* @param data.url {string} URL to retreive temporary in-memory preview photo.
|
|
*/
|
|
|
|
/** Callback for {@link jibo.media#storePhoto}.
|
|
*
|
|
* @callback jibo.media~StorePhotoCallback
|
|
* @param [error] {Error} error `null` if there is no error.
|
|
* @param [result] {object} The object's keys correspond to the
|
|
* thumbnail keys provided in the `thumbnails` argument of
|
|
* `storePhoto`. Values are the photo id as assigned by the media
|
|
* service. Use `getPhoto` to retrieve the PIXI.Texture that
|
|
* corresponds to this photo, or `getUrl` to get the url as served by
|
|
* the media service.
|
|
*/
|
|
|
|
/** Media API - jibo.media
|
|
*
|
|
* ```
|
|
* let params = {camera: jibo.media.CameraID.LEFT};
|
|
* jibo.media.takePhoto(params, (err, data) => {
|
|
* jibo.loader.load({src: data.url, format: 'binary'}, (error, buffer) => {
|
|
* jibo.media.storePhoto(
|
|
* buffer,
|
|
* (error, result) => {
|
|
* let thumbnailId = result.thumbnails[jibo.media.ThumbnailType.thumb_robot];
|
|
* jibo.media.getPhoto(thumbnailId, (err, pixiTexture) => {
|
|
* const s = new PIXI.Sprite();
|
|
* s.texture = pixiTexture;
|
|
* jibo.face.stage.addChild(s);
|
|
* })
|
|
* });
|
|
* });
|
|
* });
|
|
*
|
|
* ```
|
|
* You can use Promises instead of callbacks by simply omitting the callback.
|
|
* ```
|
|
* let params = {photoType: jibo.media.CameraID.PREVIEW};
|
|
* jibo.media.takePhoto(params)
|
|
* .then( (data) => {
|
|
* return jibo.media.storePhoto(data.id);
|
|
* })
|
|
* .then( (result) => {
|
|
* let thumbnailId = result.thumbnails[jibo.media.ThumbnailType.thumb_robot];
|
|
* return jibo.media.getPhoto(thumbnailId);
|
|
* .then( (pixiTexture) => {
|
|
* const s = new PIXI.Sprite();
|
|
* s.texture = pixiTexture;
|
|
* jibo.face.stage.addChild(s);
|
|
* });
|
|
* });
|
|
* ```
|
|
*
|
|
* @namespace jibo.media
|
|
*/
|
|
|
|
/** Take a photo. Returns data about photo including the content
|
|
* id and url to the temporary in-memory copy of the photo.
|
|
*
|
|
* @method jibo.media#takePhoto
|
|
* @param [params] {object} Optional parameters object.
|
|
* @param [params.camera=jibo.media.CameraID.RIGHT] {jibo.media#CameraID}
|
|
* Which camera to use, left or right.
|
|
* @param [params.photoType=jibo.media.PhotoType.FULL] {jibo.media#PhotoType}
|
|
* Size/type of photo to take.
|
|
* @param [params.undistort=true] {boolean} Undistort (flatten)
|
|
* the photo. If `false` image will have fish-eye distortion.
|
|
* @param [params.flip=true] {boolean} Flip (mirror) the photo.
|
|
* If `false` image will not be flipped.
|
|
* @param [params.colorCorrection=true] {boolean} Apply a default
|
|
* set of filters to the photo (brightness, contrast, vibrance,
|
|
* hue, saturation and RGB curve) to give it a more natural
|
|
* appearence.
|
|
* @param [params.filters] {jibo.media~Filter[]} List of filters
|
|
* to apply to the image in order. Embedding in an array is
|
|
* optional if only one filter is specified.
|
|
* @param [callback] {jibo.media~TakePhotoCallback} Called with an
|
|
* error, or with data about the photo including the content ID
|
|
* (`data.id`). If callback is omitted a promise is returned
|
|
* instead.
|
|
* @returns {Promise} A promise that resolves when the operation is
|
|
* finished.
|
|
*/
|
|
|
|
/** Save a temporary in-memory photo via the content id returned
|
|
* from `takePhoto`, or via a buffer object. Photo will be saved
|
|
* locally to disk and in the cloud. Default thumbnails (`thumb`
|
|
* for mobile, and `thumb_robot` for Jibo) will be generated and
|
|
* also saved. The KB media list `jibo.kb.media` will also be
|
|
* updated. Data including the content id and url is provided.
|
|
*
|
|
* @method jibo.media#storePhoto
|
|
* @param [id] {string} Content id of in-memory recently taken
|
|
* photo to be stored. Can also be specified via `params.id`.
|
|
* @param [buffer] {Buffer} Instead of providing an id, an image
|
|
* in a buffer object to store. Can also be specified via
|
|
* `params.buffer`.
|
|
* @param [params] {object} Optional parameters object.
|
|
* @param [params.id] {string} Content id of in-memory recently taken photo to be stored.
|
|
* @param [params.buffer] {Buffer} An image in a buffer object to be stored.
|
|
* @param [callback] {jibo.media~StorePhotoCallback} Called when
|
|
* photos are stored. If callback is omitted a promise is returned
|
|
* instead.
|
|
* @returns {Promise} A promise that resolves when the operation is
|
|
* finished.
|
|
*/
|
|
|
|
/** Delete a photo from the local image store and from the cloud.
|
|
*
|
|
* @method jibo.media#deletePhoto
|
|
* @param id {string} Content ID of photo to delete.
|
|
* @param [callback] {function} Called with err object if there
|
|
* was an error. If callback is omitted a promise is returned instead.
|
|
* @returns {Promise} A promise that resolves when the operation is
|
|
* finished.
|
|
*/
|
|
|
|
/** Retrieve the PIXI.Texture that corresponds to the specified photo.
|
|
*
|
|
* @method jibo.media#getPhoto
|
|
* @param id {string} The photo ID to retrieve the texture for.
|
|
* @param [callback] {function} Node style callback that returns a
|
|
* `PIXI.Texture`. If callback is omitted a promise is returned
|
|
* instead.
|
|
* @returns {Promise} A promise that resolves when the operation
|
|
* is finished.
|
|
*/
|
|
|
|
/** Get a URL given a photo ID.
|
|
*
|
|
* @method jibo.media#getUrl
|
|
* @param id {string} Content ID of the photo.
|
|
* @returns {string} URL to the photo.
|
|
*/
|
|
|
|
/** Get the preview URL of a recently taken
|
|
* in-memory photo that hasn't been stored yet.
|
|
*
|
|
* @method jibo.media#getPreviewUrl
|
|
* @param id {string} Content ID of the photo.
|
|
* @returns {string} URL to the photo.
|
|
*/
|
|
|
|
/** Set up a viewfinder in a window with camera preview positioned
|
|
* at a given location on-screen.
|
|
*
|
|
* @method jibo.media#setViewfinder
|
|
* @param [enable=false] {boolean} Show (enable) or hide
|
|
* viewfinder. Can also be specified via `params.enable`.
|
|
* @param [params] {object} Optional parameters object.
|
|
* @param [params.enable=false] {boolean} Show (enable) or hide
|
|
* viewfinder.
|
|
* @param [params.width=1280] {number} Width of the viewfinder in pixels.
|
|
* @param [params.height=720] {number} Height of the viewfinder in pixels.
|
|
* @param [params.x=0] {number} X-coordinate for placing the viewfinder. In pixels.
|
|
* @param [params.y=0] {number} Y-coordinate for placing the viewfinder. In pixels.
|
|
* @param [params.camera=1] {number} Camera to use. 0=Left, 1=Right.
|
|
* @param [callback] {function} Callback for the method. If callback
|
|
* is omitted a promise is returned instead.
|
|
* @returns {Promise} A promise that resolves when the
|
|
* operation is finished.
|
|
*/
|
|
|
|
/** Get the current state of the viewfinder preview window.
|
|
*
|
|
* @method jibo.media#getViewfinder
|
|
* @param [callback] {function} Callback for the function that
|
|
* returns an error, or if request is successful returns object
|
|
* with timestamp, enable, and window. If callback is omitted a
|
|
* promise is returned instead.
|
|
* @returns {Promise} A promise that resolves when the
|
|
* operation is finished.
|
|
*/ |