pic4carto

    2.1.15 • Public • Published

    Pic4Carto.js

    build status

    Read-me

    Pic4Carto.js is a library for efficient retrieval of geolocated, free-licensed pictures. Its goal is to make easier to reuse pictures from several providers (Flickr, Mapillary, OpenStreetCam, Wikimedia Commons...). Using a simple API, you can retrieve all the pictures freely available over a given area. See the list of available providers.

    For the HTTP API version of Pic4Carto, please see the P4CaaS project.

    Help making this possible

    Install

    Pic4Carto.js can be installed following one of these methods.

    Using npm

    npm install pic4carto

    Then, access it in JS using require.

    var P4C = require("pic4carto");

    Using bundle version

    Download the latest archive from builds list. Extract it, put the P4C.min.js file somewhere accessible, and then import it in your HTML page using script markup.

    <script src="P4C.min.js"></script>
    <script>
    	var picManager = new P4C.PicturesManager();
    </script>

    Usage

    Here are some rapid examples of how to use Pic4Carto.js. If you want working examples, see HTML examples in dist/ folder. For complete documentation, check the API details.

    Get pictures in a given area

    var picManager = new P4C.PicturesManager();
    
    //Call for pictures download
    picManager.startPicsRetrieval(new P4C.LatLngBounds(new P4C.LatLng(48.1075, -1.6860), new P4C.LatLng(48.1156, -1.6739)))
    .then(function(pictures) { //Called when promise resolves
    	for(let pId=0; pId < pictures.length; pId++) {
    		let currentPicture = pictures[pId];
    		console.log(currentPicture.pictureUrl);
    	}
    });

    Get pictures within a circle

    var picManager = new P4C.PicturesManager();
    
    //Call for pictures download
    picManager.startPicsRetrievalAround(new P4C.LatLng(48.1075, -1.6860), 15) //15 meters around this point
    .then(function(pictures) { //Called when promise resolves
    	for(let pId=0; pId < pictures.length; pId++) {
    		let currentPicture = pictures[pId];
    		console.log(currentPicture.pictureUrl);
    	}
    });

    Show message when a fetcher has done or failed

    var picManager = new P4C.PicturesManager();
    
    //Asynchronous events for watching fetchers progress
    picManager
    	.on("fetcherdone", (fetcherId) => {
    		console.log("Fetcher "+fetcherId+" finished its pictures retrieval");
    	})
    	.on("fetcherfailed", (fetcherId) => {
    		console.log("Fetcher "+fetcherId+" failed to retrieve pictures");
    	});
    
    //Filtering only recent pictures (since mid-2016)
    picManager.startPicsRetrieval(new P4C.LatLngBounds(new P4C.LatLng(48.1075, -1.6860), new P4C.LatLng(48.1156, -1.6739)), { mindate: 1464775200000 })
    .then((picsArray) => { //Called when promise resolves
    	for(let pId=0; pId < picsArray.length; pId++) {
    		let currentPicture = picsArray[pId];
    		console.log(currentPicture.pictureUrl);
    	}
    });

    Get summary of pictures availability

    var picManager = new P4C.PicturesManager();
    
    //Call for pictures summary download (around Rennes center)
    picManager.startSummaryRetrieval(new P4C.LatLngBounds(new P4C.LatLng(48.1075, -1.6860), new P4C.LatLng(48.1156, -1.6739)))
    .then(function(summary) { //Called when promise resolves
    	console.log("Available pictures: "+((summary.approxAmount) ? "~" : "")+summary.amount+" | Last picture date: "+(new Date(summary.last).toDateString()));
    });

    Search through statically served images

    var picManager = new P4C.PicturesManager({
    	userDefinedFetchers: {
    		ownfetch: {
    			csv: "http://my.server.net/own/index.csv", // Mandatory
    			name: "OwnFetcher", // Recommended
    			homepage: "http://my.server.net/own/", // Optional
    			logo: "http://my.server.net/own/logo.png", // Recommended
    			bbox: new LatLngBounds(new LatLng(1.2, 48.7), new LatLng(1.3, 48.8)), // Recommended if you server pictures in a specific country/area
    			license: "CC By-SA 3.0", // Optional, can be overriden in CSV index
    			user: "Default user name" // Optional, can be overriden in CSV index
    		}
    	}
    });
    
    //then call picManager.startPicsRetrieval as shown above

    Get automatic detections from pictures in a given area

    var picManager = new P4C.PicturesManager();
    
    //Call for pictures download
    picManager.startDetectionsRetrieval(
    	new P4C.LatLngBounds(new P4C.LatLng(48.1075, -1.6860), new P4C.LatLng(48.1156, -1.6739)),
    	{ types: [ P4C.Detection.SIGN_ADVERT, P4C.Detection.SIGN_STORE ] }
    )
    .then(function(detections) { //Called when promise resolves
    	for(let dId=0; dId < detections.length; dId++) {
    		let currentDetection = detections[dId];
    		console.log(currentDetection.type);
    		console.log(currentDetection.date);
    		console.log(currentDetection.coordinates);
    	}
    });

    Build

    Dependencies

    • npm

    Compiling

    If you want to build Pic4Carto.js by yourself, run the following commands (or use directly compiled version in dist/ folder):

    npm install
    npm run build
    

    When this is done, Pic4Carto.js is ready in dist/ folder.

    Tests

    A test suite is available, run this command to generate test suite:

    npm run test
    

    Then, open the test/tests.html web page to run tests.

    Contributing

    Pic4Carto.js is an open-source project, and contributions are welcome. Here is how you can help:

    • Let us know about any free-licensed pictures provider you want to see integrated in Pic4Carto.js.
    • Report bugs or discuss new functionalities in the Issues tracker.
    • Write code (and tests) and create a merge request. As this project is using Git Flow branching model, please create requests on develop or feature/* branches.

    License

    Copyright 2016-2019 Adrien PAVIE

    See LICENSE for complete AGPL3 license. Pic4Carto.js is a fork based on Pic4Carto code basis.

    Pic4Carto.js is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

    Pic4Carto.js is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

    You should have received a copy of the GNU Affero General Public License along with Pic4Carto.js. If not, see http://www.gnu.org/licenses/.

    Install

    npm i pic4carto

    DownloadsWeekly Downloads

    10

    Version

    2.1.15

    License

    SEE LICENSE IN LICENSE.txt

    Unpacked Size

    517 kB

    Total Files

    40

    Last publish

    Collaborators

    • panieravide