No project description provided
Project description
django-large-image
Image tile serving in Django made easy
django-large-image
is an abstraction of large-image
for use with django-rest-framework
providing view mixins for endpoints to
work with large images in Django -- specifically geared towards geospatial and
medical image tile serving.
Created by Kitware, Inc.
OpenAPI Documentation | Tiles Endpoint |
---|---|
Overview
This package ports Kitware's large-image to Django by providing a set of abstract, mixin API view classes that will handle tile serving, fetching metadata from images, and extracting regions of interest.
django-large-image
is an optionally installable Django app with
a few classes that can be mixed into a Django project (or application)'s
drf-based views to provide tile serving endpoints out of the box. Notably,
django-large-image
is designed to work specifically with FileFeild
interfaces with development being tailored to Kitware's
S3FileField
. We are working
to also support GeoDjango's GDALRaster
in the future
This package ships with pre-made HTML templates for rendering geospatial image tiles with CesiumJS and non-geospatial image tiles with GeoJS.
Features
Rich set of RESTful endpoints to extract information from large image formats:
- Image metadata (
/metadata
,/internal_metadata
) - Tile serving (
/tiles/{z}/{x}/{y}.png?projection=EPSG:3857
) - Region extraction (
/region.tif?left=v&right=v&top=v&bottom=v
) - Image thumbnails (
/thumbnail
) - Individual pixels (
/pixel?left=v&top=v
) - Band histograms (
/histogram
)
Support for general FileFeild's or File URLs
- Supports django's FileFeild
- Supports
S3FileField
- Supports GDAL's Virtual File System for
s3://
,ftp://
, etc. URLs
Miscellaneous:
- Admin interface widget for viewing image tiles.
- Caching - tile sources are cached for rapid file re-opening
- tiles and thumbnails are cached to prevent recreating these data on multiple requests
- Easily extensible SSR templates for tile viewing with CesiumJS and GeoJS
- OpenAPI specification
Installation
Out of the box, django-large-image
only depends of the core large-image
module, but you will need a large-image-source-*
module in order for this
to work. Most of our users probably want to work with geospatial images so we
will focus on the large-image-source-gdal
case, but it is worth noting that
large-image
has source modules for a wide variety of image formats
(e.g., medical image formats for microscopy).
See large-image
's
installation instructions for more details.
Tip: installing GDAL is notoriously difficult, so at Kitware we provide
pre-built Python wheels with the GDAL binary bundled for easily installation in
production environments. To install our GDAL wheel, use: pip install --find-links https://girder.github.io/large_image_wheels GDAL
pip install \
--find-links https://girder.github.io/large_image_wheels \
django-large-image \
large-image-source-gdal
Usage
Simply install the app and mixin the LargeImageView
class to your existing
django-rest-framework
viewsets and specify the FILE_FIELD_NAME
as the
string name of the FileField
in which your image data are saved.
# settings.py
INSTALLED_APPS = [
...,
'django_large_image',
]
# viewsets.py
from django_large_image.rest import LargeImageView
class MyModelViewset(viewsets.GenericViewSet, LargeImageView):
... # configuration for your model's viewset
FILE_FIELD_NAME = 'field_name'
And that's it!
Example Code
To use the mixin classes provided here, create a model, serializer, and view in your Django project like so:
# models.py
from django.db import models
from rest_framework import serializers
class ImageFile(models.Model):
name = models.TextField()
file = models.FileField()
class ImageFileSerializer(serializers.ModelSerializer):
class Meta:
model = ImageFile
fields = '__all__'
# admin.py
from django.contrib import admin
from example.core.models import ImageFile
@admin.register(ImageFile)
class ImageFileAdmin(admin.ModelAdmin):
list_display = ('pk', 'name')
Then create the viewset, mixing in the django-large-image
view class:
# viewsets.py
from example.core import models
from rest_framework import mixins, viewsets
from django_large_image.rest import LargeImageView
class ImageFileDetailView(
mixins.ListModelMixin,
viewsets.GenericViewSet,
LargeImageView,
):
queryset = models.ImageFile.objects.all()
serializer_class = models.ImageFileSerializer
# for `django-large-image`: the name of the image FileField on your model
FILE_FIELD_NAME = 'file'
Then register the URLs:
# urls.py
from django.urls import path
from example.core.viewsets import ImageFileDetailView
from rest_framework.routers import SimpleRouter
router = SimpleRouter(trailing_slash=False)
router.register(r'api/image-file', ImageFileDetailView, basename='image-file')
urlpatterns = [
path('', include('django_large_image.urls')), # Additional diagnostic URLs from django-large-image
] + router.urls
You can also use an admin widget for your model:
<!-- templates/admin/myapp/imagefile/change_form.html -->
{% extends "admin/change_form.html" %}
{% block after_field_sets %}
<script>
var baseEndpoint = 'api/image-file';
</script>
{% include 'admin/django_large_image/_include/geojs.html' %}
{% endblock %}
Please note the example Django project in the project/
directory of this
repository that shows how to use django-large-image
in a girder-4
project.
Customization
The LargeImageView
is modularly designed and able to be subclassed for your
project's needs. While the provided LargeImageView
handles
FileFeild
-interfaces, you can easily extend it to handle any mechanism of
data storage.
In the following example, I will show how to use GDAL compatible VSI paths
from a model that stores s3://
or https://
URLs.
# model.py
from django.db import models
from rest_framework import serializers
class URLImageFile(models.Model):
name = models.TextField()
url = models.TextField()
class URLImageFileSerializer(serializers.ModelSerializer):
class Meta:
model = URLImageFile
fields = '__all__'
# viewsets.py
from example.core import models
from rest_framework import mixins, viewsets
from django_large_image.rest import LargeImageViewMixin
from django_large_image.utilities import make_vsi
class URLLargeImageViewMixin(LargeImageViewMixin):
def get_path(self, request, pk):
object = self.get_object()
return make_vsi(object.url)
class URLImageFileDetailView(
mixins.ListModelMixin,
viewsets.GenericViewSet,
URLLargeImageViewMixin,
):
queryset = models.URLImageFile.objects.all()
serializer_class = models.URLImageFileSerializer
Here is a good test image: https://oin-hotosm.s3.amazonaws.com/59c66c5223c8440011d7b1e4/0/7ad397c0-bba2-4f98-a08a-931ec3a6e943.tif
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for django_large_image-0.2.4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 106bc56c631f73e1830e67005dcc224b0879aeb30a937f51dd54fbd22a02b0be |
|
MD5 | 0bab7885f5ea37ec8ac53c2b138e8455 |
|
BLAKE2b-256 | 7489765308784281c7206cddac7492d2b98cac8a9d6fa0bac281153d6ef92d20 |