1、Information technology JPSearch Part 3: Query format AMENDMENT 1: JPSearch API Technologies de linformation JPSearch Partie 3: Format dinterrogation AMENDEMENT 1: API JPSearch INTERNATIONAL STANDARD ISO/IEC 24800-3 First edition 2010-05-01 Reference number ISO/IEC 24800-3:2010/Amd.1:2015(E) AMENDMEN
2、T 1 2015-12-15 ISO/IEC 2015 ii ISO/IEC 2015 All rights reserved COPYRIGHT PROTECTED DOCUMENT ISO/IEC 2015, Published in Switzerland All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized otherwise in any form or by any means, electronic or mechanic
3、al, including photocopying, or posting on the internet or an intranet, without prior written permission. Permission can be requested from either ISO at the address below or ISOs member body in the country of the requester. ISO copyright office Ch. de Blandonnet 8 CP 401 CH-1214 Vernier, Geneva, Swit
4、zerland Tel. +41 22 749 01 11 Fax +41 22 749 09 47 copyrightiso.org www.iso.org ISO/IEC 24800-3:2010/Amd.1:2015(E) ISO/IEC 24800-3:2010/Amd.1:2015(E) Foreword ISO (the International Organization for Standardization) and IEC (the International Electrotechnical Commission) form the specialized system
5、for worldwide standardization. National bodies that are members of ISO or IEC participate in the development of International Standards through technical committees established by the respective organization to deal with particular fields of technical activity. ISO and IEC technical committees colla
6、borate in fields of mutual interest. Other international organizations, governmental and non-governmental, in liaison with ISO and IEC, also take part in the work. In the field of information technology, ISO and IEC have established a joint technical committee, ISO/IEC JTC 1. The procedures used to
7、develop this document and those intended for its further maintenance are described in the ISO/IEC Directives, Part 1. In particular the different approval criteria needed for the different types of document should be noted. This document was drafted in accordance with the editorial rules of the ISO/
8、IEC Directives, Part 2 (see www.iso.org/directives). Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. ISO and IEC shall not be held responsible for identifying any or all such patent rights. Details of any patent rights identified
9、during the development of the document will be in the Introduction and/or on the ISO list of patent declarations received (see www.iso.org/patents). Any trade name used in this document is information given for the convenience of users and does not constitute an endorsement. For an explanation on th
10、e meaning of ISO specific terms and expressions related to conformity assessment, as well as information about ISOs adherence to the WTO principles in the Technical Barriers to Trade (TBT) see the following URL: Foreword - Supplementary information The committee responsible for this document is ISO/
11、IEC JTC 1, Information technology, Subcommittee SC 29, Coding of audio, picture, multimedia and hypermedia information. ISO/IEC 2015 All rights reserved iii Information technology JPSearch Part 3: Query format AMENDMENT 1: JPSearch API Add the following paragraph at the end of Clause 1. In addition,
12、 this part of ISO/IEC 24800 specifies the JPSearch API, a Restful State (REST) Application Programming Interface, complementary to the JPSearch Query Format (JPQF). It is primarily intended to be used for web services. Compared to JPQF, it does not only specify the query syntax, but also the protoco
13、ls used for sending and retrieving queries. It reduces the complexity of expressing image search queries by providing a simplified syntax to express common queries in the form of URIs. Furthermore, the API allows embedding JPQF queries to express more advanced queries or to use the API solely as a c
14、ommunication protocol for sending and retrieving queries between client and repository. In addition to text based search queries, the API provides functionality to support visual search applications, such as content-based image retrieval systems. Change the title of Clause 5 “Disabled datatypes” to
15、“JPQF Disabled datatypes”. Change the title of Clause 6 “Disabled Query Types” to “JPQF Disabled Query Types”. Move Clause 7 “Conformance” to the end of the document and update numbering. Add the following clauses to the end of the document (before Conformance). 7 Basic concepts of the JPSearch API
16、The API builds upon the HyperText Transfer Protocol (HTTP) for client-server communication. More specifically, in the context of a JPSearch-environment, the communication between a JPSearch-client and a JPSearch-server is specified. A JPSearch-client is any application that can formulate JPSearch- r
17、equests and handle JPSearch-responses. A JPSearch-server is an image repository that answers to JPSearch-requests and responds compliant with this part of ISO/IEC 24800. Requests are largely expressed using the Uniform Resource Identifier (URI) syntax. This part of ISO/IEC 24800 follows the RFC 3986
18、 syntax, as shown below: URI = scheme “:/” authority “/” path “?” query “#” fragment More specifically, this part of ISO/IEC 24800 focuses solely on the “query” part of the former definition. The query part is a sequence of key value pairs separated with an “ real numbers; ISO/IEC 24800-3:2010/Amd.1
19、:2015(E) ISO 2015 All rights reserved 1 ISO/IEC 24800-3:2010/Amd.1:2015(E) intervals: from-to, for example, 0-10 denotes any integer number between 0 and 10, 0.-10. denotes any real number between 0 and 10; boolean: 0 = false and 1 = true; string: strings should be URL encoded. Strings can be restri
20、cted to a specific syntax, e.g. a pair is a string of two values separated with a comma: “x,y”; enum: discrete list of valid values, where the options are separated with a “|”. For example: value1|value2|; time: formatted string according to ISO 8601 representation; geolocation: formatted string con
21、taining two comma separated real numbers representing latitude and longitude as decimal degrees with negative numbers for south and west. A JPSearch repository is completely free to specify the remaining part of the URI, i.e. the scheme, authority, path and fragments. Furthermore, additional query o
22、ptions can be specified, as long as they do not infer with the system query options. By default, JPSearch system query options do not have a prefix. However, in order to avoid collisions with custom query options, a prefix can be specified in the capability description. The capability description is
23、 a resource served by any JPSearch-server. It specifies the capabilities of the repository as well as its custom properties and settings. Any system query option can be enabled or disabled in the capability description. In addition, default values can be overwritten. It is the first resource request
24、ed in an initial interaction between a client and a repository. It informs the client about what queries can be send and how they should be formatted for the respective repository. A JPSearch-client requests resources from a JPSearch-server. A JPSearch-server serves the following resources: images:
25、binary image data; metadata of images (JPSearch Core metadata or JSON); image descriptions (JPOnto); collections of images: a set of images (JSON); resource identifiers or a collection of resource identifiers: in case the input itself is image data, the repository may return references to related re
26、sources of any kind; a JPQF output query (XML); a capability description: a description of the capabilities and properties of the respective repository (JSON). All these resources are discussed in more detail further in this part of ISO/IEC 24800. 8 JPSearch API: requesting resources 8.1 Image resou
27、rces The most essential resource type of an image repository is an individual image. The return type is a JPEG or JPEG 2000 image file. The original image can be requested by its resource identifier, without specifying any system query options. Various versions of the original image can be requested
28、 by 2 ISO 2015 All rights reserved ISO/IEC 24800-3:2010/Amd.1:2015(E) specifying system query options. The following table gives an overview of system query options specific to image resources. Argument Description Values Default crop Crops the image to a given aspect ratio. The image is cropped equ
29、ally to the top and bottom or to the left and right. This option is ignored if a region of interest is specified. none|w:h where w:h specifies the aspect ratio with w = width and h = height none discardmd Specifies whether the embedded metadata should be included or discarded. Boolean 0 maxw Specifi
30、es the maximum width of the returned image. Unsigned integer The width of the requested images. maxh Specifies the maximum height of the returned image. Unsigned integer The height of the requested image. minw Specifies the minimum width of the returned image. Unsigned integer The width of the reque
31、sted images. minh Specifies the minimum height of the returned image. Unsigned integer The height of the requested image. quality Specifies the quality of the returned image image as a value between 1 and 100 where 1 is the lowest quality and 100 is the highest quality. Percentage, 1-100 Original of
32、 the requested image, no recompression roff Region offset. Used in combination with rsize to request a rectangle region of interest. left,top where top and left are unsigned integers specifying the offset in pixels from the top and the left respectively 0,0 rsize Region size. Used in combination wit
33、h roff to request a rectangle region of interest. width,height where width and height are unsigned integers specifying the width and the height of the requested region The width and height of the requested image. scale Scale of the returned image with respect to the original image. Percentage, 0.-10
34、0. 100 thumb Specifies whether the image should be returned as a thumbnail. When a thumbnail is requested, maxw, maxh, minw, minh are set to 256, metadata to discard, crop to 1:1 (square) and quality to 50. These values are overwritten when any of these arguments is specified. Boolean 0 8.2 Image me
35、tadata Some applications need to present metadata of an image without presenting the image itself. Therefore, metadata can be requested separately from the image by specifying an image URI in combination with the metadata system query option. Metadata fields can be selected of the JPSearch Core Meta
36、data schema, ISO 2015 All rights reserved 3 ISO/IEC 24800-3:2010/Amd.1:2015(E) as defined in ISO/IEC 24800-2:2011. Alternatively, additional requestable fields can be defined in the capability description. When the GPSPositioning is requested, it is returned in the geolocation format specified in th
37、is document. The value of the metadata argument is a comma-separated list of the requested metadata fields represented by their name or XPath expression. For example, the following request: http:/www.repository.org/image.jpg?metadata=Title,Creators,GPSPositioning/ latitute,GPSPositioning, RightsDesc
38、ription/Description will return the following fields: Title: content of the title field; Creators: the GivenName and FamilyName of the creators, space separated; GPSPositioning/latitude: latitude attribute value of the GPS localization; GPSPositioning: complete GPS positioning; RightsDescription/Des
39、cription: content of the Description field of the RightsDescription element. The return format is a JSON file that contains the “metadata” field at root level. The metadata element contains an object with all the requested fields and their values. For example: “metadata“: “Title“: “Title of the imag
40、e“, “Creators“: “John Smith“, “GPSPositioning/latitude“: “50.85“, “GPSPositioning“: “50.85,4.35“, “RightsDescriptio n/Description“: “Rights description“ Alternatively, when the value is set to all, the complete JPCore metadata is returned. In this case, the return format is XML, i.e. JPCore metadata
41、 is returned according to ISO/IEC 24800-2. Finally, when it is set to description, a JPOnto description of the image is returned. In this case, the return format is compliant to the ISO/IEC 24800-2:2011/Amd 1 JPOnto specification. 8.3 Image collections 8.3.1 General A collection is a set of images i
42、dentified with a URI. In general, a collection is a subset of all images served by the repository. The repository is not limited in how it manages its own collections. Typically, the path part of the URI can be used to identify repositories. For example, an image hosting service may provide a collec
43、tion for every user. The collection of a specific user can be identified as follows. http:/www.repository.org/username If users can organize their pictures in sets, a set might be identified as follows. http:/www.repository.org/username/setname Alternatively, a repository can opt to identify collect
44、ions using query options, as long as these do not collide with the system query options. For example, http:/www.repository.org?user=username The return type of a collection is a JSON (application/json) file listing the resources of the images in the collection. Additional system query options can be
45、 specified, for example, to filter the results in the return set. The collection to which these options apply (i.e. the base URI) is referred to as the “context” of the request.4 ISO 2015 All rights reserved ISO/IEC 24800-3:2010/Amd.1:2015(E) 8.3.2 Collection system query options The following table
46、 gives an overview of system query options specific to image collection resources. Argument Description Values Default imgmeta Specifies which metadata of the images should be included. none| f ie ld 1 , f ie ld 2 , f l ie ld 3 none top Specifies the number of items included in the response. Unsigne
47、d integer 100 skip Specifies the index of the first returned item in the response (starting at 0). Unsigned integer 0 orderby Specifies by what metadata field the returned results should be ordered. relevance| f ie ld relevance orderdirec- tion Specifies whether the returned results should be ordere
48、d ascending or descending. asc|desc desc 8.3.3 Image collection syntax Image collections are returned as a JSON file with the following top-level fields. title Title of the collection String meta Any custom metadata about the collection as a comma-separated key value-pair list. String (comma separat
49、ed key-value pair list) count The total number of results. Unsigned integer images An array of images Array Images have the following fields. title Title of the image String size Size of the image Object with fields width and height which are both unsigned integers representing the width and height of the image respectively. uri Uri of the image String (URI) meta Metadata of the image String (comma separated key-value pair list) 8 . 4 Re s o
