• Stars
    star
    181
  • Rank 212,110 (Top 5 %)
  • Language
    Python
  • License
    BSD 3-Clause "New...
  • Created about 7 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Reusable Django app for storing geographic and indoor coordinates. Maintained by the OpenWISP Project.

django-loci

CI build status Dependency monitoring https://img.shields.io/gitter/room/nwjs/nw.js.svg?style=flat-square downloads code style: black

Reusable django-app for storing GIS and indoor coordinates of objects.

Indoor coordinates Map coordinates Mobile coordinates

Dependencies

Compatibility Table

django-loci Python version
0.2 2.7 or >=3.4
0.3 - 0.4 >=3.6
1.0 >=3.7
dev >=3.8

Install stable version from pypi

Install from pypi:

pip install django-loci

Install development version

First of all, install the dependencies of GeoDjango:

Install tarball:

pip install https://github.com/openwisp/django-loci/tarball/master

Alternatively you can install via pip using git:

pip install -e git+git://github.com/openwisp/django-loci#egg=django_loci

If you want to contribute, install your cloned fork:

git clone [email protected]:<your_fork>/django-loci.git
cd django_loci
python setup.py develop

Setup (integrate in an existing django project)

First of all, set up your database engine to one of the spatial databases suppported by GeoDjango.

Add django_loci and its dependencies to INSTALLED_APPS in the following order:

INSTALLED_APPS = [
    # ...
    'django.contrib.gis',
    'django_loci',
    'django.contrib.admin',
    'leaflet',
    'channels'
    # ...
]

Configure CHANNEL_LAYERS according to your needs, a sample configuration can be:

ASGI_APPLICATION = "django_loci.channels.routing.channel_routing"
CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "channels.layers.InMemoryChannelLayer",
    },
}

Now run migrations:

./manage.py migrate

Troubleshooting

Common issues and solutions when installing GeoDjango.

Unable to load the SpatiaLite library extension

If you get the following exception:

django.core.exceptions.ImproperlyConfigured: Unable to load the SpatiaLite library extension

You need to specify the SPATIALITE_LIBRARY_PATH in your settings.py as explained in the django documentation regarding how to install and configure spatialte.

Issues with other geospatial libraries

Please refer to the geodjango documentation on troubleshooting issues related to geospatial libraries.

Settings

LOCI_FLOORPLAN_STORAGE

type: str
default: django_loci.storage.OverwriteStorage

The django file storage class used for uploading floorplan images.

The filestorage can be changed to a different one as long as it has an upload_to class method which will be passed to FloorPlan.image.upload_to.

To understand the details of this statement, take a look at the code of django_loci.storage.OverwriteStorage.

DJANGO_LOCI_GEOCODER

type: str
default: ArcGIS

Service used for geocoding and reverse geocoding.

Supported geolocation services:

  • ArcGIS
  • Nominatim
  • GoogleV3 (Google Maps v3)

DJANGO_LOCI_GEOCODE_FAILURE_DELAY

type: int
default: 1

Amount of seconds between geocoding retry API calls when geocoding requests fail.

DJANGO_LOCI_GEOCODE_RETRIES

type: int
default: 3

Amount of retry API calls when geocoding requests fail.

DJANGO_LOCI_GEOCODE_API_KEY

type: str
default: None

API key if required (eg: Google Maps).

System Checks

geocoding

Use to check if geocoding is working as expected or not.

Run this checks with:

./manage.py check --deploy --tag geocoding

Extending django-loci

django-loci provides a set of models and admin classes which can be imported, extended and reused by third party apps.

To extend django-loci, you MUST NOT add it to settings.INSTALLED_APPS, but you must create your own app (which goes into settings.INSTALLED_APPS), import the base classes of django-loci and add your customizations.

Extending models

This example provides an example of how to extend the base models of django-loci by adding a relation to another django model named Organization.

# models.py of your app
from django.db import models
from django_loci.base.models import (AbstractFloorPlan,
                                     AbstractLocation,
                                     AbstractObjectLocation)

# the model ``organizations.Organization`` is omitted for brevity
# if you are curious to see a real implementation, check out django-organizations


class OrganizationMixin(models.Model):
    organization = models.ForeignKey('organizations.Organization')

    class Meta:
        abstract = True


class Location(OrganizationMixin, AbstractLocation):
    class Meta(AbstractLocation.Meta):
        abstract = False

    def clean(self):
        # your own validation logic here...
        pass


class FloorPlan(OrganizationMixin, AbstractFloorPlan):
    location = models.ForeignKey(Location)

    class Meta(AbstractFloorPlan.Meta):
        abstract = False

    def clean(self):
        # your own validation logic here...
        pass


class ObjectLocation(OrganizationMixin, AbstractObjectLocation):
    location = models.ForeignKey(Location, models.PROTECT,
                                 blank=True, null=True)
    floorplan = models.ForeignKey(FloorPlan, models.PROTECT,
                                  blank=True, null=True)

    class Meta(AbstractObjectLocation.Meta):
        abstract = False

    def clean(self):
        # your own validation logic here...
        pass

Extending the admin

Following the previous Organization example, you can avoid duplicating the admin code by importing the base admin classes and registering your models with them.

But first you have to change a few settings in your settings.py, these are needed in order to load the admin templates and static files of django-loci even if it's not listed in settings.INSTALLED_APPS.

Add django.forms to INSTALLED_APPS, now it should look like the following:

INSTALLED_APPS = [
    # ...
    'django.contrib.gis',
    'django_loci',
    'django.contrib.admin',
    #      ↓
    'django.forms', # <-- add this
    #      ↑
    'leaflet',
    'channels'
    # ...
]

Now add EXTENDED_APPS after INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
]

EXTENDED_APPS = ('django_loci',)

Add openwisp_utils.staticfiles.DependencyFinder to STATICFILES_FINDERS:

STATICFILES_FINDERS = [
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
    'openwisp_utils.staticfiles.DependencyFinder',
]

Add openwisp_utils.loaders.DependencyLoader to TEMPLATES:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'OPTIONS': {
            'loaders': [
                'django.template.loaders.filesystem.Loader',
                'django.template.loaders.app_directories.Loader',
                # add the following line
                'openwisp_utils.loaders.DependencyLoader'
            ],
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    }
]

Last step, add FORM_RENDERER:

FORM_RENDERER = 'django.forms.renderers.TemplatesSetting'

Then you can go ahead and create your admin.py file following the example below:

# admin.py of your app
from django.contrib import admin

from django_loci.base.admin import (AbstractFloorPlanAdmin, AbstractFloorPlanForm,
                                    AbstractFloorPlanInline, AbstractLocationAdmin,
                                    AbstractLocationForm, AbstractObjectLocationForm,
                                    AbstractObjectLocationInline)
from django_loci.models import FloorPlan, Location, ObjectLocation


class FloorPlanForm(AbstractFloorPlanForm):
    class Meta(AbstractFloorPlanForm.Meta):
        model = FloorPlan


class FloorPlanAdmin(AbstractFloorPlanAdmin):
    form = FloorPlanForm


class LocationForm(AbstractLocationForm):
    class Meta(AbstractLocationForm.Meta):
        model = Location


class FloorPlanInline(AbstractFloorPlanInline):
    form = FloorPlanForm
    model = FloorPlan


class LocationAdmin(AbstractLocationAdmin):
    form = LocationForm
    inlines = [FloorPlanInline]


class ObjectLocationForm(AbstractObjectLocationForm):
    class Meta(AbstractObjectLocationForm.Meta):
        model = ObjectLocation


class ObjectLocationInline(AbstractObjectLocationInline):
    model = ObjectLocation
    form = ObjectLocationForm


admin.site.register(FloorPlan, FloorPlanAdmin)
admin.site.register(Location, LocationAdmin)

Extending channel consumers

Extend the channel consumer of django-loci in this way:

from django_loci.channels.base import BaseLocationBroadcast
from ..models import Location  # your own location model


class LocationBroadcast(BaseLocationBroadcast):
    model = Location

Extending AppConfig

You may want to reuse the AppConfig class of django-loci too:

from django_loci.apps import LociConfig


class MyConfig(LociConfig):
    name = 'myapp'
    verbose_name = _('My custom app')

    def __setmodels__(self):
        from .models import Location
        self.location_model = Location

Installing for development

Install sqlite:

sudo apt-get install sqlite3 libsqlite3-dev libsqlite3-mod-spatialite gdal-bin

Install your forked repo:

git clone git://github.com/<your_fork>/django-loci
cd django-loci/
python setup.py develop

Install test requirements:

pip install -r requirements-test.txt

Create database:

cd tests/
./manage.py migrate
./manage.py createsuperuser

Launch development server and SMTP debugging server:

./manage.py runserver

You can access the admin interface at http://127.0.0.1:8000/admin/.

Run tests with:

# pytests is used to test django-channels
./runtests.py && pytest

Contributing

  1. Announce your intentions in the OpenWISP Mailing List
  2. Fork this repo and install it
  3. Follow PEP8, Style Guide for Python Code
  4. Write code
  5. Write tests for your code
  6. Ensure all tests pass
  7. Ensure test coverage does not decrease
  8. Document your changes
  9. Send pull request

Changelog

See CHANGES.

License

See LICENSE.

More Repositories

1

django-rest-framework-gis

Geographic add-ons for Django REST Framework. Maintained by the OpenWISP Project.
Python
1,081
star
2

openwisp-controller

Network and WiFi controller: provisioning, configuration management and updates, (pull via openwisp-config or push via SSH), x509 PKI management and more. Mainly OpenWRT, but designed to work also on other systems.
Python
556
star
3

ansible-openwisp2

Ansible role that installs and upgrades OpenWISP.
Python
477
star
4

openwisp-config

OpenWRT configuration agent for OpenWISP Controller
Lua
374
star
5

django-freeradius

Administration web interface and REST API for freeradius 3 build in django & python, development has moved to openwisp-radius
Python
365
star
6

openwisp-radius

Administration web interface and REST API for freeradius 3 build in django & python. Supports captive portal authentication, WPA Enerprise (802.1x), freeradius rlm_rest, social login, Hotspot 2.0 / 802.11u, importing users from CSV, registration of new users and more.
Python
363
star
7

netjsonconfig

Network configuration management library based on NetJSON DeviceConfiguration
Python
359
star
8

django-x509

Reusable django app implementing x509 PKI certificates management
Python
340
star
9

netjsongraph.js

NetJSON NetworkGraph visualizer.
JavaScript
270
star
10

django-netjsonconfig

Configuration manager for embedded devices, implemented as a reusable django-app
JavaScript
194
star
11

openwisp-network-topology

Network topology collector and visualizer. Collects network topology data from dynamic mesh routing protocols or other popular networking software like OpenVPN, allows to visualize the network graph, save daily snapshots that can be viewed in the future and more.
Python
170
star
12

openwisp-monitoring

Network monitoring system written in Python and Django, designed to be extensible, programmable, scalable and easy to use by end users: once the system is configured, monitoring checks, alerts and metric collection happens automatically.
Python
166
star
13

openwisp-users

Implementation of user management and multi-tenancy for OpenWISP
Python
163
star
14

docker-openwisp

OpenWISP in docker. For production usage we recommend using the ansible-openwisp2 role.
Python
153
star
15

django-netjsongraph

Network Topology Visualizer & Network Topology Collector
Python
141
star
16

openwisp-wifi-login-pages

Configurable captive page for public/private WiFi services providing login, sign up, social login, SMS verification, change password, reset password, change phone number and more.
JavaScript
128
star
17

ansible-openwisp2-imagegenerator

Automatically build several openwisp2 firmware images for different organizations while keeping track of their differences
Shell
120
star
18

openwisp-ipam

IP address space administration module of OpenWISP
Python
104
star
19

OpenWISP-Firmware

An OpenWRT based firmware to be used with OpenWISP Manager
Shell
86
star
20

netdiff

Python library for parsing network topology data (e.g.: OpenVPN, Wireguard, ZeroTier, NetJSON, Dynamic Routing Protocols) and detect changes.
Python
80
star
21

django-ipam

The development of this project has moved to openwisp-ipam
Python
78
star
22

openwisp-utils

Python and Django utilities shared between different openwisp modules
Python
74
star
23

django-flat-json-widget

Flat JSON widget for django, used and maintained by the OpenWISP project.
Python
64
star
24

OpenWISP-Captive-Portals-Manager

OWCPM is a captive portal written from scratch with Ruby on Rails.
Ruby
58
star
25

openwisp-firmware-upgrader

Firmware upgrade solution for OpenWRT with possibility to add support for other embedded OSes. Provides features like automatic retry for network failures, mass upgrades, REST API and more.
Python
53
star
26

openwisp-docs

OpenWISP Documentation.
Python
50
star
27

vagrant-openwisp2

Ansible Vagrant profile to install an OpenWISP 2 server
44
star
28

openwisp-notifications

Notifications module of OpenWISP
Python
41
star
29

OpenWISP-User-Management-System

OpenWISP User Management System (OWUMS) is a Ruby on Rails application, capable of managing a WISP's user base.
Ruby
40
star
30

OpenWISP-Website

OpenWISP Project's website
HTML
39
star
31

netengine

Python abstraction layer for extracting information from network devices.
Python
38
star
32

OpenWISP-Manager

The OpenWISP Manager is a RoR web GUI for configuring OpenWISP firmware-based access points.
Ruby
36
star
33

openwrt-openwisp-monitoring

OpenWRT monitoring agent for openwisp-monitoring
Lua
23
star
34

luci-openwisp

OpenWISP configuration interface implemented as LuCI extensions
HTML
20
star
35

django-owm-legacy

OpenWISP Manager backward compatible legacy features implemented in django
Python
17
star
36

OpenWISP-Geographic-Monitoring

A Rails application for managing a wISP's access points
Ruby
15
star
37

coova-chilli-openwrt

Makefile
13
star
38

openwrt-zabbixd

Ucified Zabbix Packages
Makefile
13
star
39

netjsonconfig-editor.js

[GSOC 2017] This project has stalled.
JavaScript
12
star
40

django-jsonschema-widget

JavaScript
11
star
41

OpenWISP-Middle-Ware

A Sinatra application for interconnecting OpenWISP applications via a RESTful API
Ruby
11
star
42

OpenWISP-Puppet-Modules

A set of modules and hacks for the https://openwisp.caspur.it project
HTML
10
star
43

AdaLoveBot-intents

Helping bot of the OpenWISP Chat
JavaScript
9
star
44

ansible-freeitaliawifi-login-page

Standard login page for Free ItaliaWifi federated networks
JavaScript
9
star
45

openwisp-netcheck

Shell
9
star
46

openwisp-template-library-backend

Python
8
star
47

netjson-templates

CSS
6
star
48

ansible-wireguard-openwisp

Python
6
star
49

openwisp-template-library-frontend

GSOC 19
JavaScript
6
star
50

OpenWISP-ETL

Extract Transform Load Module developed with pentaho pdi ce-5.0.1.A
6
star
51

openVPNServer

Ruby
5
star
52

openwrt-feed

DEPRECATED, work moved on OpenWisp-Firmware repo
Shell
5
star
53

ansible-openwisp-wifi-login-pages

Ansible role to deploy and manage OpenWISP WiFi Login Pages
Jinja
5
star
54

lxdock-openwisp2

This repository is only a mirror. If you want to work on it, make a fork on https://gitlab.com/openwisp/lxdock-openwisp2
5
star
55

packet-legacy

packet-legacy
Ruby
4
star
56

ansible-ow-influxdb

4
star
57

OpenWISP-BI

Business Intelligence module developed with pentaho biserver ce-4.8.0
4
star
58

openwisp-sphinx-theme

OpenWISP Sphinx Theme
CSS
3
star
59

openwisp-dev-env

Automated development environment for OpenWISP, work in progress.
3
star
60

openwisp-sentry-utils

Python
2
star
61

ansible-openwisp2-iptables

ansible role containing iptables rules to protect an openwisp2 instance
Shell
2
star