Better docs

formats.md

@@ -66,7 +66,49 @@ Query format

                                
                                
                                
                            
                                
                                    
                                        
                                            66  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            67  
                                            The query format is based on YAML and used to query for pictures in the system.
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            68  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        69 +
                                        ### Structure
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        70 +
                                        The root can have 3 keys:
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        71 +
                                        * `want`: A list of rules that the images must satisfy. If not provided, no
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        72 +
                                          filtering is done.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        73 +
                                        * `exclude`: A list of rules that the images must not satisfy. If not provided,
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        74 +
                                          no filtering is done.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        75 +
                                        * `include_obsolete`: If true the query may return images with a designated
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        76 +
                                          replacement. If false (default) this won't be possible.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            77  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        78 +
                                        `want` and `exclude` are lists of rules. Each rule is a dictionary with a single
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        79 +
                                        key (this is to allow multiple rules of the same kind). Accepted rules are:
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        80 +
                                        * `has_object: [object1, object2, ...]`: The image must contain any of the
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        81 +
                                          objects in the list.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        82 +
                                        * `nature: [nature1, nature2, ...]`: The image must have one of the natures in
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        83 +
                                          the list. Natures are strings like "photo" that indicate the source of the
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        84 +
                                          image.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        85 +
                                        * `licence: [licence1, licence2, ...]`: The image must have one of the licences
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        86 +
                                          in the list. If possible, licence IDs are SPDX identifiers, non-standard ones
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        87 +
                                          are prefixed with `X-`.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        88 +
                                        * `author: [author1, author2, ...]`: The image's author's username must be in
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        89 +
                                          the list.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        90 +
                                        * `title: query`: Search for titles (`ilike`).
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        91 +
                                        * `description: query`: Search for descriptions (`ilike`).
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        92 +
                                        * `origin_url: query`: Search for origin URLs. The query matches the beginning
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        93 +
                                          of the URL excluding the protocol. (like `commons.wikimedia.org`)
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        94 +
                                        * `above_width: width`: The image must have a width greater than or equal to
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        95 +
                                          the given value, in pixels.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        96 +
                                        * `above_height: height`: The image must have a height greater than or equal to
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        97 +
                                          the given value, in pixels.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        98 +
                                        * `below_width: width`: The image must have a width less than or equal to the
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        99 +
                                          given value, in pixels.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        100 +
                                        * `below_height: height`: The image must have a height less than or equal to the
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        101 +
                                          given value, in pixels.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        102 +
                                        * `before_date: timestamp`: The image must have been uploaded before the given
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        103 +
                                          Unix timestamp.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        104 +
                                        * `after_date: timestamp`: The image must have been uploaded after the given
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        105 +
                                          Unix timestamp.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        106 +
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        107 +
                                        `ordering`, `offset` and `limit` can be specified as query parameters in the
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        108 +
                                        URL. `ordering` can be one of `date-desc`, `date-asc`, `title-asc`, `title-desc`,
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        109 +
                                        `number-regions-desc`, `number-regions-asc`, `random`. `offset` and `limit` are
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        110 +
                                        integers that specify the number of images to skip and the maximum number of
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        111 +
                                        images to return, respectively.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            112  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            113  
                                            ### Example
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            114  
                                            ~~~yaml
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        

@@ -82,13 +124,13 @@ want:

                                
                                
                                
                            
                                
                                    
                                        
                                            124  
                                                # a flower
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            125  
                                                # The following rule restricts the images to those with a certain source,
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            126  
                                                # like a camera or a drawing; omitting this rule means that the images can
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        85 -
                                            # be of any type
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        86 -
                                            - nature: ["photo", "drawing"]
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        127 +
                                            # be of any source
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        128 +
                                            - nature: ["photo", "computer-3d-art"]
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            129  
                                                # The following rule restricts the images to those with a certain licence
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            130  
                                                - licence: ["CC-BY-1.0", "CC-BY-2.0", "CC-BY-3.0", "CC-BY-4.0", "CC0-1.0",
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            131  
                                                            "Unlicense", "WTFPL", "MIT", "BSD-2-Clause", "BSD-3-Clause",
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        90 -
                                                        "Apache-2.0", "Informal-attribution", "Informal-do-anything",
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        91 -
                                                        "Public-domain-old", "Public-domain"]
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        132 +
                                                        "Apache-2.0", "X-informal-attribution", "X-informal-do-anything",
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        133 +
                                                        "X-public-domain-old", "X-public-domain"]
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            134  
                                            # Prohibitions for queried images
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            135  
                                            exclude:
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            136  
                                                # This means that the image must not contain any of the objects in the list
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        

@@ -100,6 +142,6 @@ exclude:

                                
                                
                                
                            
                                
                                    
                                        
                                            142  
                                                - below_height: 600
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            143  
                                            # In summary, we want images that contain both a cat and a dog, either a grass
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            144  
                                            # or a flower, but not a human, taken after 2019-01-01, must be a photo or a
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        103 -
                                        # drawing, must carry one of certain permissive licences and have a resolution
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        145 +
                                        # 3D render, must carry one of certain permissive licences and have a resolution
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            146  
                                            # of at least 800x600 pixels.
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            147  
                                            ~~~