Support local files

app/action/option.go

@@ -13,6 +13,7 @@ var StartOption struct {
 	Port               int
 	Readonly           bool
 	OnlineSegmentation string
+	DataDir            string
 }
 
 var ImportOption struct {

app/action/start.go

@@ -66,6 +66,12 @@ func Start(ctx context.Context) error {
 	}
 	e.Use(middlewares...)
 
+	// local data
+	if StartOption.DataDir != "" {
+		zap.L().Info("serving local data", zap.String("dir", StartOption.DataDir))
+		e.Static("/local", StartOption.DataDir)
+	}
+
 	// backend
 	s, teardown, err := createServer()
 	if err != nil {
@@ -105,6 +111,7 @@ func createServer() (nutshapi.ServerInterface, func(), error) {
 		backend.WithPublicStorage(localfs.NewPublic(publicDir(), publicUrlPrefix)),
 		backend.WithSampleStorage(localfs.NewSample(sampleDir())),
 		backend.WithOnlineSegmentationServerAddr(StartOption.OnlineSegmentation),
+		backend.WithDataDir(StartOption.DataDir),
 		backend.WithConfig(&nutshapi.Config{
 			Readonly:                  StartOption.Readonly,
 			OnlineSegmentationEnabled: StartOption.OnlineSegmentation != "",

app/backend/option.go

@@ -16,6 +16,7 @@ type Options struct {
 	config *nutshapi.Config
 
 	onlineSegmentationServerAddr string
+	dataDir                      string
 }
 
 func (o *Options) Validate() error {
@@ -73,3 +74,9 @@ func WithOnlineSegmentationServerAddr(addr string) Option {
 		o.onlineSegmentationServerAddr = addr
 	}
 }
+
+func WithDataDir(dir string) Option {
+	return func(o *Options) {
+		o.dataDir = dir
+	}
+}

app/backend/segmentation.go

@@ -10,7 +10,10 @@ import (
 	"nutsh/openapi/gen/nutshapi"
 	schemav1 "nutsh/proto/gen/schema/v1"
 	servicev1 "nutsh/proto/gen/service/v1"
+	"os"
 	"path"
+	"path/filepath"
+	"strings"
 
 	"github.com/labstack/echo/v4"
 	"github.com/pkg/errors"
@@ -136,7 +139,7 @@ func (s *mServer) onlineSegmentationEmbed(ctx context.Context, request nutshapi.
 	hasCrop := (w > 0 && h > 0)
 
 	imUrl := request.Params.ImageUrl
-	im, err := downloadImage(ctx, imUrl)
+	im, err := s.loadImage(ctx, imUrl)
 	if err != nil {
 		return nil, err
 	}
@@ -202,6 +205,25 @@ func (s *mServer) onlineSegmentationEmbed(ctx context.Context, request nutshapi.
 	}, nil
 }
 
+func (s *mServer) loadImage(ctx context.Context, url string) ([]byte, error) {
+	localPrefix := "file://"
+	if strings.HasPrefix(url, localPrefix) {
+		// the image should be loaded from data dir
+		relPath := strings.TrimPrefix(url, localPrefix)
+		dir := s.options.dataDir
+		if dir == "" {
+			return nil, errors.Errorf("missing data dir to load local image [%s]", relPath)
+		}
+		fpath := filepath.Join(dir, relPath)
+		data, err := os.ReadFile(fpath)
+		if err != nil {
+			return nil, errors.WithStack(err)
+		}
+		return data, nil
+	}
+	return downloadImage(ctx, url)
+}
+
 func downloadImage(ctx context.Context, url string) ([]byte, error) {
 	zap.L().Info("downloading image", zap.String("url", url))
 

app/frontend/src/state/image/store.ts

@@ -4,7 +4,14 @@ import {useQuery, QueryClient} from '@tanstack/react-query';
 const client = new QueryClient();
 const context = createContext<QueryClient | undefined>(client);
 
-const query = (url: string) => {
+const query = (u: string) => {
+  let url = u;
+
+  const localPrefix = 'file://';
+  if (u.startsWith(localPrefix)) {
+    url = `/local/${u.substring(localPrefix.length)}`;
+  }
+
   return {
     queryKey: ['downloadImage', url],
     queryFn: async () => await (await fetch(url)).blob(),

docs/docs/03-Usage/02-Resource.mdx

@@ -7,3 +7,47 @@ Resources refer to objects that are to be annotated, such as images, videos, poi
 Through the user interface, you can effortlessly create, search for, update, and delete videos.
 
 <VideoPlayer url="https://nutsh-public.s3.eu-central-1.amazonaws.com/doc/video/manage_videos.mp4" />
+
+## Loading Local Files
+
+Resource assets are specified by their URLs, e.g. a video is represented by a list of urls of its frames.
+By default, the URL should use the HTTP protocol, which isn't convenient for directly loading local files.
+You can take the following steps to work with local files.
+
+1. Start nutsh with an additional flag `--data-dir [data_dir]` pointing to some directory where your data is located.
+2. Use `file://[rel_path]` as the URL for your resources, which will point to the file at `[data_dir]/[rel_path]` on your local machine.
+
+For instance, if you're working with videos stored in
+
+```
+/var/data/abc
+    - video0001
+        - frame0001.jpg
+        - frame0002.jpg
+        - ...
+    - video0002
+        - frame0001.jpg
+        - frame0002.jpg
+        - ...
+    - ...
+```
+
+Start nutsh with the flag `--data-dir /var/data/abc`, and create your videos with urls like
+
+```
+file://video0001/frame0001.jpg
+file://video0001/frame0002.jpg
+...
+```
+
+:::caution
+
+Always use relative paths. Namely, a local url should never start with `file:///` but only two slashes `file://`.
+
+:::
+
+:::danger
+
+You may use `--data-dir /` to serve files with absolute paths, like `file://var/data/abc/video0001/frame0001.jpg`, but do note that it exposes security risks for your host machine.
+
+:::

main.go

@@ -62,6 +62,12 @@ func main() {
 				EnvVars:     []string{"NUTSH_ONLINE_SEGMENTATION"},
 				Destination: &action.StartOption.OnlineSegmentation,
 			},
+			&cli.StringFlag{
+				Name:        "data-dir",
+				Usage:       "data directory to serve local files under `file://`",
+				EnvVars:     []string{"NUTSH_DATA_DIR"},
+				Destination: &action.StartOption.DataDir,
+			},
 		},
 		Commands: []*cli.Command{
 			{